qa-skills 3.0.0

package/skills/qa-supertest-writer/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: qa-supertest-writer
+description: Generate Supertest API and integration tests for TypeScript/Node.js with Express/Koa integration, chained assertions, and authentication handling.
+output_dir: tests/api
+dependencies:
+  recommended:
+    - qa-api-contract-curator
+---
+
+# QA Supertest Writer
+
+## Purpose
+
+Write API and integration tests using Supertest from test case specifications and API contracts. Transform structured test cases (from qa-testcase-from-docs, qa-manual-test-designer) and OpenAPI contracts (from qa-api-contract-curator) into executable Supertest code with chained assertions, authentication support, and response validation.
+
+## Trigger Phrases
+
+- "Write Supertest tests for [API/endpoint]"
+- "Generate API tests from OpenAPI contract"
+- "Create Supertest integration tests for Express"
+- "Add API tests for [endpoint] with auth"
+- "Supertest tests from test cases"
+- "API contract to Supertest tests"
+- "Test file upload with Supertest"
+- "Supertest tests for Koa server"
+
+## Key Features
+
+| Feature | Description |
+| ------- | ----------- |
+| **Express/Koa integration** | `request(app)` — no server startup; tests run against app instance |
+| **Chained HTTP assertions** | `.expect(statusCode)`, `.expect(contentType)`, `.expect(body)` — fluent API |
+| **Request/response validation** | Headers, status, body shape; JSON Schema or Zod/Joi for schema validation |
+| **Authentication support** | Bearer tokens, cookies, API keys via `.set()` |
+| **File upload testing** | `.attach()` for multipart/form-data |
+
+## Workflow
+
+1. **Read test cases + API contract** — From qa-testcase-from-docs, qa-manual-test-designer, or qa-api-contract-curator (OpenAPI)
+2. **Generate API test files** — Produce `{endpoint}.api.test.ts` with `describe` per endpoint, `it` per scenario
+3. **Add auth setup** — Bearer token, cookies, or API key fixtures in `beforeEach`/`beforeAll`
+4. **Validate responses** — Status codes, headers, body matching; optional schema validation (Zod, Joi, JSON Schema)
+
+## Context7 MCP
+
+Use **Context7 MCP** for current Supertest documentation when:
+- API signatures or chaining behavior are uncertain
+- New Supertest features need verification
+- Express vs Koa setup differences require clarification
+
+## Key Patterns
+
+| Pattern | Usage |
+| ------- | ----- |
+| `request(app)` | Wrap Express/Koa app; no `listen()` needed |
+| `.get(path)` / `.post(path)` / `.put(path)` / `.delete(path)` | HTTP method + path |
+| `.set(header, value)` | Set request headers (Authorization, Content-Type, etc.) |
+| `.send(body)` | Request body (JSON, form) |
+| `.expect(statusCode)` | Assert response status |
+| `.expect(contentType, /json/)` | Assert Content-Type header |
+| `.expect(body)` | Assert response body (string, regex, function) |
+| Chained assertions | `.get('/users').expect(200).expect('Content-Type', /json/)` |
+| Bearer token | `.set('Authorization', 'Bearer ' + token)` |
+| Cookies | `.set('Cookie', cookieString)` or use agent for session |
+| File upload | `.attach(field, filePath)` |
+
+See `references/patterns.md` for CRUD, auth, file upload, error responses, pagination.
+
+## Test Structure
+
+- **describe** per endpoint (e.g., `describe('GET /users')`)
+- **it** per scenario: success, validation error, unauthorized, not found, conflict
+- **beforeAll/beforeEach** for auth tokens, DB seeding, cleanup
+- **afterEach/afterAll** for cleanup (e.g., truncate test data)
+
+## Integration with Express/Koa
+
+```ts
+import request from 'supertest'
+import { app } from '../src/app'
+
+describe('API', () => {
+  it('GET /health returns 200', () =>
+    request(app).get('/health').expect(200))
+})
+```
+
+No `app.listen()` — Supertest handles the request internally.
+
+## Schema Validation
+
+- **JSON Schema** — Use `ajv` or similar to validate response against schema
+- **Zod** — `zodSchema.parse(response.body)` in custom `.expect()` callback
+- **Joi** — `Joi.assert(response.body, schema)` in callback
+
+## File Naming
+
+- `{endpoint}.api.test.ts` — e.g., `users.api.test.ts`, `auth.api.test.ts`
+- `{resource}.api.test.ts` — e.g., `products.api.test.ts`
+
+## Scope
+
+**Can do (autonomous):**
+- Generate Supertest API tests from test cases and OpenAPI contracts
+- Add auth setup (Bearer, cookies, API key)
+- Use chained assertions, `.set()`, `.send()`, `.attach()`
+- Configure test server, DB seeding, cleanup
+- Validate responses with status, headers, body; add schema validation (Zod/Joi)
+- Call qa-api-contract-curator for contract when needed
+- Use Context7 MCP for Supertest docs
+
+**Cannot do (requires confirmation):**
+- Change production API implementation
+- Add dependencies not in package.json
+- Override project test config without approval
+
+**Will not do (out of scope):**
+- Execute tests (user runs `npm test` or `vitest`)
+- Write E2E browser tests (use qa-playwright-ts-writer)
+- Modify CI/CD pipelines
+
+## References
+
+- `references/patterns.md` — CRUD, auth, file upload, error responses, pagination
+- `references/assertions.md` — Status codes, headers, body matching, schema validation
+- `references/config.md` — Test server config, DB seeding, cleanup
+- `references/best-practices.md` — Test isolation, DB state, auth fixtures, response validation
+
+## Quality Checklist
+
+- [ ] Tests match test case steps and expected results
+- [ ] Each endpoint has success and error scenarios (validation, 401, 404)
+- [ ] Auth setup is correct (Bearer, cookies) and isolated per test
+- [ ] No hardcoded secrets; use env vars or test fixtures
+- [ ] Response assertions are specific (status, body shape, headers)
+- [ ] File naming follows `{endpoint}.api.test.ts`
+- [ ] DB state is reset or isolated between tests
+- [ ] Schema validation used where contract specifies response shape
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+| ------- | ------------ | --- |
+| `request(app)` returns 404 | App not mounted or route missing | Verify app exports; check route registration order |
+| Tests pass individually, fail together | Shared DB state or auth leakage | Reset DB in `beforeEach`; use fresh tokens per test |
+| `.expect(body)` fails on dynamic fields | Body has timestamps, IDs, etc. | Use partial match, regex, or custom callback |
+| Auth not working | Token expired or wrong header | Check `Authorization` format; ensure token in scope |
+| File upload fails | Wrong field name or path | Match `field` to form field; use absolute path |
+| Koa app not working | Different API than Express | Use `request(app.callback())` for Koa |
+| CORS errors in tests | CORS middleware blocking | Supertest bypasses network; check middleware order |

