node-testing

name	node-testing
description	Generates unit and HTTP-level integration tests for Node backend APIs (Express, Fastify, Koa, NestJS) using Supertest against the app instance directly, with Vitest, Jest, or node:test. Use when the user asks to test a route handler, controller, middleware, or Express/Fastify app, or mentions Supertest, app.listen, testcontainers, or a package.json with express/fastify/koa but no frontend framework. For a React or Next.js frontend in the same repo, use react-testing or nextjs-testing instead.
license	MIT
compatibility	Requires Node.js and the project's existing package manager. Requires a package.json declaring express, fastify, koa, or @nestjs/core.
metadata	{"platform":"node-express","report-source":"testing-methodologies-deep-research-report.txt Part 6 and Part 8"}
allowed-tools	Read, Write, Edit, Grep, Glob, Bash
paths	["**/*.route.js","**/*.route.ts","**/routes/**","**/controllers/**"]

Node / Express Testing

Writes unit and HTTP-level integration tests for Node backend APIs, using Supertest against the app instance directly — never a real listening port — with real Request/Response behavior and none of the flakiness of standing up an actual server process. Writing the test files is the deliverable. Running the suite and verifying it — including the fault-injection self-check — is a separate, optional step this skill offers but never runs without being asked. See Step 6.

Progress checklist

Copy this into your response and check items off as you go:

- [ ] 1. Detect stack (scripts/detect_stack.sh)
- [ ] 2. Audit project structure and existing test conventions
- [ ] 3. Ask the user what to test (layer + scope) — do not assume
- [ ] 4. State the test plan explicitly
- [ ] 5. Generate tests following AAA, boundary-only mocking
- [ ] 6. Report what was written; offer to run + verify — do not run yet
- [ ] 7. Only if asked: run tests, fault-injection self-check, report results

Step 1 — Detect stack

Run scripts/detect_stack.sh from the project root. It confirms this is a Node backend project (Express/Fastify/Koa/NestJS) and reports the existing test runner, Supertest, testcontainers, and contract-testing tools already present, plus a check for .listen() calls outside test files — a common port-binding footgun under parallel test workers.

If a test runner or HTTP-testing library is already in use, follow it even if a different tool is this skill's default recommendation. Never introduce a second, competing test runner into a project that already picked one.

Step 2 — Audit project structure

Before writing anything:

• Classify the target: pure logic (a service/utility function, no Express-specific objects involved) vs a route handler/controller (needs Supertest, exercising real request/response) vs middleware.
• Match the existing test file convention (__tests__/ vs co-located *.test.ts) from Step 1.
• Flag critical paths — authentication, payment/billing, any data-write operation — for elevated rigor and deliberately high branch coverage, even if the user's request was narrower. State this flag out loud; do not silently expand scope.

Step 3 — Ask the user what to test (never assume)

Ask a single message with two questions before generating anything:

1. Layer: unit tests only (pure logic/services) / HTTP-level integration tests via Supertest / testcontainers-backed integration tests against a real disposable database / a mix appropriate to what's being tested.
2. Scope: does the user want the whole API tested, one route/feature tested end-to-end, or just specific file(s)/handler(s)? Do not assume — ask explicitly and wait for the answer. If the user's original request already named specific files or a feature, confirm that scope back to them rather than silently re-asking, but still confirm it.