test-matrix

Test Matrix

For each changed unit/function, provide this matrix before coding tests:

Categories

1. Success path: expected output and side effects.
2. Boundary values: min, max, empty, zero, one, large input.
3. Guard clauses: invalid type/shape/range; missing required values.
4. Failure paths: downstream failure, timeout, retries exhausted.
5. State transitions: create/update/delete/retry/idempotency.
6. Determinism: stable behavior across repeated runs.

Output format

## Test Matrix: <unit>

Case:

• Category: success|boundary|guard|failure|state|determinism
• Input:
• Expected output:
• Observable side effect: <what changes in the world — DB row, file, container state, stdout>
• Assertion strategy: <which assertion level from policy-core, and why>
• Mock boundary: <what is mocked and why, or "none — real implementation">

## Assertion strategy guide

Follow the assertion hierarchy and mock rules defined in the `policy-core` skill.

For each test case, explicitly state HOW you will verify it, preferring Level 1-5 (behavior) assertions over Level 6-7 (wiring) assertions per `policy-core`:

| If testing... | Assert via... | NOT via... |
|--------------|---------------|------------|
| Return value | `expect(result).toEqual(...)` | Mock call args |
| Error thrown | `expect(() => fn()).toThrow(ErrorType)` | Mock call count |
| Formatted output | `expect(formatter.success).toHaveBeenCalledWith("Mecha started")` + `expect(result.id)` | Mock call args alone |
| Docker state | `inspectContainer()` or integration test | `expect(mockCreate).toHaveBeenCalledWith(...)` |
| File written | Read file back and verify content | `expect(mockWriteFile).toHaveBeenCalled()` |
| DB state | Query the DB and verify rows | `expect(mockInsert).toHaveBeenCalled()` |
| Stream output | Write to stream, collect output, verify content | `expect(mockStream.on).toHaveBeenCalled()` |

## Mock decision tree

Apply the mock rules from `policy-core`. Before adding a mock, answer:

1. **Can I use the real thing?** (in-memory DB, tmpdir, real Zod parse) → Use real.
2. **Is it a system boundary?** (Docker daemon, network, child process) → Mock is OK.
3. **Is it my own code?** (another module in this repo) → Do NOT mock. Use the real module.
4. **Is it non-deterministic?** (Date.now, crypto.random) → Spy/stub the specific call.

If you mock, you MUST also have an integration test (gated behind `INTEGRATION=true`) that tests the real path.