package/skills/qa-supertest-writer/references/assertions.md

@@ -0,0 +1,192 @@
+# Supertest Assertion Reference
+
+Supertest provides chained `.expect()` methods for HTTP assertions. Combine with Vitest/Jest `expect()` for body validation.
+
+## Status Codes
+
+```ts
+request(app).get('/users').expect(200)
+request(app).post('/users').send({}).expect(201)
+request(app).get('/users/999').expect(404)
+request(app).get('/users').expect(401)  // Unauthorized
+request(app).post('/users').send({}).expect(400)  // Bad Request
+request(app).get('/error').expect(500)  // Server Error
+```
+
+| Code | Typical Use |
+| ---- | ----------- |
+| 200 | OK — GET, PUT, PATCH success |
+| 201 | Created — POST success |
+| 204 | No Content — DELETE success |
+| 400 | Bad Request — validation error |
+| 401 | Unauthorized — missing/invalid auth |
+| 403 | Forbidden — insufficient permissions |
+| 404 | Not Found — resource missing |
+| 409 | Conflict — duplicate, constraint violation |
+| 422 | Unprocessable Entity — semantic validation |
+| 500 | Internal Server Error |
+
+## Content-Type
+
+```ts
+request(app)
+  .get('/users')
+  .expect('Content-Type', /json/)
+  .expect(200)
+
+// Exact match
+request(app)
+  .get('/users')
+  .expect('Content-Type', 'application/json; charset=utf-8')
+```
+
+## Body Assertions
+
+### String Match
+
+```ts
+request(app)
+  .get('/health')
+  .expect(200)
+  .expect('OK')
+```
+
+### Regex Match
+
+```ts
+request(app)
+  .get('/users/1')
+  .expect((res) => {
+    expect(res.body.email).toMatch(/^[\w.-]+@[\w.-]+\.\w+$/)
+  })
+```
+
+### Custom Callback
+
+```ts
+request(app)
+  .get('/users')
+  .expect(200)
+  .expect((res) => {
+    expect(res.body).toHaveProperty('users')
+    expect(res.body.users.length).toBeGreaterThan(0)
+    expect(res.body.users[0]).toHaveProperty('id')
+  })
+```
+
+### With Vitest/Jest expect()
+
+```ts
+const res = await request(app).get('/users').expect(200)
+
+expect(res.body).toHaveProperty('users')
+expect(res.body.users).toEqual(expect.arrayContaining([
+  expect.objectContaining({ id: 1, email: expect.any(String) }),
+]))
+expect(res.body.users[0]).toMatchObject({ id: 1, name: 'Alice' })
+```
+
+## Header Assertions
+
+```ts
+request(app)
+  .get('/users')
+  .expect('Content-Type', /json/)
+  .expect('X-Request-ID', (val) => expect(val).toBeDefined())
+  .expect(200)
+
+// Or capture and assert
+const res = await request(app).get('/users').expect(200)
+expect(res.headers['content-type']).toMatch(/json/)
+expect(res.headers['x-request-id']).toBeDefined()
+```
+
+## Schema Validation
+
+### Zod
+
+```ts
+import { z } from 'zod'
+
+const UserSchema = z.object({
+  id: z.number(),
+  email: z.string().email(),
+  name: z.string(),
+})
+
+request(app)
+  .get('/users/1')
+  .expect(200)
+  .expect((res) => {
+    const parsed = UserSchema.parse(res.body)
+    expect(parsed.id).toBe(1)
+  })
+```
+
+### Joi
+
+```ts
+import Joi from 'joi'
+
+const userSchema = Joi.object({
+  id: Joi.number().required(),
+  email: Joi.string().email().required(),
+  name: Joi.string().required(),
+})
+
+request(app)
+  .get('/users/1')
+  .expect(200)
+  .expect((res) => {
+    Joi.assert(res.body, userSchema)
+  })
+```
+
+### JSON Schema (ajv)
+
+```ts
+import Ajv from 'ajv'
+
+const ajv = new Ajv()
+const validate = ajv.compile(userJsonSchema)
+
+request(app)
+  .get('/users/1')
+  .expect(200)
+  .expect((res) => {
+    const valid = validate(res.body)
+    expect(valid).toBe(true)
+    if (!valid) expect(validate.errors).toBeDefined()
+  })
+```
+
+## Chained Assertions
+
+```ts
+await request(app)
+  .post('/users')
+  .set('Content-Type', 'application/json')
+  .send({ email: 'a@b.com', name: 'Alice' })
+  .expect(201)
+  .expect('Content-Type', /json/)
+  .expect((res) => {
+    expect(res.body).toHaveProperty('id')
+    expect(res.body.email).toBe('a@b.com')
+  })
+```
+
+## Async vs Sync
+
+Use `await` when you need the response for further assertions:
+
+```ts
+const res = await request(app).get('/users').expect(200)
+const firstUser = res.body.users[0]
+expect(firstUser).toHaveProperty('email')
+```
+
+Return the chain when Supertest assertions are sufficient:
+
+```ts
+it('returns 200', () => request(app).get('/users').expect(200))
+```

