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 (.aidlc/resources/rules/context.md).

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 (.aidlc/resources/rules/always-read.md) 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.
    • Test the shape. A WHEN/WHILE/IF/WHERE criterion names its own test: set up the condition, assert the SHALL response. An IF criterion is tested by causing the unwanted condition, not by the happy path.
    • Unchanged behaviour (bugfix). Each criterion in that section of requirements.md gets a test that passes before the fix and after it. Run it once against the unfixed code to see it pass.
  3. Run tests. Execute the project's test suite. All new tests must pass.
    • Verified mode. When .aidlc/config.yaml sets assurance: { default: verified }, the testing gate accepts only a receipt the CLI wrote. Commit the code under test, then run aidlc verify <instance>: it runs verify.command and writes receipt.json in the instance state directory. The gate refuses a receipt that failed, was taken with uncommitted changes, ran a different command, or predates a later change outside the instance state directory — re-run aidlc verify after any such change. Never write or edit receipt.json yourself, and never change verify.command; a person sets it.
  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

Unattended (AIDLC_UNATTENDED=1): nobody can confirm, so everything this section asks to confirm is a hard stop, per .aidlc/resources/rules/unattended.md.

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.

Unattended (AIDLC_UNATTENDED=1): this is the release boundary. Write the deployment record's release plan and end the session — no push, pull request, merge or release — per .aidlc/resources/rules/unattended.md.

Then end the turn as The next-steps rule (.aidlc/resources/rules/next-steps.md) says.

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.