@brunosps00/dev-workflow 0.8.0 → 0.9.0

package/scaffold/skills/api-testing-recipes/recipes/http-rest-client.md

@@ -0,0 +1,130 @@
+# Recipe: `.http` (REST Client) — DEFAULT
+
+Universal API-testing format. One file per RF. Read by VSCode REST Client, JetBrains HTTP Client, Neovim rest.nvim/kulala, Zed Assistant. No test runner needed.
+
+## File shape
+
+`{{PRD_PATH}}/QA/scripts/api/RF-XX-[slug].http`
+
+```http
+### RF-XX [slug] — happy path
+# @name create_user
+POST {{base}}/users
+Authorization: Bearer {{token_admin}}
+Content-Type: application/json
+
+{
+  "email": "qa-{{$randomInt 1 999999}}@example.com",
+  "name": "QA User"
+}
+
+> {%
+client.test("status is 201", () => client.assert(response.status === 201));
+client.test("response has id", () => client.assert(response.body.id != null));
+client.global.set("created_user_id", response.body.id);
+%}
+
+### RF-XX — 4xx validation: missing email
+POST {{base}}/users
+Authorization: Bearer {{token_admin}}
+Content-Type: application/json
+
+{ "name": "No email" }
+
+> {%
+client.test("status is 422", () => client.assert(response.status === 422));
+client.test("error mentions email", () => client.assert(response.body.error.message.toLowerCase().includes("email")));
+%}
+
+### RF-XX — 4xx auth: missing token
+POST {{base}}/users
+Content-Type: application/json
+
+{ "email": "x@y.com", "name": "x" }
+
+> {%
+client.test("status is 401", () => client.assert(response.status === 401));
+%}
+
+### RF-XX — 4xx authz: cross-tenant access
+GET {{base}}/users/{{created_user_id}}
+Authorization: Bearer {{token_other_org_admin}}
+
+> {%
+client.test("status is 403 or 404", () =>
+  client.assert(response.status === 403 || response.status === 404));
+%}
+
+### RF-XX — contract drift: response shape vs OpenAPI
+GET {{base}}/users/{{created_user_id}}
+Authorization: Bearer {{token_admin}}
+
+> {%
+client.test("has required fields", () => {
+  ["id", "email", "name", "created_at"].forEach(f =>
+    client.assert(response.body[f] != null, `missing ${f}`));
+});
+client.test("no leaked internal fields", () => {
+  ["password_hash", "internal_id", "_raw"].forEach(f =>
+    client.assert(response.body[f] === undefined, `leaked ${f}`));
+});
+%}
+```
+
+## Variables
+
+Set once at the top of the file (or in a `http-client.env.json` next to it):
+
+```http
+@base = {{$dotenv API_BASE_URL}}
+@token_admin = {{$dotenv QA_TOKEN_ADMIN}}
+@token_user = {{$dotenv QA_TOKEN_USER}}
+@token_other_org_admin = {{$dotenv QA_TOKEN_OTHER_ORG}}
+```
+
+Or, if the project uses login-based auth, capture the token in a setup request and reference it in subsequent requests:
+
+```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); %}
+```
+
+## Execution from `dw-run-qa` (CLI fallback)
+
+When running outside an IDE (e.g., from the agent in headless mode), parse and execute via `curl`:
+
+```bash
+# For each ### block, extract method/url/headers/body and execute:
+curl -sS -X POST "$BASE/users" \
+  -H "Authorization: Bearer $TOKEN_ADMIN" \
+  -H "Content-Type: application/json" \
+  -d '{"email":"qa-1@example.com","name":"QA"}' \
+  -w '\n%{http_code} %{time_total}s\n' \
+  | tee -a "QA/logs/api/RF-XX-create-user.log"
+```
+
+The `dw-run-qa` agent does this loop automatically and writes to the JSONL log per `references/log-conventions.md`.
+
+## Assertions
+
+Use the inline `> {% ... %}` post-response handler when running in an IDE. For headless `curl` execution, use `jq`:
+
+```bash
+RESP=$(curl -sS ...)
+STATUS=$(echo "$RESP" | head -1 | awk '{print $2}')
+[ "$STATUS" = "201" ] || { echo "FAIL: expected 201, got $STATUS"; exit 1; }
+echo "$RESP" | jq -e '.id != null' >/dev/null || { echo "FAIL: missing id"; exit 1; }
+```
+
+## Pros / cons
+
+- **Pro**: zero install, opens in any IDE, devs read it without running a test runner.
+- **Pro**: each request is a single block, easy to copy-paste into incident tickets.
+- **Con**: no native fixture/teardown — multi-request flows rely on `client.global.set` for state.
+- **Con**: parallel execution requires per-block uniqueness in resource names (use `{{$randomInt}}` or `{{$timestamp}}`).

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.