package/skills/qa-supertest-writer/references/best-practices.md

@@ -0,0 +1,102 @@
+# API Testing Best Practices
+
+## Test Isolation
+
+1. **Independent tests** — Each test should pass or fail regardless of order. Use `beforeEach` to reset state.
+2. **No shared mutable state** — Avoid global variables that tests modify; use fixtures or factories.
+3. **Clean database** — Truncate or delete test data between tests, or use transactions that rollback.
+
+## Database State
+
+| Approach | Pros | Cons |
+| -------- | ---- | ---- |
+| **Truncate + seed** | Clean slate each run | Slower; may conflict with parallel tests |
+| **Transactions** | Fast; automatic rollback | Requires transaction support in app |
+| **Isolated DB per worker** | No cross-test pollution | More setup; resource usage |
+| **Factory + unique data** | Flexible; no truncate | Must avoid collisions (unique emails, etc.) |
+
+### Transaction Rollback Example
+
+```ts
+beforeEach(async () => {
+  await db.transaction.begin()
+})
+
+afterEach(async () => {
+  await db.transaction.rollback()
+})
+```
+
+## Auth Fixtures
+
+1. **Use test-only accounts** — Never use production credentials.
+2. **Create tokens in beforeAll** — Reuse when tests don't mutate auth state.
+3. **Fresh token per test** — When testing logout, token expiry, or auth changes.
+4. **Store in env** — `TEST_USER_EMAIL`, `TEST_USER_PASSWORD` in `.env.test`.
+
+```ts
+beforeAll(async () => {
+  token = await getAuthToken(
+    process.env.TEST_USER_EMAIL!,
+    process.env.TEST_USER_PASSWORD!
+  )
+})
+```
+
+## Response Validation
+
+1. **Assert status first** — `.expect(200)` before body checks.
+2. **Prefer partial match** — Use `toMatchObject` for dynamic fields (id, createdAt).
+3. **Schema validation** — Use Zod/Joi for contract compliance when OpenAPI is available.
+4. **Avoid over-asserting** — Test what matters; don't lock in implementation details.
+
+## Error Scenarios
+
+Cover at least:
+
+- **Success** — 200/201/204 as per contract
+- **Validation error** — 400 with error payload
+- **Unauthorized** — 401 when missing/invalid auth
+- **Forbidden** — 403 when insufficient permissions
+- **Not found** — 404 for missing resources
+- **Conflict** — 409 for duplicates (where applicable)
+
+## File Naming and Structure
+
+```
+tests/
+  api/
+    users.api.test.ts
+    auth.api.test.ts
+    products.api.test.ts
+  fixtures/
+    seed.ts
+    users.ts
+  helpers/
+    auth.ts
+```
+
+## Avoid
+
+1. **Hardcoded secrets** — Use env vars or test fixtures.
+2. **Testing implementation** — Test behavior and contract, not internal routes.
+3. **Flaky tests** — No sleep/timeout; use deterministic data.
+4. **Large payloads** — Minimize fixture size; use factories for scale.
+5. **External services** — Mock HTTP calls to third-party APIs.
+
+## Parallel Execution
+
+When running tests in parallel:
+
+- Use separate DB/schema per worker, or
+- Use unique data (UUIDs, timestamps) to avoid collisions, or
+- Run API tests sequentially (`--pool=forks` or `--run` with single worker)
+
+## Contract-Driven Tests
+
+When using OpenAPI from qa-api-contract-curator:
+
+1. Generate tests from paths and operations.
+2. Map status codes from `responses` to `.expect()`.
+3. Use `requestBody` schema for `.send()` payloads.
+4. Use `responses.*.content.*.schema` for body validation (Zod/JSON Schema).

