Testing

Testing conventions, folder guidelines, and Python execution rules.

When to Use

• •Creating or running unit tests
• •Setting up test infrastructure for a module
• •Running Python commands in terminals
• •Deciding between tests/ and playground/ folders
• •Managing HyperRed adversarial testing artifacts

Testing Folder Decision Tree

Step 1: Is this a one-off scratch file?

• •YES → Use .temp_agent_work/ (MUST clean up after session)
• •NO → Continue

Step 2: Am I HyperRed running adversarial attacks?

• •YES → Use .agent_plan/red_team/<module>/
• •NO → Continue

Step 3: Is this a FORMAL test case for pytest/CI?

• •YES → Step 3a: Does it test ONE module in isolation?
  • •YES → Use <module>/tests/
  • •NO → Use tests/integration/
• •NO → Continue

Step 4: Is this exploratory code (demos, experiments)?

• •YES → Step 4a: Does it explore ONE module's API?
  • •YES → Use <module>/playground/
  • •NO → Use playground/ (project-level)
• •NO → Reconsider: What is this file for?

Folder Responsibility Matrix

Quick Reference

tests/ vs playground/

Rule: If it should run in CI → tests/. If it's for humans to explore → playground/.

HyperRed Artifact Conventions

.agent_plan/red_team/<module_name>/
├── attacks/     # Generated attack scripts (persist for re-runs)
├── findings/    # Structured JSON per session (YYYY-MM-DD_findings.json)
└── evidence/    # Crash logs, stderr captures (gitignored)

Git Tracking: Track attacks/ and findings/. Ignore evidence/.

Before Attacking a Module

1. •Check if .agent_plan/red_team/<module>/findings/ exists
2. •If previous findings exist, review before re-attacking (avoid duplicate work)
3. •Create attack scripts in attacks/ folder
4. •Log all evidence to evidence/ folder

Findings Output

Write findings to .agent_plan/red_team/<module>/findings/YYYY-MM-DD_findings.json. Always update latest_findings.json as a reference point.

Cleanup Responsibilities

Before Creating Test Files

1. •Check existing tests: Search <module>/tests/ and tests/integration/ first
2. •Check HyperRed findings: Look at .agent_plan/red_team/<module>/findings/
3. •Reuse before creating: Don't duplicate existing test coverage

Python Terminal Commands

Rule 1: ALWAYS Activate Virtual Environment

When using run_in_terminal to execute Python commands, ALWAYS activate .venv first.

Pattern 1 (Recommended): Chain activation with command

source .venv/bin/activate && python <command>

Pattern 2 (Alternative): Use venv Python directly

.venv/bin/python <command>

Rule 2: Apply to ALL Python Executables

This rule applies to:

• •python or python3 script execution
• •pip install package installation
• •pytest test execution
• •python -m <module> module execution
• •Any Python-based CLI tools

Examples

CORRECT:

# Running a script
source .venv/bin/activate && python adhd_framework.py refresh

# Installing packages
source .venv/bin/activate && pip install requests

# Running pytest
source .venv/bin/activate && pytest tests/

# Running module
source .venv/bin/activate && python -m stocks_data_manager

INCORRECT:

# Missing venv activation
python adhd_framework.py refresh
pip install requests
pytest tests/

Why This Matters

• •Prevents "module not found" errors
• •Ensures consistent dependency resolution
• •All Python commands execute within the project's virtual environment