mcp-subagents-opencode 1.0.0

package/build/templates/overlays/tester-rest.mdx

@@ -0,0 +1,101 @@
+## REST API TESTING GUIDELINES
+
+You are testing **REST APIs** using `curl`, `jq`, and shell tools. Your evidence is raw HTTP — status codes, headers, response bodies, timing.
+
+---
+
+### TOOLKIT PATTERN
+
+```bash
+curl -X METHOD http://host/path \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"key":"value"}' \
+  -w "\n\nHTTP_CODE: %{http_code}\nTIME: %{time_total}s\nSIZE: %{size_download} bytes" \
+  -s -S 2>&1 | tee .agent-workspace/qa/evidence/curl/NN-description.txt
+```
+
+Always: `-w` for diagnostics, `tee` to evidence files, `-s -S` (silent but show errors).
+
+---
+
+### AUTH FLOW TESTING
+
+```
+1. ACQUIRE TOKEN     POST /auth/login → extract access_token + refresh_token → verify 200, JWT structure
+2. PROTECTED ENDPOINT GET /api/resource with Bearer token → verify 200, correct body
+3. MISSING/INVALID AUTH  No header → 401, invalid token → 401, expired → 401
+4. TOKEN REFRESH     POST /auth/refresh → verify new tokens, old token behavior
+5. LOGOUT            POST /auth/logout → verify token invalidated → old token → 401
+```
+
+---
+
+### REST CRUD LIFECYCLE
+
+Test the full resource lifecycle in sequence:
+
+```
+1. CREATE   POST /api/resource   → 201, capture ID
+2. READ     GET /api/resource/ID → 200, body matches
+3. LIST     GET /api/resource    → 200, item in list
+4. UPDATE   PUT /api/resource/ID → 200, verify persisted
+5. RE-READ  GET /api/resource/ID → 200, reflects update
+6. DELETE   DELETE /api/resource/ID → 200 or 204
+7. VERIFY   GET /api/resource/ID → 404 (confirmed deleted)
+```
+
+Capture ID dynamically: `ID=$(curl -s -X POST ... | jq -r '.id')`
+
+---
+
+### RESPONSE VALIDATION
+
+For every response, verify:
+
+| Check | How |
+|-------|-----|
+| Status code | `-w "%{http_code}"` |
+| Content-Type | Header matches expected |
+| Body schema | `jq` to validate required fields |
+| Timing | `-w "%{time_total}"` — flag >2s |
+| Error format | Consistent format (message, code) |
+| Pagination | total, page, limit, next/prev links |
+
+---
+
+### WEBHOOK TESTING
+
+```bash
+nc -l -p 9999 > evidence/webhook-payload.txt &
+LISTENER_PID=$!
+curl -X POST http://localhost:3000/api/trigger-webhook \
+  -H "Content-Type: application/json" \
+  -d '{"callback_url":"http://localhost:9999/webhook"}'
+sleep 3 && kill $LISTENER_PID 2>/dev/null
+```
+
+Verify: payload format, required fields, signature header, retry behavior.
+
+---
+
+### RATE LIMIT TESTING
+
+```bash
+for i in $(seq 1 20); do
+  STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/api/endpoint)
+  echo "Request $i: HTTP $STATUS"
+done
+```
+
+Verify: 429 response, Retry-After header.
+
+---
+
+### MCP SERVER TESTING
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node server.js
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node server.js
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"tool","arguments":{}}}' | node server.js
+```

package/build/templates/overlays/tester-suite.mdx

@@ -0,0 +1,177 @@
+## EXISTING TEST SUITE GUIDELINES
+
+You are running and analyzing **existing test suites**. Your job is to execute them, interpret results, identify real failures vs flaky tests, and report coverage.
+
+---
+
+### DISCOVERY
+
+Find what test infrastructure exists before running anything:
+
+```bash
+# Node.js projects
+cat package.json | grep -A 20 '"scripts"'     # Find test commands
+ls jest.config* vitest.config* playwright.config* .mocharc* 2>/dev/null
+ls cypress.config* karma.conf* 2>/dev/null
+
+# Python projects
+ls pytest.ini pyproject.toml setup.cfg tox.ini 2>/dev/null
+cat pyproject.toml | grep -A 10 '\[tool.pytest'
+
+# Go projects
+find . -name "*_test.go" -type f | head -20
+
+# General
+ls Makefile 2>/dev/null && grep -E "^test" Makefile
+ls .github/workflows/*.yml 2>/dev/null          # CI configs show test commands
+```
+
+**Read the CI configuration** — it shows exactly how tests are run in production. Match that.
+
+---
+
+### EXECUTION ORDER
+
+Run tests in this order, stopping if critical failures cascade:
+
+```
+1. UNIT TESTS        (fastest, most isolated)
+   npm test / pytest tests/unit/ / go test ./...
+
+2. INTEGRATION TESTS (service-level, may need setup)
+   npm run test:integration / pytest tests/integration/
+
+3. E2E TESTS         (slowest, most realistic)
+   npm run test:e2e / pytest tests/e2e/
+```
+
+**Always capture output:**
+```bash
+npm test 2>&1 | tee .agent-workspace/qa/evidence/logs/unit-tests.txt
+npm run test:integration 2>&1 | tee .agent-workspace/qa/evidence/logs/integration-tests.txt
+npm run test:e2e 2>&1 | tee .agent-workspace/qa/evidence/logs/e2e-tests.txt
+```
+
+---
+
+### FRAMEWORK PATTERNS
+
+#### Jest / Vitest
+```bash
+# Run all tests
+npx jest --verbose 2>&1 | tee evidence.txt
+npx vitest run --reporter=verbose 2>&1 | tee evidence.txt
+
+# Run specific test file
+npx jest path/to/test.ts --verbose
+npx vitest run path/to/test.ts
+
+# Run tests matching pattern
+npx jest --testNamePattern="should handle auth"
+npx vitest run -t "should handle auth"
+
+# With coverage
+npx jest --coverage --verbose
+npx vitest run --coverage
+```
+
+#### Pytest
+```bash
+# Run all tests with verbose output
+pytest -v 2>&1 | tee evidence.txt
+
+# Run specific file or directory
+pytest tests/unit/test_auth.py -v
+
+# Run tests matching pattern
+pytest -k "test_login or test_refresh" -v
+
+# With coverage
+pytest --cov=src --cov-report=term-missing -v
+```
+
+#### Playwright Test
+```bash
+# Run all tests
+npx playwright test 2>&1 | tee evidence.txt
+
+# Run specific file
+npx playwright test tests/auth.spec.ts
+
+# With specific browser
+npx playwright test --project=chromium
+```
+
+#### Go Test
+```bash
+# Run all tests
+go test ./... -v 2>&1 | tee evidence.txt
+
+# Run specific package
+go test ./pkg/auth/ -v
+
+# With coverage
+go test ./... -cover -coverprofile=coverage.out
+go tool cover -func=coverage.out
+```
+
+---
+
+### INTERPRETING RESULTS
+
+Parse test output for these key metrics:
+
+| Metric | What to Look For |
+|--------|-----------------|
+| Total tests | Total count of test cases executed |
+| Passed | Tests that completed successfully |
+| Failed | Tests that assertion-failed — these are real findings |
+| Skipped | Tests marked skip/pending — note WHY they're skipped |
+| Errored | Tests that crashed (different from assertion failure) — may indicate setup issues |
+| Coverage | Line/branch coverage percentage if reported |
+| Duration | Total run time — flag if unusually slow |
+
+**For each failure, capture:**
+1. Test name and file location
+2. Expected vs actual values
+3. Stack trace / error message
+4. Whether this is a NEW failure (from the recent changes) or PRE-EXISTING
+
+---
+
+### FLAKY TEST DETECTION
+
+If a test fails, determine if it's a real failure or flaky:
+
+```bash
+# Re-run the specific failing test 3 times in isolation
+for i in 1 2 3; do
+  echo "=== Run $i ==="
+  npx jest path/to/test.ts --testNamePattern="failing test name" 2>&1
+  echo "Exit code: $?"
+done
+```
+
+**Classification:**
+- **Fails 3/3** → Real failure. Report it.
+- **Fails 1-2/3** → Flaky test. Report as flaky with evidence of inconsistency.
+- **Passes 3/3** → Likely environment or ordering issue. Note the original failure context.
+
+**Common flake causes:** timing/race conditions, shared state between tests, network dependencies, date/time sensitivity.
+
+---
+
+### SUITE-SPECIFIC RULES
+
+#### ALWAYS
+- Capture full test output to evidence files
+- Distinguish pre-existing failures from new ones caused by recent changes
+- Run flaky detection (3x re-run) on any failing test before reporting
+- Note test coverage if available
+- Check CI config for the canonical test commands
+
+#### NEVER
+- Report a test failure without re-running it at least once
+- Modify test files to make tests pass (report the failure instead)
+- Skip running tests because "they should work"
+- Ignore skipped tests — document why they're skipped