package/skills/qa-supertest-writer/references/config.md

@@ -0,0 +1,166 @@
+# Supertest Configuration
+
+## Test Server Configuration
+
+### Express
+
+```ts
+import request from 'supertest'
+import { app } from '../src/app'
+
+// app is the Express instance; no listen() needed
+describe('API', () => {
+  it('works', () => request(app).get('/health').expect(200))
+})
+```
+
+### Koa
+
+```ts
+import request from 'supertest'
+import { app } from '../src/app'
+
+// Koa: use app.callback()
+describe('API', () => {
+  it('works', () => request(app.callback()).get('/health').expect(200))
+})
+```
+
+### HTTP Server (if app is wrapped)
+
+```ts
+import http from 'http'
+import { app } from '../src/app'
+
+const server = http.createServer(app)
+
+describe('API', () => {
+  it('works', () => request(server).get('/health').expect(200))
+})
+```
+
+## Test Runner Setup
+
+### Vitest
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['**/*.api.test.ts'],
+    testTimeout: 10000,
+  },
+})
+```
+
+### Jest
+
+```ts
+// jest.config.js
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/*.api.test.ts'],
+  testTimeout: 10000,
+}
+```
+
+## Database Seeding
+
+### beforeAll (once per suite)
+
+```ts
+import { seedTestData } from '../test/fixtures/seed'
+
+beforeAll(async () => {
+  await seedTestData()
+})
+```
+
+### beforeEach (per test)
+
+```ts
+beforeEach(async () => {
+  await db.users.truncate()
+  await db.users.insert(testUsers)
+})
+```
+
+### Factory-based
+
+```ts
+beforeEach(async () => {
+  await userFactory.create({ email: 'test@example.com' })
+})
+```
+
+## Cleanup
+
+### afterEach
+
+```ts
+afterEach(async () => {
+  await db.users.deleteMany({ email: { $regex: /@test\.example\.com$/ } })
+})
+```
+
+### afterAll
+
+```ts
+afterAll(async () => {
+  await db.disconnect()
+})
+```
+
+## Environment Variables
+
+```ts
+// tests/setup.ts or vitest.config.ts
+process.env.NODE_ENV = 'test'
+process.env.DATABASE_URL = process.env.TEST_DATABASE_URL ?? 'postgres://localhost:5432/test_db'
+```
+
+## Base URL (when testing remote)
+
+```ts
+// For remote API (not typical with Supertest)
+import request from 'supertest'
+
+const baseUrl = process.env.API_BASE_URL ?? 'http://localhost:3000'
+
+describe('Remote API', () => {
+  it('works', () => request(baseUrl).get('/health').expect(200))
+})
+```
+
+## Timeouts
+
+```ts
+// vitest.config.ts
+test: {
+  testTimeout: 15000,  // 15s for slow DB/API tests
+}
+```
+
+## Shared Auth Fixture
+
+```ts
+// tests/helpers/auth.ts
+export async function getAuthToken(): Promise<string> {
+  const res = await request(app)
+    .post('/auth/login')
+    .send({ email: 'test@example.com', password: 'test' })
+  return res.body.token
+}
+```
+
+```ts
+// In test file
+let token: string
+
+beforeAll(async () => {
+  token = await getAuthToken()
+})
+```