@boopkit/cap-testing 0.5.3 → 0.5.6

package/README.md

@@ -12,16 +12,19 @@ Agent skills plus a minimal Jest + ts-jest scaffold. The scaffold is intentional
 
 Copied into your project on install:
 
-- `jest.config.js` — ts-jest preset, Node test environment, test matcher at `tests/**/*.test.ts`
-- `tsconfig.test.json` — extends your project tsconfig and includes `tests/`
+- `jest.config.js` — ts-jest preset, Node test environment, test matcher at `tests/**/*.test.ts`, and the worker settings the suite runs under (`maxWorkers: 4`, `workerIdleMemoryLimit: '500MB'`). Those two spread test files across a pool of worker processes Jest recycles as they grow, so a long suite's memory stays bounded instead of climbing until it dies. They live in the config rather than in the `test` script so that focused runs — `npx jest tests/foo.test.ts` — inherit them too. Because files now run concurrently, tests must namespace whatever they create; drop `maxWorkers` to 1 if a suite is not isolation-safe yet.
+- `tsconfig.test.json` — extends your project tsconfig and includes `tests/`, widening `rootDir` to the project and naming its `@types` packages so that `src/` and `tests/` compile as one program on any TypeScript major. Its comments explain each setting.
 - `tests/app.test.ts` — a starter test asserting the Express app boots and has body parsing wired
 
 ### Scripts added to `package.json`
 
 | Script | Command |
 |--------|---------|
-| `test` | `jest --runInBand` |
+| `test` | `jest` |
 | `test:watch` | `jest --watch` |
+| `typecheck` | `tsc -p tsconfig.test.json` |
+
+`typecheck` is the whole-program static check the testing and planning skills tell every task to run alongside its focused tests: it sees every caller of what changed, which is the breakage a focused run is blind to.
 
 ### Skills installed
 
@@ -37,9 +40,12 @@ Copied into `skills/` on install:
 
 **npm devDependencies added to your project:**
 
-- `jest` — test runner
-- `ts-jest` — TypeScript preset for Jest
-- `@types/jest` — TypeScript types for Jest
+- `jest@^30` — test runner
+- `ts-jest@^29` — TypeScript preset for Jest
+- `@types/jest@^30` — TypeScript types for Jest
+- `typescript@^5` — required by `ts-jest` and by the `typecheck` script
+
+Each is pinned to a caret major so that the toolchain a new project receives is the one boop runs its own suite against, rather than whatever shipped most recently.
 
 **Environment variables:** none required for the scaffold. Individual tests may need service credentials (the Express testing skill documents the integration-test prerequisites — local Postgres, etc.) — those are project-specific and not enforced by this capability.
 
@@ -48,7 +54,7 @@ Copied into `skills/` on install:
 Run the suite:
 
 ```bash
-npm test           # full suite, serialized
+npm test           # full suite
 npm run test:watch # watch mode
 ```
 

package/capability.json

