@brunosps00/dev-workflow 0.8.0 → 0.8.1

package/scaffold/skills/api-testing-recipes/recipes/pytest-httpx.md

@@ -0,0 +1,157 @@
+# Recipe: `pytest + httpx` (Python)
+
+Use when the project already runs `pytest` (FastAPI, Starlette, Flask + pytest-flask). The async client matches FastAPI's design and gives you fixtures + parametrize for free.
+
+## File shape
+
+`{{PRD_PATH}}/QA/scripts/api/test_RF_XX_[slug].py`
+
+```python
+"""RF-XX [slug] — API QA suite."""
+import os
+import pytest
+import httpx
+
+BASE = os.environ["API_BASE_URL"]
+TOKEN_ADMIN = os.environ["QA_TOKEN_ADMIN"]
+TOKEN_USER = os.environ["QA_TOKEN_USER"]
+TOKEN_OTHER_ORG = os.environ.get("QA_TOKEN_OTHER_ORG", "")
+
+
+@pytest.fixture
+async def client():
+    async with httpx.AsyncClient(base_url=BASE, timeout=10.0) as c:
+        yield c
+
+
+def auth(token: str) -> dict:
+    return {"Authorization": f"Bearer {token}"}
+
+
+# ---------- happy path ----------
+
+@pytest.mark.asyncio
+async def test_create_user_happy_path(client):
+    r = await client.post("/users", headers=auth(TOKEN_ADMIN),
+                          json={"email": "qa@example.com", "name": "QA"})
+    assert r.status_code == 201, r.text
+    body = r.json()
+    assert body["id"]
+    assert body["email"] == "qa@example.com"
+    pytest.created_user_id = body["id"]   # share via module attr or use a fixture
+
+
+# ---------- 4xx validation ----------
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("payload, missing_field", [
+    ({"name": "No email"}, "email"),
+    ({"email": "no-name@x.com"}, "name"),
+    ({"email": "not-an-email", "name": "X"}, "email"),
+])
+async def test_create_user_validation(client, payload, missing_field):
+    r = await client.post("/users", headers=auth(TOKEN_ADMIN), json=payload)
+    assert r.status_code == 422, r.text
+    assert missing_field in r.json()["error"]["message"].lower()
+
+
+# ---------- 4xx auth ----------
+
+@pytest.mark.asyncio
+async def test_create_user_no_token(client):
+    r = await client.post("/users", json={"email": "x@y.com", "name": "x"})
+    assert r.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_create_user_expired_token(client):
+    r = await client.post("/users",
+                          headers={"Authorization": "Bearer expired.token.here"},
+                          json={"email": "x@y.com", "name": "x"})
+    assert r.status_code == 401
+
+
+# ---------- 4xx authz cross-tenant ----------
+
+@pytest.mark.asyncio
+async def test_get_user_other_org_denied(client):
+    if not TOKEN_OTHER_ORG:
+        pytest.skip("QA_TOKEN_OTHER_ORG not set")
+    r = await client.get(f"/users/{pytest.created_user_id}",
+                         headers=auth(TOKEN_OTHER_ORG))
+    assert r.status_code in (403, 404)
+
+
+# ---------- contract drift ----------
+
+@pytest.mark.asyncio
+async def test_get_user_contract(client):
+    r = await client.get(f"/users/{pytest.created_user_id}",
+                         headers=auth(TOKEN_ADMIN))
+    assert r.status_code == 200
+    body = r.json()
+    for field in ("id", "email", "name", "created_at"):
+        assert field in body, f"missing {field}"
+    for leaked in ("password_hash", "internal_id", "_raw"):
+        assert leaked not in body, f"leaked {leaked}"
+```
+
+## Configuration
+
+`pyproject.toml` (or `pytest.ini`):
+
+```toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["QA/scripts/api"]
+```
+
+## Running
+
+```bash
+# all RF tests
+pytest QA/scripts/api/
+
+# one RF
+pytest QA/scripts/api/test_RF_01_create_user.py -v
+
+# capture log to QA/logs/api/
+pytest QA/scripts/api/ -v --tb=short 2>&1 | tee QA/logs/api/run-$(date +%F).log
+```
+
+## Logging request/response (for QA evidence)
+
+Wrap `client` to log every call:
+
+```python
+import json, time
+from pathlib import Path
+
+LOG = Path("QA/logs/api/RF-XX-create-user.log")
+
+class LoggingClient(httpx.AsyncClient):
+    async def request(self, method, url, **kw):
+        start = time.time()
+        r = await super().request(method, url, **kw)
+        ms = int((time.time() - start) * 1000)
+        LOG.parent.mkdir(parents=True, exist_ok=True)
+        with LOG.open("a") as f:
+            f.write(json.dumps({
+                "ts": time.time(),
+                "method": method,
+                "url": str(r.request.url),
+                "status": r.status_code,
+                "ms": ms,
+                "request_body": kw.get("json"),
+                "response_body": r.json() if r.headers.get("content-type", "").startswith("application/json") else None,
+            }) + "\n")
+        return r
+```
+
+## Pros / cons
+
+- **Pro**: parametrize covers the 4xx matrix in one block.
+- **Pro**: fixtures handle auth + setup/teardown cleanly.
+- **Pro**: integrates with existing `pytest` config + CI.
+- **Con**: not portable to non-Python projects.
+- **Con**: requires `httpx` and `pytest-asyncio` in dev deps.

