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.