@rashidee/co2 1.2.5

package/plugin/skills/specgen-node-cli-web/references/testing-patterns.md

@@ -0,0 +1,174 @@
+# Testing & Verification Patterns — specgen-node-cli-web
+
+Canonical patterns for the testing strategy (root spec Section 11) and per-module test
+sections. The verification protocol is the heart of this stack: source-only testing is
+insufficient because shebang, bundling, native-module, and asset-path failures only
+surface against the **built** artifact.
+
+## 1. Verification protocol
+
+`pnpm verify` must pass before any task is complete:
+
+```
+verify = check (tsc -b + biome check .)
+       → test (vitest run)
+       → build (all packages)
+       → smoke (built CLI: --version + smoke-start.mjs)
+```
+
+The **smoke stage is mandatory**. It executes the *built* CLI: starts the app on a random
+port with a temp `--data-dir`, asserts HTTP 200 on `/` and on `/api/health`, asserts the
+printed admin credentials can log in, then shuts down cleanly.
+
+## 2. Unit/integration tests — real DB, never mocked
+
+Tests inject `:memory:` SQLite via the connection factory with real migrations applied.
+Never mock the DB:
+
+```ts
+import { beforeEach, describe, expect, it } from 'vitest'
+import { openDatabase, runMigrations, type Db } from '../../db/index.js'
+import { bootstrapAdmin } from '../../db/bootstrap.js'
+
+let db: Db
+
+beforeEach(() => {
+  db = openDatabase(':memory:')
+  runMigrations(db)
+})
+
+describe('bootstrapAdmin', () => {
+  it('creates the admin with must_change_password on an empty database', () => {
+    const created = bootstrapAdmin(db)
+    expect(created).not.toBeNull()
+    expect(created?.username).toBe('admin')
+    expect(created?.password).toHaveLength(16)
+  })
+
+  it('is a no-op once any user exists', () => {
+    bootstrapAdmin(db)
+    expect(bootstrapAdmin(db)).toBeNull()
+  })
+})
+```
+
+Route tests go through the real Hono app with `app.request()` — no HTTP server needed:
+
+```ts
+import { createApp } from '../../app.js'
+
+it('returns 403 PASSWORD_CHANGE_REQUIRED on guarded routes until the password changes', async () => {
+  const app = createApp({ db, dataDir: ':memory:' })
+  const cookie = await loginAsBootstrappedAdmin(app, db)
+
+  const guarded = await app.request('/api/users', { headers: { cookie } })
+  expect(guarded.status).toBe(403)
+  expect((await guarded.json()).code).toBe('PASSWORD_CHANGE_REQUIRED')
+
+  const change = await app.request('/api/auth/change-password', {
+    method: 'POST',
+    headers: { cookie, 'content-type': 'application/json' },
+    body: JSON.stringify({ currentPassword: BOOT_PASSWORD, newPassword: 'a-longer-password' }),
+  })
+  expect(change.status).toBe(200)
+
+  const after = await app.request('/api/users', { headers: { cookie } })
+  expect(after.status).toBe(200)
+})
+```
+
+### Mandatory coverage (security invariants)
+
+Every generated spec requires tests for:
+
+1. Forced-change middleware — 403 on every guarded route; login/change-password/logout
+   exempt
+2. Last-admin deletion invariant
+3. Session revocation on password change (other sessions revoked, current kept)
+4. Login rate limiting (attempt 11 within the window rejected)
+5. First-run bootstrap no-op on second start
+
+Per business module: every PRD constraint becomes a service-level test; every route gets
+a validation-rejection test (bad body → 400 from zValidator).
+
+## 3. Smoke script
+
+`scripts/smoke-start.mjs` — runs against the built CLI (default) or a globally installed
+command (`--command <name>` for the pre-publish check):
+
+```js
+import { spawn } from 'node:child_process'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const command = getArg('--command') ?? 'node'
+const args = command === 'node' ? ['packages/cli/dist/index.js'] : []
+const port = 3000 + Math.floor(Math.random() * 30000)
+const dataDir = mkdtempSync(join(tmpdir(), 'smoke-'))
+
+const child = spawn(command, [...args, 'start', '--port', String(port), '--data-dir', dataDir], {
+  stdio: ['ignore', 'pipe', 'inherit'],
+})
+
+let stdout = ''
+child.stdout.on('data', (chunk) => {
+  stdout += chunk
+})
+
+try {
+  await waitFor(() => fetchOk(`http://127.0.0.1:${port}/api/health`), 15000)
+  await assertOk(`http://127.0.0.1:${port}/`, 'SPA index')
+  await assertOk(`http://127.0.0.1:${port}/api/health`, 'health endpoint')
+
+  const password = /password:\s+(\S+)/.exec(stdout)?.[1]
+  if (!password) throw new Error('printed admin credentials not found in start output')
+  const login = await fetch(`http://127.0.0.1:${port}/api/auth/login`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ username: 'admin', password }),
+  })
+  if (login.status !== 200) throw new Error(`login with printed credentials failed: ${login.status}`)
+
+  console.log('smoke: OK')
+} finally {
+  child.kill('SIGINT')
+  await new Promise((resolve) => child.once('exit', resolve))
+  rmSync(dataDir, { recursive: true, force: true })
+}
+```
+
+(Include the small `getArg`/`waitFor`/`fetchOk`/`assertOk` helpers in the generated spec
+so the file is complete and runnable.)
+
+## 4. Playwright E2E
+
+`e2e/` runs against a started instance. `playwright.config.ts` uses a `globalSetup` that
+launches the built CLI exactly like the smoke script (random port, temp data dir),
+captures the printed credentials into `process.env`, and tears the process down in
+`globalTeardown`.
+
+The canonical scenario mirrors the full user lifecycle, in order:
+
+1. First-run login with the printed credentials → lands on the forced password change
+   screen
+2. Forced password change succeeds → redirected into the app
+3. Admin creates a second user (temp password)
+4. Second user logs in → forced change → succeeds
+5. Password change from the settings page (with current password) succeeds
+
+Per business module: one spec file exercising the module's list/create/edit/delete flows
+through the real UI, matching the mockup screens.
+
+## 5. Pre-publish check
+
+After `pnpm verify` is green:
+
+```
+npm pack ./packages/cli
+npm i -g ./{{PACKAGE_NAME}}-{{VERSION}}.tgz
+node scripts/smoke-start.mjs --command {{PACKAGE_NAME}}
+```
+
+This validates the `files` whitelist, the shebang, and native-module resolution in the
+exact artifact end users receive.