package/scaffold/skills/api-testing-recipes/recipes/rust-reqwest.md

@@ -0,0 +1,173 @@
+# Recipe: `reqwest + tokio::test` (Rust)
+
+Use for Axum, Actix-web, Rocket. Async HTTP client that pairs naturally with each framework's tower / actix-rt runtime.
+
+Two execution modes:
+
+- **A: against a running server** — best when the project already exposes the API in dev.
+- **B: in-process via `axum::Router::oneshot`** — fastest, no port, no flake.
+
+## File shape (mode A — running server, framework-agnostic)
+
+`{{PRD_PATH}}/QA/scripts/api/rf_xx_[slug].rs` (typically a `tests/` integration target):
+
+```rust
+// RF-XX [slug] — API QA suite
+use reqwest::{Client, StatusCode};
+use serde_json::{json, Value};
+
+fn base() -> String { std::env::var("API_BASE_URL").unwrap_or_else(|_| "http://localhost:3000".into()) }
+fn token_admin() -> String { std::env::var("QA_TOKEN_ADMIN").unwrap_or_default() }
+fn token_other() -> String { std::env::var("QA_TOKEN_OTHER_ORG").unwrap_or_default() }
+
+fn client() -> Client {
+    Client::builder().timeout(std::time::Duration::from_secs(10)).build().unwrap()
+}
+
+#[tokio::test]
+async fn happy_path_returns_201() {
+    let r = client().post(format!("{}/users", base()))
+        .bearer_auth(token_admin())
+        .json(&json!({ "email": format!("qa-{}@example.com", uuid::Uuid::new_v4()), "name": "QA" }))
+        .send().await.unwrap();
+    assert_eq!(r.status(), StatusCode::CREATED);
+    let body: Value = r.json().await.unwrap();
+    assert!(body.get("id").is_some());
+}
+
+#[tokio::test]
+async fn validation_missing_email_returns_422() {
+    let r = client().post(format!("{}/users", base()))
+        .bearer_auth(token_admin())
+        .json(&json!({ "name": "No email" }))
+        .send().await.unwrap();
+    assert_eq!(r.status(), StatusCode::UNPROCESSABLE_ENTITY);
+    let body: Value = r.json().await.unwrap();
+    let msg = body["error"]["message"].as_str().unwrap_or_default().to_lowercase();
+    assert!(msg.contains("email"));
+}
+
+#[tokio::test]
+async fn no_token_returns_401() {
+    let r = client().post(format!("{}/users", base()))
+        .json(&json!({ "email": "x@y.com", "name": "x" }))
+        .send().await.unwrap();
+    assert_eq!(r.status(), StatusCode::UNAUTHORIZED);
+}
+
+#[tokio::test]
+async fn cross_tenant_denied() {
+    if token_other().is_empty() { return; }
+    let r = client().get(format!("{}/users/{}", base(), "00000000-0000-0000-0000-000000000001"))
+        .bearer_auth(token_other())
+        .send().await.unwrap();
+    assert!(matches!(r.status(), StatusCode::FORBIDDEN | StatusCode::NOT_FOUND));
+}
+
+#[tokio::test]
+async fn contract_required_fields_present_no_leaks() {
+    let create = client().post(format!("{}/users", base()))
+        .bearer_auth(token_admin())
+        .json(&json!({ "email": format!("c-{}@example.com", uuid::Uuid::new_v4()), "name": "C" }))
+        .send().await.unwrap();
+    let created: Value = create.json().await.unwrap();
+    let id = created["id"].as_str().unwrap();
+
+    let get = client().get(format!("{}/users/{}", base(), id))
+        .bearer_auth(token_admin())
+        .send().await.unwrap();
+    assert_eq!(get.status(), StatusCode::OK);
+    let body: Value = get.json().await.unwrap();
+
+    for f in ["id", "email", "name", "created_at"] { assert!(body.get(f).is_some(), "missing {f}"); }
+    for leak in ["password_hash", "internal_id", "_raw"] {
+        assert!(body.get(leak).is_none(), "leaked {leak}");
+    }
+}
+```
+
+## File shape (mode B — Axum in-process via `Router::oneshot`)
+
+```rust
+use axum::body::Body;
+use axum::http::{Request, StatusCode};
+use http_body_util::BodyExt;
+use my_app::build_router;
+use serde_json::{json, Value};
+use tower::util::ServiceExt;
+
+#[tokio::test]
+async fn happy_path_oneshot() {
+    let app = build_router().await;
+    let req = Request::post("/users")
+        .header("authorization", "Bearer test-admin")
+        .header("content-type", "application/json")
+        .body(Body::from(json!({"email":"qa@example.com","name":"QA"}).to_string()))
+        .unwrap();
+    let res = app.oneshot(req).await.unwrap();
+    assert_eq!(res.status(), StatusCode::CREATED);
+    let bytes = res.into_body().collect().await.unwrap().to_bytes();
+    let body: Value = serde_json::from_slice(&bytes).unwrap();
+    assert!(body.get("id").is_some());
+}
+```
+
+`build_router()` is the project's exported async function that returns the `axum::Router` — same one used in `main.rs`.
+
+## Configuration
+
+`Cargo.toml`:
+
+```toml
+[dev-dependencies]
+reqwest = { version = "0.12", features = ["json", "rustls-tls"] }
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+serde_json = "1"
+uuid = { version = "1", features = ["v4"] }
+# mode B (Axum):
+http-body-util = "0.1"
+tower = { version = "0.5", features = ["util"] }
+```
+
+## Running
+
+```bash
+# all
+cargo test --test rf_xx_create_user -- --nocapture
+
+# log to QA/logs/api/
+cargo test --test rf_xx_create_user -- --nocapture 2>&1 \
+  | tee "QA/logs/api/run-$(date +%F).log"
+```
+
+## Logging request/response
+
+`reqwest` doesn't ship a logging middleware out of the box. Two options:
+
+- **Wrap at the test layer**: small helper that calls `client.execute(req)` and writes JSONL.
+- **Tower middleware in mode B**: insert a `tower::Layer` that logs request/response. Reuse the project's tracing/logging layer if it has one.
+
+```rust
+use std::fs::OpenOptions;
+use std::io::Write;
+
+async fn log_request(method: &str, url: &str, status: u16, ms: u128, body: &str) {
+    std::fs::create_dir_all("QA/logs/api").ok();
+    let mut f = OpenOptions::new().create(true).append(true)
+        .open("QA/logs/api/RF-XX-create-user.log").unwrap();
+    let entry = serde_json::json!({
+        "ts": chrono::Utc::now().timestamp_millis(),
+        "method": method, "url": url, "status": status, "ms": ms,
+        "response_body": body,
+    });
+    writeln!(f, "{entry}").ok();
+}
+```
+
+## Pros / cons
+
+- **Pro (mode B)**: in-process, no port, fastest, deterministic.
+- **Pro**: `tokio::test` integrates with the project's existing `cargo test` flow.
+- **Pro**: type-safe assertions on response bodies.
+- **Con (mode A)**: depends on the server being up before `cargo test`.
+- **Con (mode B)**: requires the project to expose a `build_router()` factory.

