| name | qa-test |
| description | Writes an effective automated test suite - testing pyramid, behavior over implementation, deterministic tests. Loads a stack reference (e.g. typescript). Use when adding or improving tests. |
| argument-hint | <stack> |
Writing an automated test suite
Build a fast, trustworthy safety net that tests behavior, not implementation, and fails for exactly one reason. Apply test-principles (the testing philosophy) and dev-principles (the least test code that pins the behavior).
Use when writing or restructuring tests. For hands-on bug-hunting see qa-explore; for verifying a change against acceptance criteria see qa-review; for reviewing the source itself see develop-review.
Stack guidance
Load references/typescript.md for the target stack's test runner and idioms (add more stacks as reference files); with no file for the user's stack, apply the principles below and say so.
Test design (beyond test-principles)
test-principles covers behavior-over-implementation, determinism, the pyramid/risk balance, property-based testing, and the regression-test-per-fix rule. In addition:
- One reason to fail per test. Arrange-act-assert; a name that states the expected behavior, so a failure names the cause.
- Test the boundaries and every state. Empty, error, permission, and edge inputs (zero/one/many, long, unicode) - not just the happy path.
- Fake only at real seams. Stub the clock, network, or filesystem; do not mock internal collaborators - over-mocking tests the mock and couples the test to the structure you want free to change.
Gotchas
- Testing implementation details or private internals makes the suite brittle and blocks refactoring; test the public contract.
- A flaky test erodes trust in the whole suite - quarantine and fix it, do not add a retry loop.
- 100% coverage with assertions that never fail is theater; assert the behavior, not mere execution.
- Slow tests do not get run; keep the unit layer fast so the feedback loop stays tight.
- A test that changes whenever the code is refactored is testing structure, not behavior - move it down or rewrite it against the contract.
