testing

# Testing Skill Standards and workflow for writing and running tests. Every feature must be tested. **Announce at start:** "I'm using testing skill to ensure proper test coverage." ## Trigger Conditions - Writing new tests for a feature or bug fix - Adding a new feature (must include tests) - Modifying logic that has existing tests (must update them) - Before claiming work is complete - Before committing code ## Framework **Vitest 4** — configured in `vitest.config.ts`. ## Test Structure ``` tests/ ├── unit/ # Individual functions, utilities, components ├── integration/ # IPC, database, service interactions ├── regression/ # Regression test cases └── e2e/ # End-to-end tests (Playwright, playwright.config.ts) ``` ## Two Test Environments | Environment | When | File naming | | ---------------- | --------------------------------- | --------------- | | `node` (default) | Main process, utilities, services | `*.test.ts` | | `jsdom` | DOM/browser-dependent code | `*.dom.test.ts` | ## Workflow ### Step 1: Identify What to Test Before writing tests, list the **riskiest scenarios** first: - What happens when the dependency returns `undefined` / throws? - What happens at boundaries (empty list, max retries, past timestamp)? - What is most likely to break in production? ### Step 2: Write Tests Follow these quality rules: **1. Describe behavior, not code structure** ```typescript // Wrong — describes implementation it('should call repo.getConversation', ...) // Correct — describes behavior it('should return cached task without hitting repo on second call', ...) it('should reject with error when conversation does not exist', ...) ``` **2. Every describe block must cover at least one failure path** Happy-path-only tests leave the most dangerous code untested. **3. One behavior per test** Keep each `it()` focused. More than 3 `expect()` calls in one test is a signal it is testing too much at once. **4. Self-check** After writing a test, mentally delete the core logic it targets. If the test would still pass, rewrite it — it is not guarding anything. **5. Start from risk, not from coverage gaps** List scenarios most likely to produce bugs. Write those first. Coverage is the outcome, not the starting point. ### Step 3: Run Tests ```bash bun run test # Run all tests (REQUIRED before every commit) bun run test:coverage # Check coverage (before opening a PR) ``` ### Step 4: Verify Coverage **Coverage target**: ≥ 80% for all source files matched by `vitest.config.ts` → `coverage.include` (currently `src/**/*.{ts,tsx}` plus a few scripts). New source files are automatically included in coverage — no manual config changes needed. If a new file is accidentally excluded by a rule in `coverage.exclude`, remove it from the exclude list. ### Step 5: Update Existing Tests When modifying logic, check if existing tests need updating: ```bash bun run test -- --reporter=verbose # See which tests pass/fail with names ``` If a test fails because the behavior changed intentionally, update the test. If it fails unexpectedly, investigate. ## Edge Case Checklist When testing a module, verify: - [ ] `null` / `undefined` inputs handled - [ ] Empty arrays/objects handled - [ ] Error thrown by dependencies handled - [ ] Boundary values (0, -1, max, empty string) - [ ] Async operations (timeout, rejection, cancellation) ## Quick Checklist Before submitting code: - [ ] New features have corresponding test cases - [ ] Modified logic has updated tests - [ ] `bun run test` passes - [ ] Tests describe **behavior**, not implementation - [ ] At least one failure path per describe block - [ ] New source files are not accidentally excluded by `coverage.exclude` - [ ] `bun run test:coverage` meets ≥ 80% target ## Common Mistakes | Mistake | Correct | | --------------------------------- | --------------------------------------------- | | Testing implementation details | Test observable behavior | | Only testing happy path | Must include at least one failure path | | 5+ expects in one `it()` | Split into separate tests | | Skipping tests for "simple" code | Simple code breaks too — test the risky parts | | Writing tests after saying "done" | Tests are part of "done", not an afterthought |