package/scaffold/skills/api-testing-recipes/recipes/supertest-node.md

@@ -0,0 +1,153 @@
+# Recipe: `supertest` (Node.js / TypeScript)
+
+Use for Fastify, Express, NestJS projects that already run `vitest` or `jest`. supertest binds directly to the app instance and runs in-process — no port allocation, no flake.
+
+## File shape
+
+`{{PRD_PATH}}/QA/scripts/api/RF-XX-[slug].test.ts`
+
+```ts
+// RF-XX [slug] — API QA suite
+import request from 'supertest';
+import { describe, expect, it, beforeAll } from 'vitest';
+import { buildApp } from '../../../src/app'; // or: import app from '../../../src/server';
+
+const BASE = process.env.API_BASE_URL ?? 'http://localhost:3000';
+const TOKEN_ADMIN = process.env.QA_TOKEN_ADMIN ?? '';
+const TOKEN_USER = process.env.QA_TOKEN_USER ?? '';
+const TOKEN_OTHER_ORG = process.env.QA_TOKEN_OTHER_ORG ?? '';
+
+let app: Awaited<ReturnType<typeof buildApp>>;
+let createdUserId: string;
+
+beforeAll(async () => { app = await buildApp(); });
+
+const auth = (t: string) => ({ Authorization: `Bearer ${t}` });
+
+describe('RF-XX create user', () => {
+
+  it('happy path returns 201 and id', async () => {
+    const r = await request(app.server).post('/users')
+      .set(auth(TOKEN_ADMIN))
+      .send({ email: `qa-${Date.now()}@example.com`, name: 'QA' });
+    expect(r.status).toBe(201);
+    expect(r.body.id).toBeDefined();
+    createdUserId = r.body.id;
+  });
+
+  it.each([
+    [{ name: 'No email' }, 'email'],
+    [{ email: 'no-name@x.com' }, 'name'],
+    [{ email: 'not-an-email', name: 'X' }, 'email'],
+  ])('validation: %j → mentions %s', async (payload, missing) => {
+    const r = await request(app.server).post('/users')
+      .set(auth(TOKEN_ADMIN))
+      .send(payload);
+    expect(r.status).toBe(422);
+    expect(r.body.error.message.toLowerCase()).toContain(missing);
+  });
+
+  it('no token returns 401', async () => {
+    const r = await request(app.server).post('/users')
+      .send({ email: 'x@y.com', name: 'x' });
+    expect(r.status).toBe(401);
+  });
+
+  it('expired token returns 401', async () => {
+    const r = await request(app.server).post('/users')
+      .set({ Authorization: 'Bearer expired.token.here' })
+      .send({ email: 'x@y.com', name: 'x' });
+    expect(r.status).toBe(401);
+  });
+
+  it('cross-tenant access denied', async () => {
+    if (!TOKEN_OTHER_ORG) return;
+    const r = await request(app.server).get(`/users/${createdUserId}`)
+      .set(auth(TOKEN_OTHER_ORG));
+    expect([403, 404]).toContain(r.status);
+  });
+
+  it('contract: required fields present, leaked fields absent', async () => {
+    const r = await request(app.server).get(`/users/${createdUserId}`)
+      .set(auth(TOKEN_ADMIN));
+    expect(r.status).toBe(200);
+    for (const f of ['id', 'email', 'name', 'created_at']) {
+      expect(r.body[f]).toBeDefined();
+    }
+    for (const f of ['password_hash', 'internal_id', '_raw']) {
+      expect(r.body[f]).toBeUndefined();
+    }
+  });
+});
+```
+
+## Configuration
+
+`vitest.config.ts`:
+
+```ts
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+  test: {
+    include: ['QA/scripts/api/**/*.test.ts'],
+    testTimeout: 10_000,
+    hookTimeout: 30_000,
+  },
+});
+```
+
+## Running
+
+```bash
+# all
+pnpm vitest run QA/scripts/api
+
+# one RF
+pnpm vitest run QA/scripts/api/RF-01-create-user.test.ts
+
+# log to QA/logs/api/
+pnpm vitest run QA/scripts/api 2>&1 | tee "QA/logs/api/run-$(date +%F).log"
+```
+
+## Logging request/response
+
+Wrap the supertest agent in a small helper that emits to JSONL:
+
+```ts
+import fs from 'node:fs';
+
+const LOG = 'QA/logs/api/RF-XX-create-user.log';
+fs.mkdirSync('QA/logs/api', { recursive: true });
+
+function logRequest(method: string, url: string, status: number, ms: number, reqBody: unknown, resBody: unknown) {
+  fs.appendFileSync(LOG, JSON.stringify({
+    ts: Date.now(), method, url, status, ms, request_body: reqBody, response_body: resBody,
+  }) + '\n');
+}
+```
+
+## NestJS variant
+
+Use `@nestjs/testing`'s `Test.createTestingModule(...)` + `app.getHttpServer()` instead of `buildApp`:
+
+```ts
+import { Test } from '@nestjs/testing';
+import { AppModule } from '../../../src/app.module';
+
+let app: INestApplication;
+beforeAll(async () => {
+  const moduleRef = await Test.createTestingModule({ imports: [AppModule] }).compile();
+  app = moduleRef.createNestApplication();
+  await app.init();
+});
+
+// then: request(app.getHttpServer()) ...
+```
+
+## Pros / cons
+
+- **Pro**: in-process, no port allocation, fastest possible.
+- **Pro**: integrates with `vitest`/`jest` watch + coverage.
+- **Pro**: `it.each` covers the 4xx matrix in one block.
+- **Con**: only works against a `supertest`-compatible HTTP framework.
+- **Con**: requires the `buildApp` factory pattern; one-off scripts/handlers may need refactor.

