QA Playbook

Fetch / Map / Crawl QA Reference

Canonical QA checks for API and dashboard flows. This page is aligned to current v1 route behavior. Last updated: 2026-02-24.

1) Setup

Base URL: http://localhost/api/v1

export BASE="http://localhost/api/v1"
export API_KEY="<YOUR_API_KEY>"

2) API Smoke: Fetch

Expected create response: HTTP 200, service=fetch, status=queued.

curl -sS -X POST "$BASE/fetch" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com"],"proxy":{"type":"datacenter"}}'

curl -sS -X POST "$BASE/fetch" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com"],"proxy":{"type":"residential"}}'

3) API Smoke: Map

Expected create response: HTTP 200, service=map, status=queued.

curl -sS -X POST "$BASE/map" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com"],"proxy":{"type":"datacenter"}}'

curl -sS -X POST "$BASE/map" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com"],"proxy":{"type":"residential"}}'

4) API Smoke: Crawl

Expected create response: HTTP 200, service=crawl, status=queued.

curl -sS -X POST "$BASE/crawl" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com"],"max_depth":1,"proxy":{"type":"datacenter"}}'

curl -sS -X POST "$BASE/crawl" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com"],"max_depth":1,"proxy":{"type":"residential"}}'

5) Polling Checks

Typical status flow: queued -> running -> completed/failed.

curl -sS "$BASE/fetch/<FETCH_JOB_ID>" -H "x-api-key: $API_KEY"

curl -sS "$BASE/map/<MAP_JOB_ID>" -H "x-api-key: $API_KEY"

curl -sS "$BASE/crawl/<CRAWL_JOB_ID>" -H "x-api-key: $API_KEY"

6) Required Runtime Checks

runtime.effective_proxy_type matches request proxy type.

runtime.proxy_usage_summary exists (object or null until completion).

Single URL requests include compatibility fields: job_id, poll_url.

Crawl response includes rows[] and counts.status_counts.

7) Crawl Row File Endpoint

Returns presigned URL for row markdown/html artifact.

curl -sS "$BASE/crawl/<CRAWL_JOB_ID>/rows/0/file?type=md" -H "x-api-key: $API_KEY"

8) Negative Cases

Invalid proxy type should return HTTP 400.

curl -sS -X POST "$BASE/fetch" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com"],"proxy":{"type":"mobile"}}'

Invalid URL should return HTTP 400.

curl -sS -X POST "$BASE/fetch" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["not-a-url"]}'

Idempotency replay should return same payload + idempotency_replay=true.

curl -sS -X POST "$BASE/fetch" \
  -H "x-api-key: $API_KEY" \
  -H "Idempotency-Key: qa-edge-001" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com"]}'

9) Dashboard Checklist

/fetch: run datacenter + residential; single URL redirects to detail page.

/map: run both proxy types; verify links JSON download appears after completion.

/crawl: run both proxy types; verify results zip/jsonl/csv links after completion.

Dashboard run uses session auth; browser call should not require API key header.

10) Automated Edge Runner

Runs 10 edge cases and writes a markdown report.

API_BASE_URL="http://localhost/api/v1" \
API_KEY="<YOUR_API_KEY>" \
npm run qa:edge:v1

11) QA Report Format

Case | Endpoint | Proxy | Create HTTP | Terminal Status | effective_proxy_type | Pass/Fail | Notes

Back to API Docs|OpenAPI / Swagger|

If route behavior changes, update this page and `QA_CHECKLIST_FETCH_MAP_CRAWL.md` together.