computer-playbook/docs/agents/action/testing.md

Testing

Filesystem Scans: Use the Shared Cache

• When writing or modifying a test that scans the project tree, you MUST route the walk and file reads through utils.cache.files, specifically iter_project_files(...), iter_project_files_with_content(...), or read_text(...). You MUST NOT introduce raw os.walk(<project-root>), Path(<project-root>).rglob("*"), or broad un-scoped globs on the repo tree in test code.
• Reason: pytest runs every test in one process. Without a shared cache each test re-walks the same tree and re-reads the same files; the walk cost multiplies by the number of tests that use it. Migrating a single test from a raw walk to iter_project_files_with_content dropped it from ~26 s to ~1.3 s because every subsequent test served the walk and the file contents from the process-level cache.
• When to skip the rule: narrow globs that hit a fixed small set of paths (e.g. roles_dir.glob("*/meta/services.yml")) do not benefit meaningfully; walks inside an isolated tempfile.TemporaryDirectory() fixture are out of scope because the cache is read-only by design. Even in those cases, use utils.cache.files.read_text for individual file contents so other tests reading the same path get a cache hit.
• API reference: iter_project_files(extensions=…, exclude_tests=…, exclude_dirs=…) yields absolute paths, the walk is cached once per process. iter_project_files_with_content(…) yields (path, content) with both layers cached. read_text(path) returns cached UTF-8 content. The walker automatically prunes .git, .cache, .pytest_cache, .ruff_cache, .venv, venv, __pycache__, and node_modules.

Test Changes

• After every change to a test file, you MUST run the corresponding validation command before continuing with any further action. Use the suite-selection rules in Testing and Validation.
• You MUST NOT run more than one unit test command at the same time. Unit tests MUST be executed serially, never in parallel.
• If a new test is created or an existing test has been changed since the last test run, you MUST rerun it after every subsequent action until it passes.
• If the last test run for a test failed, you MUST rerun it after every change until it succeeds.

Commits

• make test is enforced automatically by the pre-commit hook before every commit for changes that include at least one file that is not .md, .rst, or .txt. You do NOT need to run it manually.
• For markdown/reStructuredText/text-only changes, the hook skips make test automatically.
• If the pre-commit hook warns about a staged file or its role, you MUST ask whether to fix that warning before you continue.
• Keep the follow-up limited to the roles touched by staged files so the change stays focused.

On Failure

• If that validation fails, you MUST run make clean and rerun it.
• If the failure says service "infinito" is not running, restart the stack with Development Environment Setup and retry the validation.