# Test Strategy

Use this standard whenever a chunk changes behavior, UI, auth, backend/API behavior, database access, integrations, Telegram behavior, workflow tooling, or developer/operator commands.

Validation passing is required, but it is not sufficient when the changed behavior has no meaningful coverage.

## Test Responsibilities

- Developer adds or updates tests when behavior changes.
- Developer updates the active chunk `## Test Impact` section before handoff.
- Developer explains why tests are not applicable when no test changes are made.
- QA reviews test adequacy and blocks when relevant coverage is missing, weak, stale, or not justified.
- Orchestrator ensures test impact is considered before completion and routes missing coverage back to Developer unless explicitly accepted as follow-up.
- Prompt Synthesizer may generate or refine test plans, but does not execute tests.

## Required Chunk Section

Chunks that change behavior, UI, auth, backend/API behavior, database access, integrations, Telegram behavior, workflow tooling, or developer/operator commands must include:

```md
## Test Impact

- Behavior Changed:
- Existing Tests Affected:
- New Tests Required:
- Regression Risks:
- Runtime Smoke Needed:
- Frontend/Browser Coverage Needed:
- Backend/API Coverage Needed:
- Scenario/Workflow Coverage Needed:
- Not-Applicable Rationale:
```

Use `Not applicable` only when the chunk cannot affect runtime behavior or operator behavior, and explain why.

## Lifecycle Enforcement

- Developer updates `## Test Impact` before handoff whenever scope, implementation, prompt output, helper output, or runtime behavior changes.
- `ai/commands/workflow-state.sh --ready-for-qa` may block behavior/tooling chunks when `## Test Impact` is missing, incomplete, or marked not applicable without a concrete rationale.
- QA reviews `## Test Impact` against the actual diff, acceptance criteria, validation evidence, and runtime smoke applicability.
- Orchestrator checks the workflow-state gate before completion and routes missing or weak Test Impact back to Developer.
- Documentation-only chunks may omit app tests, but they should still explain the not-applicable rationale when they change workflow policy or operator-facing output.

## Coverage Expectations

- Backend services/resolvers/controllers: unit tests for logic and GraphQL/API boundary tests for public behavior.
- Backend e2e/API flows: e2e coverage when requests cross modules, auth, database, GraphQL, or configuration boundaries.
- Backend/API scenarios: use deterministic scenario or smoke checks for bootstrap, health, auth/user/admin setup, GraphQL contract behavior, and database-sensitive regression flows that are larger than one unit or e2e assertion.
- Frontend components/UI flows: component tests for visible state, generated operation usage, and user actions; browser/runtime smoke for realistic workflow changes.
- Visible frontend UI changes: apply `ai/standards/ui-review.md`; UI review is mandatory and should run structural/DOM review, heuristics, browser smoke, and screenshot review in that order when applicable.
- Frontend browser smoke: use Playwright or another approved browser runner when UI changes need real browser feedback on app load, shell/layout rendering, console/page errors, viewport behavior, or user interaction that component tests cannot cover.
- Database/Prisma behavior: tests or smoke coverage for create/read/update/delete semantics and cleanup.
- Auth/security behavior: tests for success, denial, token/current-user behavior, and failure paths.
- Runtime/dev-server behavior: `yarn smoke:runtime` or a chunk-specific runtime smoke command.
- Local/dev auth/admin runtime smoke: follow `ai/standards/local-dev-auth-smoke.md`. Existing-admin login/current-user/admin verification using local `.env` credential names is the preferred default; guarded reset/seed scripts are recovery tools or explicitly scoped validation, not the first smoke step.
- Telegram/workflow tooling: shell scenario assertions and operator sanity checks for output quality.

## QA Blocking Rules

QA must block when:

- behavior changed and `## Test Impact` is missing.
- tests are marked not applicable without a concrete rationale.
- new behavior has no unit/e2e/smoke/scenario/browser coverage and no accepted follow-up.
- existing tests were weakened, removed, or bypassed without explicit approval.
- validation passes but no test exercises the changed behavior or operator output.

QA may accept documented follow-up coverage only when the risk is low, the gap is explicit, and the chunk does not claim full coverage.

Use these distinctions:

- Missing tests: required coverage is absent and no acceptable rationale or follow-up exists. This is normally blocking.
- Accepted follow-up tests: coverage is intentionally deferred, risk is explicitly low or bounded, and a backlog/follow-up chunk is identified.
- Not-applicable tests: the chunk cannot affect runtime, operator, integration, or user-facing behavior, and the rationale explains why.

## Existing-Feature Regression Hardening

- Existing uncovered behavior discovered during a chunk does not have to be fully fixed in that same chunk.
- High-risk existing gaps should become backlog chunks with risk-based priority.
- Prioritize auth, database writes, cross-layer API flows, smoke-user cleanup, runtime/dev-server behavior, and high-use UI workflows.
- Do not hide legacy gaps inside a PASS. Report them as non-blocking follow-ups only when the current change is still adequately covered.

## Examples

Backend/API change:
- Update or add service/resolver/controller tests for the changed behavior.
- Add e2e/API coverage when the request crosses auth, GraphQL, database, or configuration boundaries.
- Runtime smoke may be required for auth, database, or dev-server behavior.
- For backend scenario-sensitive changes, document fixture prefixes, records created, cleanup behavior, and whether `apps/backend/scenarios/README.md` guidance applies.

Frontend/UI change:
- Add component or browser coverage for visible states and user actions.
- Apply `ai/standards/ui-review.md` instead of relying only on component tests.
- Run runtime smoke when the change affects real frontend/backend integration or login/session behavior.
- Document viewport or UX sanity checks when visual workflow changes are not easily unit-tested.
- If Playwright/browser smoke is unavailable, state that explicitly in `## Test Impact` and identify whether the gap is acceptable for the chunk or needs a follow-up dependency/setup chunk.

Workflow tooling change:
- Add scenario assertions for canonical state, handoff, prompt, summary, or output-quality behavior.
- Operator Sanity should inspect actual helper output, not only shell syntax.
- App runtime smoke is normally not applicable unless the helper starts or validates the app.

Telegram helper change:
- Add shell tests or debug-command checks for command parsing, confirmation cleanup, and message formatting.
- Verify no secrets/tokens are printed.
- Runtime app smoke is not required unless Telegram behavior starts or validates app services.

## Handoff Rules

Developer handoffs should summarize:

- tests added or updated.
- tests intentionally not added and why.
- validation commands run.
- runtime smoke applicability.
- remaining accepted test gaps or follow-up chunks.