@boopkit/cap-testing 0.5.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-testing",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Jest testing setup and testing skills for AI agents",
   "files": [
     "scaffold/",

package/skills/boop-testing-testing-express-web/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 # Testing: Express App (Web & APIs)
 
 
-Parent skill: [testing.skill.md](testing.skill.md) (philosophy, generic approach)
+Parent skill: [`boop-testing-testing`](../boop-testing-testing/SKILL.md) (philosophy, generic approach)
 
 ---
 
@@ -20,63 +20,68 @@ npx jest tests/services/foo --no-coverage                   # Pattern match
 npx jest tests/services/foo.test.ts -t "handles replay"     # By test name
 ```
 
-**Prerequisites**: local Postgres, ClickHouse, and AWS credentials must be available. Integration tests use real services via `getServices()`.
+**Prerequisites**: integration tests run against the project's real backing services rather than mocks, so whatever the app talks to at runtime — the database first of all — has to be reachable from the machine running the tests. Which services those are depends on the capabilities the project has installed; its README and environment template are the authority.
 
 ## Test File Layout
 
 ```
 tests/
-  helpers.ts                        # getServices(), TestEntityManager, factories
+  helpers/                          # shared setup, factories, harnesses (see below)
   services/
     foo.test.ts                     # Unit tests (mocked deps)
     foo.integration.test.ts         # Integration tests (real services)
   controllers/
-    walletAPI.test.ts               # HTTP route tests
+    itemsAPI.test.ts                # HTTP route tests
   middleware/
   utils/
 ```
 
-- `.test.ts` for Jest auto-discovery; `.integration.test.ts` when `jest.mock` conflicts with `getServices()` in the same file
+- `.test.ts` for Jest auto-discovery. Keep the mocked tests and the real-service tests for the same subject in **separate files**: `jest.mock` is hoisted above the imports and applies to every test in the module, so one file cannot both stub a dependency and exercise the real one. `.integration.test.ts` is the conventional name for the half that uses the real services.
 - Group by domain: `services/`, `controllers/`, `middleware/`
 
-## Test Helpers — [tests/helpers.ts](../tests/helpers.ts)
-- `getServices()` — real services for integration tests
-- `TestEntityManager` — tracks entities, cleans up in `afterEach`
-- Factory helpers (`createTestAccount`, `createTestDomain`, etc.) — use instead of raw Prisma
+## Test Helpers
+
+Shared test setup belongs in one place under `tests/`, not re-derived in each spec file: booting the app, creating the entities a test needs and tearing them down again, and harnesses that make an awkward dependency — a broker, a queue, a rendered template — drivable from a test.
+
+**Read what the project already has before you write one.** These helpers are not scaffolded and cannot be, because they follow whichever capabilities and domain the project has. Every project grows its own set, and the shape varies from one shared module to a directory of purpose-built ones. Reuse what fits and extend it, rather than starting a private copy inside your test file. A helper used by exactly one test is not a helper — leave it in the test.
+
+When you do add one, keep two properties. A factory returns a real, persisted entity rather than a hand-built object literal, so the test exercises the same shape production does. And whatever creates data owns its teardown, so one failed run does not poison the next.
 
 ## Integration Test Data Isolation
-- Unique prefixes (`_test/${Date.now()}`) so parallel runs don't collide
-- Track created resources for cleanup in `afterAll`; wrap each cleanup in `try/catch`
-- For ClickHouse: use test-specific `account_id` / `hostname` (row deletes are expensive with RMT)
+
+Integration tests share their backing services with every other integration test, and with whatever the last run left behind. Three habits keep them from interfering with each other:
+
+- **Namespace whatever you create.** A per-run prefix (`_test/${Date.now()}`, a UUID) keeps parallel runs and repeat runs from colliding on unique constraints.
+- **Track created records and remove them in `afterAll`**, each cleanup wrapped in its own `try/catch` so one failure doesn't strand the rest.
+- **Scope instead of deleting where deletes are expensive.** Some stores — append-only logs, analytics columnstores, anything with asynchronous merge semantics — make row deletion slow or eventually-consistent. Isolate those by writing under a test-specific tenant or key and leave the rows in place.
 
 ## HTTP Route Tests
-Test Express routes via **real HTTP requests** (`fetch()`) against a running local server. This exercises the full middleware chain (auth → feature flags → controller → service → DB → response).
+Test Express routes via **real HTTP requests** (`fetch()`) against a running local server. This exercises the full middleware chain (auth → controller → service → DB → response).
 
 Why real HTTP over supertest: supertest skips TCP/listen and can mask middleware ordering or config bugs. Auth middleware is a critical path worth testing through, not around.
 
 **Setup:**
 ```typescript
 const BASE_URL = process.env.TEST_BASE_URL || 'http://localhost:3000';
-const TEST_API_KEY = process.env.TEST_API_KEY; // npm run admin -- key-generate
+const TEST_API_KEY = process.env.TEST_API_KEY; // however this project issues API keys
 const authHeaders = { 'Authorization': `Bearer ${TEST_API_KEY}`, 'Content-Type': 'application/json' };
 ```
 
-**What to cover:** auth rejection (401/403), feature-flag gates (404), request validation (400), happy-path response shape, cross-account access checks.
+**What to cover:** auth rejection (401/403), request validation (400), the happy-path response shape, and the authorization boundary — that one account cannot reach another's data. If the project gates routes on anything further (feature flags, roles, plan tiers), cover the closed gate too, and assert the status code it actually returns rather than the one that seems right.
+
+**Prereqs:** a local server running against a reachable database, a durable test account, and whatever credential the auth middleware expects (`TEST_API_KEY` by convention).
 
-**Prereqs:** local server running, durable test account, valid API key (`TEST_API_KEY` env var), relevant feature flags enabled.
+## Ad-Hoc Testing Tools
 
-## CLI Tools for Ad-Hoc Testing
+Jest is what runs in CI and before a commit. Alongside it, projects grow small CLIs for the things a test suite is the wrong shape for: generating fixture data, poking a live local server, checking what actually landed in the database.
 
-| Tool | Purpose |
-|---|---|
-| `npm run tester -- <cmd>` | Exploratory smoke tests, fixture data generation (`crawl`, `access-logs-generate`, `s3-raw-smoke`, `user-agent`, etc.) |
-| `npm run admin -- <cmd>` | Entity/data operations (accounts, agents, credentials, CH export/replicate) |
+Boop scaffolds one — `npm run db:query` (database capability) — for reading the local database without opening Prisma Studio. Anything beyond that is project-grown; `package.json` scripts and `src/scripts/` are where to look for what yours has, and `--help` on each is faster than reading its source.
 
-Run `--help` on either for full command list. These are not automated or part of pre-commit — use Jest for that.
+These are exploratory aids. They are not part of the automated suite, and none of them substitutes for a Jest test that can go red on its own.
 
 ## References
 
-- [tests/helpers.ts](../tests/helpers.ts) — shared test utilities and entity factories
-- [src/tester.ts](../src/tester.ts) — ad-hoc CLI (`npm run tester -- help`)
-- [src/admin.ts](../src/admin.ts) — entity management CLI (`npm run admin -- help`)
-- [jest.config.js](../jest.config.js) — Jest configuration
+- [`boop-testing-testing`](../boop-testing-testing/SKILL.md) — testing philosophy and the generic approach
+- [`boop-testing-tdd-light`](../boop-testing-tdd-light/SKILL.md) — the red/green loop for a single change
+- The project's own shared test setup under `tests/` — read it before adding another helper
+- `jest.config.js` at the project root — test discovery, transform, and match config