Testing Guide

Run Tests

Run the full suite:

python -m pytest

Run a focused file:

python -m pytest tests/test_scope_gate.py

Run a specific test:

python -m pytest tests/test_attack_modules.py::TestModuleRegistry::test_list_modules_returns_all

Run smoke checks:

python main.py --doctor
python main.py --self-test

Coverage (matches CI; pytest-cov is not a dependency, so pytest --cov fails):

python -m coverage run -m pytest tests/
python -m coverage report

What To Test By Change Type

The suite has 342 files (all mock subprocess/network — no live Nmap); this table covers the most common change types grouped by feature. When in doubt, grep tests/ for the module name. Run python -m pytest tests/ -v for the full list; focused: python -m pytest tests/test_scope_gate.py -v.

Test Workspace Pattern

Many tests use temporary or dedicated workspaces. Keep this pattern:

• Use temporary directories for generated files.
• Avoid writing into real reports/ or exploit_workspace/ unless a test is explicitly checking that behavior.
• Use localhost or mocked command execution for network/security tests.
• Keep regression fixtures small and readable.

External Dependencies

Some runtime features require tools that may not be present on every developer machine:

• nmap
• Ollama and configured models
• Metasploit
• searchsploit
• system package managers
• Unix session tooling

Unit tests should mock these where possible. --doctor and --self-test are the right place to validate local machine readiness.

Outcome-Judgment Regressions

tests/test_outcome_judge.py is deterministic and requires no network tools or model. It covers execution/evidence separation, matching and contradictory structured evidence, single versus repeated inconclusive attempts, duplicate check rejection, terminal-state planning guards, restart persistence, and version-3 database migration. Existing scope, approval, target-lock, and risk tests remain the safety regression suite; outcome judgment does not replace those gates.

Before Handoff

For small changes, run the focused tests that match the touched module.

For cross-cutting changes, run:

python -m pytest
python main.py --doctor
python main.py --self-test

If a command cannot run because a local external tool is missing, note that in the handoff and include the focused tests that did run.