From aa2f5ce7252fa509f9901995b45c0feab04e4cb1 Mon Sep 17 00:00:00 2001 From: Yeganathan S <63534555+skwowet@users.noreply.github.com> Date: Mon, 27 Jul 2026 14:36:11 +0530 Subject: [PATCH 1/5] chore: add agent skills for unit and API e2e tests (CM-968) Signed-off-by: Yeganathan S <63534555+skwowet@users.noreply.github.com> --- .claude/skills/write-api-e2e-tests/SKILL.md | 66 +++++++++++++++++++ .claude/skills/write-unit-tests/SKILL.md | 71 +++++++++++++++++++++ 2 files changed, 137 insertions(+) create mode 100644 .claude/skills/write-api-e2e-tests/SKILL.md create mode 100644 .claude/skills/write-unit-tests/SKILL.md diff --git a/.claude/skills/write-api-e2e-tests/SKILL.md b/.claude/skills/write-api-e2e-tests/SKILL.md new file mode 100644 index 0000000000..6c3d8c571a --- /dev/null +++ b/.claude/skills/write-api-e2e-tests/SKILL.md @@ -0,0 +1,66 @@ +--- +name: write-api-e2e-tests +description: > + Write API end-to-end tests. Use when adding or changing API endpoints, or when + the user asks for API e2e, smoke, or contract tests. +allowed-tools: Bash, Read, Glob, Grep, Edit, Write, AskUserQuestion +--- + +# Write API end-to-end tests + +Write or extend API end-to-end tests. + +## When to use + +- New or changed API endpoints. +- User asks for API e2e, smoke, or contract tests. +- Critical API behaviour needs regression coverage. + +## When not to use + +- Domain or SQL correctness → use `write-unit-tests`. +- Temporal, OpenSearch, or other eventual side effects outside the documented API e2e scope. +- Creating a new testing framework or suite style. + +## Source of truth + +Read before writing. Follow these ADRs and existing suite structure; do not +invent a parallel testing style. + +- [ADR-0012](docs/adr/0012-api-e2e-test-architecture.md) — runtime, isolation, supported surfaces, scope, and assertions. +- [ADR-0013](docs/adr/0013-api-e2e-test-suite-design.md) — suite organisation, helpers, and conventions. + +Current default entrypoint: + +- `.github/scripts/public-api-e2e-tests.sh` + +## Workflow + +1. Identify the API surface. Default to Public API unless the user specifies otherwise. +2. Read ADR-0012 and ADR-0013. +3. Add or extend the appropriate suite and register it if required. +4. Run the affected suite locally and fix failures until green. +5. If required fixtures cannot be created through the API, prefer testing supported scenarios and explain any coverage gaps instead of seeding the database directly. +6. Suggest production testability improvements only when they make the API easier to test, and ask before changing production code. + +## Run + +Export the environment variables required by the suite entrypoint. + +```bash +bash .github/scripts/public-api-e2e-tests.sh +``` + +Refer to ADR-0012 and the suite entrypoint for environment setup, reset behaviour, +and local development workflows. + +## Guardrails + +- Keep tests focused on observable API behaviour. + +## Output + +- Suites and cases added +- How to re-run +- Coverage gaps, if any +- Optional testability suggestions diff --git a/.claude/skills/write-unit-tests/SKILL.md b/.claude/skills/write-unit-tests/SKILL.md new file mode 100644 index 0000000000..c8d3082480 --- /dev/null +++ b/.claude/skills/write-unit-tests/SKILL.md @@ -0,0 +1,71 @@ +--- +name: write-unit-tests +description: > + Write focused Vitest unit tests. Use when adding or improving unit tests for + business logic, data access, common services, or other server modules. +allowed-tools: Bash, Read, Glob, Grep, Edit, Write, AskUserQuestion +--- + +# Write unit tests + +Write focused unit tests that follow the project's testing conventions. + +## When to use + +- User asks to add or improve unit tests. +- A change touches high-blast-radius logic (affiliations, merges, identity resolution, timelines, inference). +- A PR needs confidence in a pure or Postgres-backed function. + +## When not to use + +- Public or HTTP contract coverage → use `write-api-e2e-tests`. +- Temporal, Redis, or OpenSearch fixtures (not available yet). +- Broad "increase coverage %" requests without a clear unit under test. + +## Source of truth + +Read before writing. Follow these ADRs; do not invent a parallel testing style. + +- [ADR-0008](docs/adr/0008-how-we-write-unit-tests.md) — scenarios, `describe` grouping, assertions, mocking, and shared setup. +- [ADR-0007](docs/adr/0007-test-factory-primitives-and-defaults.md) — factories and defaults. + +## Workflow + +1. Identify the unit under test (one function or decision path). Colocate tests as `.test.ts`. +2. Read ADR-0007 and ADR-0008. Skim the nearest existing test in the same area if one exists. +3. Compose fixtures using `@crowd/test-kit` (`withQx` for Postgres-backed tests; factories and opt-in defaults per ADR-0007). +4. Write focused scenarios following ADR-0008 (grouping, naming, assertions, and mocking). +5. Run the affected tests and fix failures until green. +6. If production code is difficult to test, suggest a small testability seam and ask before changing production code. + +## Run + +Start the test database when needed: + +```bash +./scripts/cli scaffold up-test +``` + +Run a focused test file: + +```bash +pnpm test:server -- path/to/file.test.ts +``` + +Optional: + +```bash +pnpm test:changed +pnpm test:watch -- path/to/file.test.ts +``` + +## Guardrails + +- Prefer critical behaviours over trivial getters, setters, and thin wrappers. +- Keep production behaviour unchanged unless the user explicitly asks for a testability improvement. + +## Output + +- Scenarios covered +- How to re-run +- Optional testability suggestions From 4943ad5c299a050af7d817481d7e935688d40bac Mon Sep 17 00:00:00 2001 From: Yeganathan S <63534555+skwowet@users.noreply.github.com> Date: Mon, 27 Jul 2026 14:46:36 +0530 Subject: [PATCH 2/5] chore: register testing skills in skill-guidance (CM-968) Signed-off-by: Yeganathan S <63534555+skwowet@users.noreply.github.com> --- .claude/rules/skill-guidance.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.claude/rules/skill-guidance.md b/.claude/rules/skill-guidance.md index 854366fda9..84e663768a 100644 --- a/.claude/rules/skill-guidance.md +++ b/.claude/rules/skill-guidance.md @@ -18,6 +18,8 @@ This project has guided skills for common workflows. **Proactively suggest the r | `/scaffold-snowflake-connector` | Add a new Snowflake-connector data source or integration | | `/packages-worker-setup` | First-time setup of packages-db and github-repos-enricher for a new engineer | | `/packages-worker-add-entrypoint` | Scaffold a new sibling worker inside packages_worker (npm, OSV, scorecard, etc.) | +| `/write-unit-tests` | Add or improve Vitest unit tests for business logic, DAL, or server modules | +| `/write-api-e2e-tests` | Add or change Public API e2e / smoke / contract tests | ## Trigger Phrases @@ -57,3 +59,13 @@ This project has guided skills for common workflows. **Proactively suggest the r - "Add a new packages worker", "scaffold a sibling worker", "new entry point in packages_worker" - "Add npm ingestion", "add OSV worker", "add scorecard runner" - Any request to create a new `src/bin/*.ts` worker inside `packages_worker` + +**`/write-unit-tests`** — match any of these intents: +- "Write unit tests", "add a unit test", "cover this with Vitest" +- "Test this function", "add DAL tests", "unit test for affiliations/merges/inference" +- Any request for focused server/unit test coverage (not HTTP/API contract tests) + +**`/write-api-e2e-tests`** — match any of these intents: +- "Write API e2e tests", "add smoke tests", "Public API contract tests" +- "Cover this endpoint end-to-end", "API regression test" +- Any request for HTTP/API e2e coverage of Public API behaviour From 544360653958c2fda1716735c63f1ca36d9a7535 Mon Sep 17 00:00:00 2001 From: Yeganathan S <63534555+skwowet@users.noreply.github.com> Date: Mon, 27 Jul 2026 15:22:46 +0530 Subject: [PATCH 3/5] fix: correct ADR relative links in testing skills (CM-968) Signed-off-by: Yeganathan S <63534555+skwowet@users.noreply.github.com> --- .claude/skills/write-api-e2e-tests/SKILL.md | 4 ++-- .claude/skills/write-unit-tests/SKILL.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude/skills/write-api-e2e-tests/SKILL.md b/.claude/skills/write-api-e2e-tests/SKILL.md index 6c3d8c571a..9d7e70ebe8 100644 --- a/.claude/skills/write-api-e2e-tests/SKILL.md +++ b/.claude/skills/write-api-e2e-tests/SKILL.md @@ -27,8 +27,8 @@ Write or extend API end-to-end tests. Read before writing. Follow these ADRs and existing suite structure; do not invent a parallel testing style. -- [ADR-0012](docs/adr/0012-api-e2e-test-architecture.md) — runtime, isolation, supported surfaces, scope, and assertions. -- [ADR-0013](docs/adr/0013-api-e2e-test-suite-design.md) — suite organisation, helpers, and conventions. +- [ADR-0012](../../../docs/adr/0012-api-e2e-test-architecture.md) — runtime, isolation, supported surfaces, scope, and assertions. +- [ADR-0013](../../../docs/adr/0013-api-e2e-test-suite-design.md) — suite organisation, helpers, and conventions. Current default entrypoint: diff --git a/.claude/skills/write-unit-tests/SKILL.md b/.claude/skills/write-unit-tests/SKILL.md index c8d3082480..5af4cfceaf 100644 --- a/.claude/skills/write-unit-tests/SKILL.md +++ b/.claude/skills/write-unit-tests/SKILL.md @@ -26,8 +26,8 @@ Write focused unit tests that follow the project's testing conventions. Read before writing. Follow these ADRs; do not invent a parallel testing style. -- [ADR-0008](docs/adr/0008-how-we-write-unit-tests.md) — scenarios, `describe` grouping, assertions, mocking, and shared setup. -- [ADR-0007](docs/adr/0007-test-factory-primitives-and-defaults.md) — factories and defaults. +- [ADR-0008](../../../docs/adr/0008-how-we-write-unit-tests.md) — scenarios, `describe` grouping, assertions, mocking, and shared setup. +- [ADR-0007](../../../docs/adr/0007-test-factory-primitives-and-defaults.md) — factories and defaults. ## Workflow From 95b13f9d46cec7a0389941e84c67759520405b9b Mon Sep 17 00:00:00 2001 From: Yeganathan S <63534555+skwowet@users.noreply.github.com> Date: Mon, 27 Jul 2026 15:27:16 +0530 Subject: [PATCH 4/5] docs: extend ADR-0008 with mocking and describe grouping (CM-968) Signed-off-by: Yeganathan S <63534555+skwowet@users.noreply.github.com> --- docs/adr/0008-how-we-write-unit-tests.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/adr/0008-how-we-write-unit-tests.md b/docs/adr/0008-how-we-write-unit-tests.md index 3e6f84f2fb..5de6402a73 100644 --- a/docs/adr/0008-how-we-write-unit-tests.md +++ b/docs/adr/0008-how-we-write-unit-tests.md @@ -25,6 +25,8 @@ reuse is real. - Setup should make that story obvious (concrete labels, dates, relationships). - Do not combine unrelated behaviors in a single test. - Prefer fewer tests that fail clearly over many that pass for the wrong reason. +- When a file covers more than one function, group cases with + `describe('', …)` and put named scenarios inside. ### Assertions @@ -33,6 +35,18 @@ reuse is real. - Avoid loose probes (`some`, `greaterThan`, optional finds) unless the claim truly is approximate. +### Mocking + +- Do not mock the data-access layer or the unit under test. Postgres-backed + tests use a real test database and factories; query behavior is part of what + we ship. +- Reach for mocks only at external network boundaries where the real dependency + would hurt reliability or speed (outbound HTTP, LLM clients, Slack/email + senders, Auth0 JWKS in end-to-end tests). +- Control non-determinism in-process when needed (e.g. fake timers for “now”). +- If a test seems to need a mock outside that list, the unit is often too large: + extract the pure part, unit-test it, and let the outer path stay real. + ### What to share | Layer | Where | Belongs | From bd353beee0acdfdf224f65a80441d2cb0fd2f24b Mon Sep 17 00:00:00 2001 From: Yeganathan S <63534555+skwowet@users.noreply.github.com> Date: Mon, 27 Jul 2026 15:34:34 +0530 Subject: [PATCH 5/5] fix: exclude packages_worker from write-unit-tests skill (CM-968) Signed-off-by: Yeganathan S <63534555+skwowet@users.noreply.github.com> --- .claude/rules/skill-guidance.md | 1 + .claude/skills/write-unit-tests/SKILL.md | 1 + 2 files changed, 2 insertions(+) diff --git a/.claude/rules/skill-guidance.md b/.claude/rules/skill-guidance.md index 84e663768a..a754a06e5f 100644 --- a/.claude/rules/skill-guidance.md +++ b/.claude/rules/skill-guidance.md @@ -64,6 +64,7 @@ This project has guided skills for common workflows. **Proactively suggest the r - "Write unit tests", "add a unit test", "cover this with Vitest" - "Test this function", "add DAL tests", "unit test for affiliations/merges/inference" - Any request for focused server/unit test coverage (not HTTP/API contract tests) +- Not for `packages_worker` (excluded from `pnpm test:server` for now) **`/write-api-e2e-tests`** — match any of these intents: - "Write API e2e tests", "add smoke tests", "Public API contract tests" diff --git a/.claude/skills/write-unit-tests/SKILL.md b/.claude/skills/write-unit-tests/SKILL.md index 5af4cfceaf..aecdc54282 100644 --- a/.claude/skills/write-unit-tests/SKILL.md +++ b/.claude/skills/write-unit-tests/SKILL.md @@ -19,6 +19,7 @@ Write focused unit tests that follow the project's testing conventions. ## When not to use - Public or HTTP contract coverage → use `write-api-e2e-tests`. +- `packages_worker` (excluded from `pnpm test:server` for now; own vitest/packages-db). - Temporal, Redis, or OpenSearch fixtures (not available yet). - Broad "increase coverage %" requests without a clear unit under test.