# Build Session: Testing Reference

Companion file for SESSION_BUILD.md — contains baseline and verification protocols.

## Baseline (before building)

Establish a baseline before making changes — but be smart about scope.

**When to run baseline tests:**
- Modifying existing code that has tests: YES, run targeted tests
- Adding new code to a file with existing tests: YES, but only that file's tests
- Creating a new file: NO baseline needed
- Config changes, documentation: NO tests needed

**Test discovery protocol:**
1. For file `foo.mjs` → check for `foo.test.mjs` or `foo.test.js`
2. For `components/foo.js` → check `components/foo.test.js`
3. For `index.js` or `api.mjs` → **targeted tests only**: run only tests for endpoints/functions you're modifying
4. Run: `ls *.test.mjs *.test.js 2>/dev/null` to see all available test files

**Baseline steps (when applicable):**
- Identify which test files cover your target files
- Run targeted tests BEFORE making changes: `node --test <file>.test.mjs`
- Note the baseline result. If baseline fails, you inherit that — don't make it worse.

**Timeout prevention**: If tests take >3 minutes, skip baseline. You'll catch regressions in verification.

## Verification (after building)

Verification ensures you didn't break anything. Match scope to your changes.

**Verification protocol:**
1. Run **targeted tests only** — tests for files you modified, not the full suite
2. Compare results: pass count >= baseline, no new failures
3. For new functionality: add a **quick smoke test** (curl for endpoints, simple invocation for tools)
4. If tests fail: fix before committing. Do NOT commit with failing tests.

**Test file mapping (common cases):**
| File modified | Test command |
|--------------|--------------|
| `api.mjs` | `node --test api.test.mjs` |
| `session-context.mjs` | `node --test session-context.test.mjs` |
| `engage-orchestrator.mjs` | `node --test engage-orchestrator.test.mjs` |
| `index.js` | Test only the component you modified |
| `components/*.js` | Check for matching `.test.js`, else smoke test |
| New endpoint | `curl` smoke test only |

**Time-sensitive verification**: If >10 minutes into session, acceptable alternatives:
- Smoke test: `curl localhost:3847/health` confirms server starts
- Syntax check: `node --check <file>.mjs` confirms no parse errors
- Defer full tests: note "verification deferred" in commit message

**No tests exist?** If you modify a file with no test coverage:
- For bug fixes: manual verification is acceptable
- For new features: smoke test is sufficient
- Note "no tests" in the commit message

**Test tooling available:**
- `node test-coverage-status.mjs` — shows which components need tests (by churn/criticality)
- `node generate-test-scaffold.mjs components/<name>.js` — generates test skeleton with tool detection
- When working on wq-179 or similar test items, use these tools instead of writing from scratch
