Testing

PREREQUISITE: Read the methodology reference before writing any test:

• ${SKILL_DIR}/references/methodology.md — 5-stage router, 5 factors, 7 exceptions, test double taxonomy

Then follow the spec-tree workflow below.

Step 1: Load tree context

Check for <SPEC_TREE_FOUNDATION> and <SPEC_TREE_CONTEXT> markers. If absent, invoke /understanding and /contextualizing first.

This loads:

• The target spec node and its assertions
• Ancestor ADRs/PDRs that constrain the testing approach
• Lower-index sibling specs that provide context

Step 2: Extract assertions from the spec

Parse the target spec node. Extract all typed assertions and their test links:

Record each assertion with:

• Assertion text
• Assertion type
• Test link (if present) — path and whether it resolves
• Test link status: exists / missing / stale

Step 3: Analyze evidence gaps

For each assertion:

Report the evidence gap summary before proceeding.

Step 4: Route each assertion through the methodology

For each assertion that needs a test, apply the 5-stage router from ${SKILL_DIR}/references/methodology.md:

1. Stage 1 — What evidence does this assertion demand?
2. Stage 2 — At what level does that evidence live? (Use 5 factors. Respect ADRs/PDRs loaded from tree context.)
3. Stages 3–5 — If Level 1: classify the code, check real system viability, match exception if needed.

Document the routing decision for each assertion.

Step 5: Generate test scaffolds

For each assertion needing a new test:

1. Determine test pattern from assertion type (Step 2 table).
2. Determine test level from methodology routing (Step 4).
3. Create test file in the spec node's tests/ directory.
4. Name the file using level suffix: test_{slug}_unit.py, test_{slug}_integration.py, etc.
5. Scaffold the test structure based on assertion type and language-specific patterns.

Delegate language-specific patterns to /testing-python or /testing-typescript.

Specified nodes: If the implementation module doesn't exist yet, test files will fail on import. This is expected — the test is a declaration of what the implementation must satisfy. Add the node's path to spx/EXCLUDE and run the project's sync command so the quality gate excludes these tests. Remove the entry when implementation begins. See ${SKILL_DIR}/../understanding/references/excluded-nodes.md.

Step 6: Update spec assertion links

After creating test files, update the spec to add ([test](tests/{filename})) links for each new assertion-test pair. Every assertion must link to at least one test file.

Step 7: Report evidence summary

Report which assertions have tests, which don't, which are stale:

| # | Assertion | Type     | Level | Test File | Status  |
| - | --------- | -------- | ----- | --------- | ------- |
| 1 | {text}    | Scenario | 1     | {file}    | Covered |
| 2 | {text}    | Property | 1     | —         | Missing |

When an assertion lives in an ancestor node (cross-cutting), determine where the test evidence should go:

• If the assertion is about behavior that a specific child node implements, the test belongs in that child's tests/ directory.
• If the assertion spans multiple children, the test belongs in the ancestor's tests/ directory at a higher level.
• If an ancestor accumulates too many cross-cutting assertions, flag it — the tree may need an extracted shared enabler at a lower index.

Testing is complete when:

• Tree context loaded (foundation markers present)
• All assertions extracted from spec with types identified
• Evidence gaps analyzed and reported
• Each assertion routed through 5-stage methodology
• Test scaffolds created for missing assertions
• Spec assertion links updated to point to test files
• Evidence summary reported
• No test doubles without matching exception case (documented in comments)
• Property-based tests present for parsers, serializers, math operations, complex algorithms