@boopkit/cap-testing 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,72 @@
+# @boopkit/cap-testing
+
+**Part of [Boop](https://www.npmjs.com/package/@boopkit/cli)** — a bootstrap platform for AI-first builders. `boop init` scaffolds a running Node/TypeScript web app from composable **capabilities**, each one bundling the code, dependencies, middleware wiring, and agent skills needed for a feature. You pick the capabilities; `boop add` handles the rest.
+
+`cap-testing` sets up Jest for a TypeScript project and installs the testing skills agents need to use it well. It's mostly skills — the testing philosophy, the Light TDD loop, and Express-specific patterns — with a small scaffold so `npm test` works from the first commit.
+
+## What You Get
+
+Agent skills plus a minimal Jest + ts-jest scaffold. The scaffold is intentionally thin: one sample test, one config file, one test-specific tsconfig — enough that `npm test` runs green on day one and new tests follow a known layout.
+
+### Scaffold files
+
+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/`
+- `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:watch` | `jest --watch` |
+
+### Skills installed
+
+Copied into `skills/` on install:
+
+- `test.testing.skill.md` — the testing philosophy: functional tests over ceremony, observe failures before claiming success, mocks as a last resort, and a checklist for when the spec is silent (resolve the ambiguity first, then test).
+- `test.tdd-light.skill.md` — the Red → Green → Verify loop, including bug fixes (write the failing test before the fix).
+- `test.testing-express-web.skill.md` — Express-specific guidance: how to run focused Jest commands, test file layout, and patterns for services, controllers, middleware, and HTTP routes.
+
+## Requirements
+
+**Other capabilities:** none. The sample test expects `src/app` to export an Express app, which is provided by `cap-api` in the default `web-app` profile. If you add `cap-testing` to a project without an Express app, edit or delete `tests/app.test.ts`.
+
+**npm devDependencies added to your project:**
+
+- `jest` — test runner
+- `ts-jest` — TypeScript preset for Jest
+- `@types/jest` — TypeScript types for Jest
+
+**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.
+
+## Usage
+
+Run the suite:
+
+```bash
+npm test           # full suite, serialized
+npm run test:watch # watch mode
+```
+
+Targeted runs (documented in `test.testing-express-web.skill.md`):
+
+```bash
+npx jest tests/services/foo.test.ts --no-coverage
+npx jest tests/services/foo.test.ts -t "handles replay"
+```
+
+New tests go under `tests/`, mirroring the `src/` layout (`tests/services/foo.test.ts` for `src/services/foo.ts`). The three skill files are the canonical guide — agents should read `test.testing.skill.md` for philosophy before writing any test, `test.tdd-light.skill.md` to stay in the Red → Green → Verify loop, and `test.testing-express-web.skill.md` for the project-specific layout and commands.
+
+## Added by
+
+Included by default in the `web-app` profile.
+
+Add to an existing project with:
+
+```bash
+boop add testing
+```

package/package.json

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

package/skills/test.tdd-light.skill.md

@@ -1,9 +1,9 @@
 # Light TDD Flow
-When you need to build features or implement changes, follow the Light TDD Flow:
+When you need to build features, implement changes, or fix bugs, follow the Light TDD Flow. This includes bug fixes found during UAT — write the failing test *before* applying the fix.
 
 Red → Green → Refactor. Document "before" and "after" states.
 
-1. **Red**: Run/write tests that expose the gap (failing test for new feature, reproduced bug, baseline metric). Verify that issues is *observed* and that tests fail for the expected reason. Document the "before" state.
+1. **Red**: Run/write tests that expose the gap (failing test for new feature, reproduced bug, baseline metric). Verify that the issue is *observed* and that tests fail for the expected reason. Document the "before" state. **For bug fixes**: write a test that reproduces the exact failure, then confirm it fails for the right reason before touching the implementation.
 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.
 

package/skills/test.testing.skill.md

@@ -48,6 +48,8 @@ When the shared boundary is the filesystem or an in-memory data structure (CLI t
 
 ### Mock boundaries
 
+Mocks are helpful for isolating orchestration logic, but their limitations must be recognized: a mock silently accepts anything, so it cannot catch failures that occur at real system boundaries. When you use a mock, acknowledge what it *doesn't* cover and ensure integration tests fill the gap.
+
 | Mock this | Don't mock this |
 |---|---|
 | Third-party HTTP (email, OAuth) | Adjacent services you own (use real `getServices()`) |
@@ -64,6 +66,39 @@ When code is backed by a config table (patterns, routes, flags, enums):
 
 ---
 
+## Bug found during UAT
+
+When a bug is discovered through manual testing or UAT, follow this checklist:
+
+1. **Reproduce** — confirm the failure and understand the root cause.
+2. **Find the test gap** — look for an existing test that *should* have caught it. If one exists, understand why it didn't (usually: it mocked the boundary where the failure lives).
+3. **Write a failing test first** — TDD applies to bug fixes, not just features. Write a test that reproduces the exact failure, confirm it fails for the right reason (Red), *then* apply the fix (Green). See [tdd-light.skill.md](test.tdd-light.skill.md).
+4. **Choose the right test level** — if the bug occurred at a system boundary (database, external API, serialization), the test must cross that boundary. A mock-based test cannot catch a boundary failure.
+
+---
+
+## Raw SQL and integration tests
+
+Any service function that uses `$queryRaw` or `$executeRaw` **must have an integration test that runs against the real database**. Mock-based tests for raw SQL provide false confidence — the mock accepts any query shape, but the real database may reject it (wrong column types, deserialization failures, missing columns).
+
+**Pattern**: insert fixture data via raw SQL or Prisma, call the function under test, assert the result, clean up in `afterAll`.
+
+**Especially important for `Unsupported` columns**: Prisma columns marked `Unsupported(...)` (e.g., pgvector `vector(1536)`) will cause runtime deserialization errors if selected in `$queryRaw`. TypeScript won't catch this, and mocks won't catch this. Only a real DB query will.
+
+---
+
+## Schema contract testing
+
+When code produces a schema or structure that is validated by an external system, test the schema against that system's documented rules — don't assume your code is the arbiter of truth.
+
+**Pattern**: write a test that walks the schema and asserts every invariant the consuming system requires. No mocks, no API calls — just structural validation.
+
+**Example**: OpenAI structured outputs with `strict: true` require `additionalProperties: false` on every object node. A test walks the schema tree and asserts the property exists on each object. This catches schema authoring mistakes before they reach the API.
+
+**When to apply**: any time your code produces configuration, schemas, or structured data that an external system validates — OpenAI schemas, JSON Schema for APIs, database DDL consumed by migration tools, etc.
+
+---
+
 ## Subsystem Testing Skills
 
 | Subsystem | Skill |