@@ -4,9 +4,10 @@
   "type": "development",
   "dependencies": [],
   "devDependencies": [
-    "jest",
-    "ts-jest",
-    "@types/jest"
+    "jest@^30",
+    "ts-jest@^29",
+    "@types/jest@^30",
+    "typescript@^5"
   ],
   "files": [
     "jest.config.js",
@@ -20,12 +21,16 @@
   ],
   "scripts": {
     "test": {
-      "cmd": "jest --runInBand",
+      "cmd": "jest",
       "description": "Run all tests"
     },
     "test:watch": {
       "cmd": "jest --watch",
       "description": "Run tests in watch mode"
+    },
+    "typecheck": {
+      "cmd": "tsc -p tsconfig.test.json",
+      "description": "Type-check src/ and tests/ as one program"
     }
   },
   "skill_migrations": {

package/package.json

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

package/scaffold/jest.config.js

@@ -6,4 +6,28 @@ module.exports = {
   transform: {
     '^.+\\.ts$': ['ts-jest', { tsconfig: 'tsconfig.test.json' }],
   },
+
+  // Run test files across a small pool of worker processes that Jest recycles.
+  //
+  // `workerIdleMemoryLimit` is the load-bearing setting and it is easy to drop
+  // by accident. Without it Jest runs every file in its own main process — never
+  // recycling it — whenever `maxWorkers <= 1`, and that process's heap grows for
+  // the whole run until a long suite dies of it. Setting a memory limit is what
+  // overrides that decision: it forces real workers and gives Jest a threshold at
+  // which to replace one. `maxWorkers` on its own does not do this, and neither
+  // did the `--runInBand` this replaced — that flag asks for exactly the
+  // un-recycled main process described above.
+  //
+  // The limit is compared against V8 `heapUsed`, not RSS, and is checked between
+  // test files. Budget for real memory use somewhat above `maxWorkers` times this
+  // number, and note that a single file exceeding it is not caught mid-flight.
+  //
+  // Four workers is a deliberate middle setting; six is comfortable on a developer
+  // machine with memory to spare. The constraint on raising it is not the machine,
+  // it is your tests: files now run CONCURRENTLY, so anything sharing a database,
+  // a fixture directory, or a well-known key with another test file will collide.
+  // Namespace what each test creates. Drop to `maxWorkers: 1` if a suite is not
+  // isolation-safe yet — that still gets you the recycling, just without overlap.
+  maxWorkers: 4,
+  workerIdleMemoryLimit: '500MB',
 };

package/scaffold/tsconfig.test.json

@@ -1,5 +1,26 @@
 {
+  // The config ts-jest type-checks against, and the one to point a static
+  // check at: `npx tsc -p tsconfig.test.json`.
   "extends": "./tsconfig.json",
+  "compilerOptions": {
+    // The base config sets "rootDir": "src" so a build emits dist/ cleanly.
+    // Tests live outside src/, so inheriting that root makes every one of them
+    // a TS6059 "not under rootDir" error before a single assertion is read.
+    // Widening the root to the project is what lets tests and sources share a
+    // program; nothing is emitted from here, so the narrower build root is
+    // unaffected.
+    "rootDir": ".",
+    // Type-check only. Without this a stray `tsc -p tsconfig.test.json` would
+    // emit compiled tests into dist/ alongside the real build output.
+    "noEmit": true,
+    // Name the type packages explicitly instead of relying on TypeScript
+    // pulling in everything under node_modules/@types. That automatic
+    // inclusion is not dependable across TypeScript majors — under 6.x it
+    // stops finding @types/jest here, and every `describe`/`it`/`expect` in
+    // the suite becomes TS2593/TS2304 while the package sits installed and
+    // correct. Listing them costs nothing and does not change on upgrade.
+    "types": ["jest", "node"]
+  },
   "include": ["src/**/*", "tests/**/*"],
   "exclude": ["node_modules", "dist"]
 }

package/skills/boop-testing-tdd-light/SKILL.md

@@ -12,7 +12,7 @@ Red → Green → Refactor. Document "before" and "after" states.
 2. **Green**: Implement the minimum change. Add any additional tests.
 3. **Verify**: Re-run all tests from steps 1-2. Type-checking alone is **not sufficient** — functional tests must pass. Check for regressions in related functionality. Verify from the user's perspective — don't just test internal state. For example, if the feature writes files the user interacts with, verify those files exist and are correct.
 
-Test tools: `npm run test` (Jest), `npm run tester` (CLI — see `npm run tester -- help`). For UI changes, coordinate manual browser testing.
+Test tools: `npm test` for the whole suite, `npx jest <path>` for a focused run. Go through `npm test` rather than the runner binary when you want the suite — the script and `jest.config.js` together carry the settings the suite is tuned for, including how many files run at once and how much memory a worker may hold before Jest replaces it, and a bare runner invocation drops whatever lives only in the script. The general testing skill explains why those settings matter and which of them is load-bearing. If the project defines its own test commands beyond these, its `package.json` is the authority. For UI changes, coordinate manual browser testing.
 
 ## Picking the right test shape
 

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

@@ -58,6 +58,34 @@ A skip carrying neither a ticket reference nor a `SKIP-OK:` reason is a conventi
 
 ---
 
+## Which tests to run, and when
+
+**The rule.** A change runs the focused tests for what it touched, plus the project's whole-program static check. The full suite runs once per branch, on the work that completes it. The `boop-project-mgmt-beads-planning` skill carries the canonical wording to put on issues; this section is the reasoning behind it, and the two have to keep agreeing.
+
+**The command is `npm run typecheck`** — `tsc -p tsconfig.test.json`, which compiles `src/` and `tests/` as one program and emits nothing. `boop add testing` scaffolds the script and the config together, so in any project with this capability the static check has a name rather than an invocation each agent has to derive.
+
+If a project does not have it, add it before following the rule, and check the config before trusting it. A `tsconfig.test.json` that extends a build config and then includes `tests/**/*` inherits `"rootDir": "src"`, and every test file is then a TS6059 "not under rootDir" before a single assertion is read — a static check that fails on every file teaches an agent to skip it. The scaffolded config sets `"rootDir": "."`, `"noEmit": true` and an explicit `"types"` list for exactly that reason; its comments explain each one.
+
+**Why the whole suite is the wrong tool mid-change.** The problem is localization, first and foremost. Break a shared dependency and the suite reports it as a cascade of failures in tests that never mention the thing you changed, and you are then reading a wall of red to reconstruct a fact the type-checker would have told you outright, naming a file and a line. A static check plus a search for callers answers "does everything that uses this still hold?" both faster and more precisely than the suite does.
+
+Second, it is slower than the focused run, though see the caution below about how much weight that carries.
+
+Third, a suite already red for an unrelated reason gives you nothing to compare against, so mid-change runs on a red tree get retried and re-read rather than acted on.
+
+**Do not rest the rule on the suite being slow.** A suite's wall-clock time is a property of how the runner is invoked as much as of the tests themselves, and it can fall by an order of magnitude on a single configuration change — running the files in a recyclable worker pool rather than in one long-lived process is the common case. A rule argued from "the suite takes tens of minutes" quietly expires the day somebody fixes the runner, and then it reads as superstition. Argue it from instrument fit, which does not expire.
+
+**What we have not measured.** Nobody has measured how often a focused-tests-only run misses a break that the full suite would have caught, weighed against the time the narrow runs save. Until somebody does, this rule rests on the shippable-unit argument and on instrument fit, and on nothing else. That is worth stating plainly rather than dressing up.
+
+### Go through the project's test script, not a bare runner invocation
+
+Run the suite the way the project defines it — `npm test` — rather than reaching past it to the runner binary. The script and the runner's config file together carry the settings the suite is tuned for: how many files run at once, and how much memory a worker may hold before the runner replaces it. A bare `npx jest` picks up the config file but drops anything that lives only in the script.
+
+Those settings are not decoration. With Jest specifically, `--maxWorkers=1` **does nothing on its own** — Jest runs every file in its own main process, and never recycles it, whenever `maxWorkers <= 1`. Setting `workerIdleMemoryLimit` is what forces a real worker process and gives Jest a threshold at which to replace it; it is the load-bearing setting, and a long suite that grows its heap until it dies is what its absence looks like. Anyone "simplifying" the two settings down to the worker cap has restored the bug.
+
+Keep those settings in the runner's config file rather than in the `test` script, so that the focused runs this section asks for inherit them too. `boop add testing` scaffolds them that way, at four workers and a 500MB per-worker ceiling.
+
+**A worker pool makes test isolation a requirement, not a nicety.** More than one worker means test *files* run at the same time, in separate processes, against the same backing services. Anything two files share and do not namespace — a table one of them truncates in setup, a fixture directory, a well-known key or account id — is now a race, and it surfaces as a suite that passes alone and fails in a full run. That is the same symptom the shared-dev-database section below describes, reached by a different route, and it invites the same wrong fix of weakening the assertion that caught it. Namespace what each test creates. Where a suite is not isolation-safe yet, set `maxWorkers: 1`: that keeps the recycling, which is the part that fixes the memory, and gives up only the overlap.
+
 ## Integration tests never touch the shared dev database
 
 A test or migration that needs a real database must not run against the checkout's inherited connection string.
@@ -197,4 +225,4 @@ When code produces a schema or structure that is validated by an external system
 ## References
 
 - [development.skill.md](development.skill.md) — Light TDD Flow, completion criteria
-- [jest.config.js](../jest.config.js) — Jest configuration
+- [jest.config.js](../../jest.config.js) — Jest configuration, at the project root this capability installs it to

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

@@ -20,6 +20,8 @@ npx jest tests/services/foo --no-coverage                   # Pattern match
 npx jest tests/services/foo.test.ts -t "handles replay"     # By test name
 ```
 
+The focused forms are safe to reach for: the concurrency and per-worker memory settings live in `jest.config.js`, not in the `test` script, so `npx jest <path>` runs under the same settings the full suite does. Which of these you should be running on a given piece of work is a separate question — see "Which tests to run, and when" in the parent skill.
+
 **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