@boopkit/cap-testing 0.1.0

package/capability.json

@@ -0,0 +1,13 @@
+{
+  "name": "testing",
+  "description": "Jest testing setup",
+  "type": "development",
+  "dependencies": [],
+  "devDependencies": ["jest", "ts-jest", "@types/jest"],
+  "files": ["jest.config.js", "tsconfig.test.json", "tests/"],
+  "skills": ["test.tdd-light.skill.md", "test.testing-express-web.skill.md", "test.testing.skill.md"],
+  "scripts": {
+    "test": { "cmd": "jest --runInBand", "description": "Run all tests" },
+    "test:watch": { "cmd": "jest --watch", "description": "Run tests in watch mode" }
+  }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@boopkit/cap-testing",
+  "version": "0.1.0",
+  "description": "Jest testing setup and testing skills for AI agents",
+  "files": [
+    "scaffold/",
+    "skills/",
+    "capability.json"
+  ],
+  "boopkit": {
+    "capability": true,
+    "scaffoldDir": "scaffold",
+    "skillsDir": "skills",
+    "manifest": "capability.json"
+  },
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scaffold/jest.config.js

@@ -0,0 +1,9 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['<rootDir>/tests/**/*.test.ts'],
+  transform: {
+    '^.+\\.ts$': ['ts-jest', { tsconfig: 'tsconfig.test.json' }],
+  },
+};

package/scaffold/tests/app.test.ts

@@ -0,0 +1,17 @@
+import app from '../src/app';
+
+describe('app', () => {
+  it('exports a valid Express application', () => {
+    expect(app).toBeDefined();
+    expect(typeof app.get).toBe('function');
+    expect(typeof app.post).toBe('function');
+    expect(typeof app.use).toBe('function');
+  });
+
+  it('has JSON and URL-encoded body parsing enabled', () => {
+    const stack = (app as any).router?.stack ?? (app as any)._router?.stack ?? [];
+    const layerNames = stack.map((layer: any) => layer.name);
+    expect(layerNames).toContain('jsonParser');
+    expect(layerNames).toContain('urlencodedParser');
+  });
+});

package/scaffold/tsconfig.test.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src/**/*", "tests/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -0,0 +1,10 @@
+# Light TDD Flow
+When you need to build features or implement changes, follow the Light TDD Flow:
+
+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.
+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.

package/skills/test.testing-express-web.skill.md

