Skip to content

skill · phase: testing

Testing Phase

Purpose

Verify that the implementation satisfies all acceptance criteria. Produce evidence of correctness through automated tests and manual verification where needed.

Entry Criteria

  • Implementation phase complete
  • The instance is claimed by this session

Entering in a fresh session

Testing averages 344k tokens today, more than twice implementation's start, almost entirely inherited. Read only:

  • instance.yaml
  • requirements.md — the acceptance criteria, which are what tests are traced to
  • code-complete.md — what implementation says it delivered
  • tasks.md — which tasks claim which criteria

Not design.md: the design's job ended when the code existed, and the test verifies the code against the requirements. Not the implementation conversation. See The context rule in aidlc-overview.

Required Artifacts

  • Test files covering acceptance criteria
  • The artifacts your template's testing phase declares in required_artifacts — test-results.md for every built-in template. Read phase-testing.yaml in the instance state dir if unsure. Whatever the filename, the content is the test plan, results summary, and coverage notes.

Instructions

{{glossary:gate}} {{glossary:artifact}}

  1. Review acceptance criteria. Read requirements.md (or task description for Micro scope). Each criterion needs at least one test. Read the always-read guidance layers from .aidlc/guidance/index.yaml — see The always-read rule in aidlc-overview for which layers those are and when to reach for the full lessons.md.
  2. Write automated tests. Follow the project's existing test patterns:
    • Unit tests for pure logic and edge cases
    • Integration tests for component interactions
    • Property-based tests where inputs have broad domains
    • Reference AC IDs. When requirements.md defines AC-n criteria, each test names the criteria it verifies — in the test name or a comment (e.g. // AC-3). The testing-phase gate scans test files for these references and fails on any active criterion with none. If two instances define the same ID, qualify the reference as <instance>/AC-n.
  3. Run tests. Execute the project's test suite. All new tests must pass.
  4. Document results. Write the phase's required artifact (see Required Artifacts above) with:

    • Test plan (what was tested and why)

    • Results (pass/fail counts, any notable findings)

    • Coverage notes (which criteria are covered, any gaps)

    • ac-coverage block for indirect coverage. A criterion verified manually or outside scannable test files is claimed in a fenced code block whose info string is ac-coverage, one AC-<n>: <evidence> line per entry — the gate unions these with scanned references:

      AC-7: verified manually — see results table above
  5. Address failures. If tests reveal bugs, fix the implementation. Do not skip or weaken tests to force a pass.

Exit Criteria

  • All acceptance criteria have corresponding test coverage
  • All tests pass
  • Every artifact the template's testing phase requires exists, with a results summary
  • No critical bugs remain open

Guidance

{{context:style-guide}} {{guidance:secure-defaults}}

Security Testing

When the work under test touches a trust boundary (user input, auth, file paths, subprocess or query construction, deserialization), the suite MUST include negative security tests, not only happy paths:

  • Inputs crafted to escape the intended context: injection payloads for shell, SQL, path (../), and template sinks the code actually has
  • Requests without credentials, and with valid credentials for the WRONG user or role, asserting they are rejected
  • Malformed and boundary inputs (empty, oversized, wrong type) asserting safe failure — no stack traces or internals in the response

Run the project's dependency audit (e.g. npm audit, pnpm audit) once per testing phase and record newly introduced advisories as findings.

Security Confirmation

If testing requires:

  • Access to production-like environments
  • Use of real credentials or sensitive data
  • Execution of destructive operations (even in test environments)

You MUST describe the action, confirm it targets a safe environment, and wait for user acknowledgment before proceeding.

Completion

When exit criteria are met, update phase-testing.yaml status to complete and append a transition record to transitions.log.

Changing a completed phase's artifact. Do it only through an amendment — append an ## Amendment <n> — YYYY-MM-DD section to requirements.md with Retires:, Issues:, Reopens: and Reason: bullets, then run aidlc amend <instance> (start with --impact to see what still cites the retired criteria). Editing the artifact directly leaves every gate passing while the requirements and the code disagree.