package/scaffold/skills/api-testing-recipes/references/auth-patterns.md

@@ -0,0 +1,138 @@
+# Auth patterns — how to wire credentials into API tests
+
+Tests need real credentials, but credentials must never live in the script files (which are committed). This file describes how each recipe handles the four common auth schemes and where credentials come from.
+
+## The four schemes
+
+| Scheme | How it travels | Recipe handling |
+|--------|----------------|-----------------|
+| **Bearer JWT** | `Authorization: Bearer <token>` | Most common. Token comes from a login response or pre-issued for QA. |
+| **Cookie session** | `Cookie: session=<sid>` (set by `Set-Cookie` on login) | Recipes capture the cookie from a login call and replay it. |
+| **API key** | `X-API-Key: <key>` (header) or `?api_key=<key>` (query) | Header form is preferred; key comes from a per-environment env var. |
+| **Basic auth** | `Authorization: Basic <base64(user:pass)>` | Rare in modern APIs; supported but discouraged. |
+
+## Where credentials come from (in priority order)
+
+1. **`.env` file** at the repo root, gitignored. Contains `QA_TOKEN_ADMIN`, `QA_ADMIN_EMAIL`, `QA_ADMIN_PASSWORD`, etc.
+2. **Pre-issued QA tokens** — long-lived JWTs minted by an admin tool (e.g., a `make qa-tokens` target) and stored in `.env`. Best for CI; avoids login-time flake.
+3. **Login at runtime** — a setup request hits `/auth/login` with `QA_ADMIN_EMAIL` + `QA_ADMIN_PASSWORD` and captures the token. Use when no pre-issued option exists.
+4. **`.dw/templates/qa-test-credentials.md`** — the project-level QA credentials registry that `dw-run-qa` already reads (UI mode). API mode reads the same file for env-var hints + role mapping.
+
+## Three roles every project should have
+
+Even for single-tenant apps, define at minimum:
+
+- **`token_admin`** — has every permission. Used for setup (create test data) and teardown.
+- **`token_user`** — regular authenticated user. The role most happy-path tests run as.
+- **`token_guest`** OR **`token_other_org_admin`** — for negative tests. In multi-tenant apps, this token belongs to a different org and powers the cross-tenant denial tests.
+
+## Per-recipe variable conventions
+
+### `.http` (REST Client)
+
+Top of the file:
+
+```http
+@base = {{$dotenv API_BASE_URL}}
+@token_admin = {{$dotenv QA_TOKEN_ADMIN}}
+@token_user = {{$dotenv QA_TOKEN_USER}}
+@token_other_org = {{$dotenv QA_TOKEN_OTHER_ORG}}
+```
+
+Or, if logging in at runtime, capture once and reuse:
+
+```http
+### Setup — login as admin
+# @name login_admin
+POST {{base}}/auth/login
+Content-Type: application/json
+{ "email": "{{$dotenv QA_ADMIN_EMAIL}}", "password": "{{$dotenv QA_ADMIN_PASSWORD}}" }
+
+> {%
+client.global.set("token_admin", response.body.access_token);
+client.test("login ok", () => client.assert(response.status === 200));
+%}
+```
+
+### `pytest + httpx`
+
+Read from environment in module scope; expose as fixtures if the test count grows:
+
+```python
+TOKEN_ADMIN = os.environ["QA_TOKEN_ADMIN"]
+TOKEN_USER = os.environ["QA_TOKEN_USER"]
+TOKEN_OTHER_ORG = os.environ.get("QA_TOKEN_OTHER_ORG", "")
+
+@pytest.fixture(scope="session")
+async def admin_client():
+    async with httpx.AsyncClient(base_url=BASE,
+        headers={"Authorization": f"Bearer {TOKEN_ADMIN}"},
+        timeout=10.0) as c:
+        yield c
+```
+
+### `supertest` (Node)
+
+Same `process.env` reads, optionally one helper per role:
+
+```ts
+const auth = (token: string) => ({ Authorization: `Bearer ${token}` });
+const TOKEN_ADMIN = process.env.QA_TOKEN_ADMIN!;
+```
+
+### `WebApplicationFactory` (.NET)
+
+Subclass the factory once per role:
+
+```csharp
+public class AdminAppFactory : WebApplicationFactory<Program>
+{
+    protected override void ConfigureClient(HttpClient client)
+    {
+        client.DefaultRequestHeaders.Authorization =
+            new AuthenticationHeaderValue("Bearer",
+                Environment.GetEnvironmentVariable("QA_TOKEN_ADMIN") ?? "");
+    }
+}
+```
+
+### `reqwest` (Rust)
+
+Helper functions read env once:
+
+```rust
+fn token_admin() -> String { std::env::var("QA_TOKEN_ADMIN").unwrap_or_default() }
+fn admin_client() -> reqwest::Client {
+    reqwest::Client::builder().build().unwrap()
+}
+// then: admin_client().get(url).bearer_auth(token_admin()).send().await
+```
+
+## Refresh tokens
+
+If the API uses refresh tokens, capture both `access_token` and `refresh_token` in the login setup. When a test needs a long-lived flow (e.g., wait for a webhook), refresh the access token before the wait.
+
+For most QA suites, the access token's TTL (typically 15-60 min) is longer than the suite's runtime, so refresh is unnecessary.
+
+## Scoped credentials per role
+
+For RBAC-heavy systems, define more roles:
+
+- `token_admin` — global admin
+- `token_org_admin` — admin within one org
+- `token_member` — regular member of one org
+- `token_billing` — read-only billing access
+- `token_other_org_admin` — admin of a different org (for cross-tenant tests)
+
+Add one env var per role; the recipe reads them as needed. Tests that don't need a particular role just don't reference it.
+
+## Anti-patterns
+
+- **Don't hardcode `Bearer eyJ...` in any committed file.** Even "test" tokens leak.
+- **Don't share one token across happy-path AND negative tests.** If a happy-path test mutates the token's user (e.g., suspends it), every later test fails.
+- **Don't reuse production tokens for QA.** Mint QA-only tokens with a clearly distinct subject (`sub: qa-admin@example.com`).
+- **Don't pass credentials via command-line args.** They land in shell history and process listings.
+
+## What `dw-run-qa` does
+
+In API mode, `/dw-run-qa` reads `QA/test-credentials.md` (or `.env`) for the env var names, picks the recipe, and substitutes variables at test-generation time. The script files reference `@variable` references only — never raw tokens.