@boopkit/cap-testing 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-testing",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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 |