@@ -0,0 +1,77 @@
+# Testing: Express App (Web & APIs)
+
+When you need to write or run tests for the Express server — services, controllers, middleware, and HTTP routes.
+
+Parent skill: [testing.skill.md](testing.skill.md) (philosophy, generic approach)
+
+---
+
+## Running Tests
+
+```bash
+npm test                                                    # Full suite
+npx jest tests/services/foo.test.ts --no-coverage           # Single file
+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()`.
+
+## Test File Layout
+
+```
+tests/
+  helpers.ts                        # getServices(), TestEntityManager, factories
+  services/
+    foo.test.ts                     # Unit tests (mocked deps)
+    foo.integration.test.ts         # Integration tests (real services)
+  controllers/
+    walletAPI.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
+- 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
+
+## 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)
+
+## 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).
+
+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 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.
+
+**Prereqs:** local server running, durable test account, valid API key (`TEST_API_KEY` env var), relevant feature flags enabled.
+
+## CLI Tools for Ad-Hoc Testing
+
+| 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) |
+
+Run `--help` on either for full command list. These are not automated or part of pre-commit — use Jest for that.
+
+## 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

package/skills/test.testing.skill.md

@@ -0,0 +1,79 @@
+# Testing
+
+When you need to write, run, or reason about tests in this project.
+
+## Philosophy
+
+**Functional testing, not ceremony.** Tests prove code works — not that mocks were wired correctly. Every test should exercise real logic. Type-checking or compilation alone is never sufficient. Be pessimistic about your assumptions: if you think "this should never fail," write a test that verifies it doesn't.
+
+- **Observe the failure first.** A plausible explanation for repeated failures is still a hypothesis until you see success. Always verify the expected *positive* outcome actually occurs (e.g., `cache_hit: true`, not just "no errors").
+- **Mocks are a last resort**, acceptable only for genuinely external dependencies (third-party HTTP, email providers) or to isolate complex decision logic (error classification, retry semantics). If it doesn't hit a real store, call it a unit test — not an "integration test with mocks."
+- **Data-driven coverage for config tables.** Code backed by configuration (pattern tables, route maps, enum mappings) must have tests that exercise *every entry*, not a hand-picked subset. Include a count sanity check (`expect(records.length).toBeGreaterThan(N)`) so an empty response doesn't silently pass.
+- **Undocumented assumptions are spec gaps, not test targets.** When the spec is silent on a behavior (e.g., can a user have multiple sessions? does logout delete or expire state?), that's a design decision to resolve — not something to test around. **Resolve the ambiguity first** (update the spec or get a decision), **then** write the test encoding the decided behavior. If you're writing tests before code (TDD), a spec gap blocks you — don't guess the intent and test your guess. If you discover the gap while reviewing existing code, file a spec issue and name the test to surface the question (e.g., `'login creates additional session token — multi-device support'` not `'login works'`).
+
+---
+
+## Generic Testing Approach
+
+These principles apply across all subsystems.
+
+### Unit tests
+Test **decision logic** independent of real stores: pure functions, orchestration branching, error classification, algorithm correctness.
+
+Mock minimally — just enough to drive the code path under test.
+
+### Refactor for testability
+When a function mixes I/O with logic (reading a file *and* parsing its contents, fetching data *and* transforming it), split it into:
+- A **pure function** that accepts pre-parsed data and returns a result — directly testable with plain objects, no mocks.
+- A **thin I/O wrapper** that reads/writes and delegates to the pure function.
+
+Signs you need this split:
+- Tests require mocking `fs`, `fetch`, or other I/O just to reach the logic you actually want to verify.
+- The mock setup is longer than the assertions.
+- Small changes to serialization format require rewriting mock plumbing.
+
+The pure function tests are fast, deterministic, and mock-free. The I/O wrapper is trivial enough to cover via integration tests or manual verification.
+
+### Integration tests
+Test that **data survives real boundaries** — between components, across serialization, through schema constraints and multi-step lifecycles.
+
+**Principle: test pairwise producer/consumer contracts.** When component A produces output that component B consumes, write a test that runs A then feeds its real output into B. Don't test them only in isolation with hand-crafted fixtures — the fixture may not match what A actually produces.
+
+Two common shapes:
+
+- **Round-trip fidelity.** Write data through one path, read it back through another. *Example:* insert a row via the ORM, query it via the API, assert the response matches. Key question: *could this break because of how the database/service handles the data?* If yes, hit the real dependency.
+- **Writer/reader handoff.** One command writes artifacts (files, config, state) that another command interprets. *Example:* `init` writes a project manifest, `status` reads it to determine setup state — test that status correctly interprets init's actual output, not a synthetic fixture. Key question: *could these disagree about the shape or meaning of the shared artifact?* If yes, wire them together in a test.
+
+When the shared boundary is the filesystem or an in-memory data structure (CLI tools, config pipelines), these tests are cheap and deterministic — no mocks, no external services. Prefer them over testing each side in isolation whenever feasible.
+
+### Mock boundaries
+
+| Mock this | Don't mock this |
+|---|---|
+| Third-party HTTP (email, OAuth) | Adjacent services you own (use real `getServices()`) |
+| `Date.now()` for deterministic assertions | Database queries (use real Postgres/CH) |
+| Complex branching inputs | The service under test's own methods |
+
+### Data-driven config coverage
+When code is backed by a config table (patterns, routes, flags, enums):
+- Load the full config at test time from the real source
+- Iterate every entry and assert expected output
+- Collect all failures (don't fail-fast on first broken entry)
+- Sanity-check the count: `expect(records.length).toBeGreaterThan(N)`
+- Skip only when each entry triggers expensive metered side effects; document why
+
+---
+
+## Subsystem Testing Skills
+
+| Subsystem | Skill |
+|---|---|
+| Express app (web & APIs) | [testing-express-web.skill.md](testing-express-web.skill.md) — Jest, HTTP route tests, CLI tools, test helpers |
+| Cloudflare edge workers | [testing-cf-workers.skill.md](testing-cf-workers.skill.md) — Worker unit/integration tests, wrangler dev setup |
+
+---
+
+## References
+
+- [development.skill.md](development.skill.md) — Light TDD Flow, completion criteria
+- [jest.config.js](../jest.config.js) — Jest configuration