docs(scripts): add scripts/README.md with token and ID setup instructions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-25 18:36:18 +02:00 · 2026-04-25 18:36:18 +02:00 · 5918b29af3
commit 5918b29af3
parent b6c08851a0
1 changed files with 93 additions and 0 deletions
--- a/scripts/README.md
+++ b/scripts/README.md
@ -0,0 +1,93 @@
+# API Test Scripts
+
+## test-api.sh
+
+Runs curl-based tests against all 7 Scrum4Me API endpoints. Covers happy paths, auth (401), demo-block (403), and input validation (400).
+
+### Prerequisites
+
+| What | How |
+|---|---|
+| Database seeded | `npx prisma db seed` |
+| Dev server running | `npm run dev` |
+| `curl` installed | `curl --version` |
+
+### Step 1 — Get a token for lars
+
+1. Open `http://localhost:3000` in your browser
+2. Log in as `lars` / `scrum4me123`
+3. Go to **Settings → API Tokens**
+4. Click **New token**, give it any label
+5. Copy the token — it is shown only once
+
+Open `scripts/test-api.sh` and paste it into `TOKEN=""`.
+
+### Step 2 — Find your IDs
+
+You need four IDs. The easiest way is to use the API itself:
+
+```bash
+# 1. Get PRODUCT_ID — run this after setting TOKEN
+curl -s -H "Authorization: Bearer <TOKEN>" http://localhost:3000/api/products | grep -o '"id":"[^"]*"' | head -1
+
+# 2. SPRINT_ID — look in the database or the UI (Sprint → copy ID from the URL)
+# 3. STORY_ID  — open a story in the Sprint Board, copy the ID from the URL or the activity log
+# 4. TASK_ID   — open a task, copy its ID
+```
+
+Or query the database directly:
+
+```bash
+# With psql / Neon CLI:
+SELECT id FROM "Sprint" WHERE status = 'ACTIVE' LIMIT 1;
+SELECT id FROM "Story"  WHERE status = 'IN_SPRINT' LIMIT 1;
+SELECT id FROM "Task"   WHERE story_id = '<story-id>' LIMIT 1;
+```
+
+Paste the four values into the variables at the top of `test-api.sh`.
+
+### Step 3 — (Optional) Get a demo token for 403 tests
+
+The 403 demo-block tests are skipped unless you set `DEMO_TOKEN`.
+
+1. Log out, log in as `demo` / `demo1234`
+2. Go to **Settings → API Tokens**, create a token
+3. Paste it into `DEMO_TOKEN=""` in `test-api.sh`
+
+### Step 4 — Run
+
+```bash
+bash scripts/test-api.sh
+```
+
+Expected output when all IDs are set and a demo token is provided:
+
+```
+============================================================
+  Scrum4Me API Test Suite
+  Base URL : http://localhost:3000
+  Token    : scrum4me... (lars)
+  Demo     : demo1234... (403 tests active)
+============================================================
+
+── GET /api/products ──────────────────────────────────────────────
+  PASS  TC-P-09  happy path (lars)
+  PASS  TC-P-01  no token → 401
+  PASS  TC-P-02  invalid token → 401
+
+── GET /api/products/:id/next-story ───────────────────────────────
+  PASS  TC-NS-08  happy path (lars, 200 or 404 both valid)
+  PASS  TC-NS-01  no token → 401
+  ...
+
+============================================================
+  Results: 30 passed, 0 failed
+============================================================
+```
+
+### Notes
+
+- **product_id is required** for `POST /api/todos`. The Zod schema enforces `z.string().min(1)`. Sending a todo without a product_id returns 400.
+- **TC-NS-08** accepts both 200 and 404. After a fresh seed lars has no active sprint, so 404 is the expected response unless you create a sprint and add stories to it.
+- **Reorder test (TC-RO-10)** uses a single task ID. A reorder with one element is valid (sort_order is updated to 1).
+- The todos happy-path test appends `$(date +%s)` to the title to avoid duplicate-title issues on repeated runs.