Historical (April 2026). This describes the consolidation from the FastAPI backend to Next.js. Phase 16 (2026-08-28) deleted the FastAPI backend, the backend-proxy layer and the legacy UI this plan refers to; nothing here describes TestForge today. Kept for history only — see
README.md.
Goal: lock stable request/response contracts for the Next.js UI workflow while the backend implementation is migrated.
Scope for this phase:
Base path: same-origin Next.js API routes under /api/*
Endpoint: POST /api/generate
Request body:
{ “baseUrl”: “string (url)”, “description”: “string (required)”, “selectedPractices”: [ “functional|cross-browser|responsive/mobile|performance/load|security|accessibility|usability|seo/content|cookie/session|database” ], “auditMode”: “fast|deep”, “contentRules”: { “paths”: [”/”], “requiredHeadings”: [“string”], “requiredText”: [“string”], “forbiddenText”: [“string”] }, “contentProfile”: { “scannedAt”: “ISO datetime”, “baseUrl”: “string”, “pages”: [ { “path”: “string”, “url”: “string”, “title”: “string”, “metaDescription”: “string”, “headings”: [“string”], “buttons”: [“string”], “links”: [“string”], “actionableElements”: [], “linkDetails”: [], “visibleTextSnippets”: [“string”] } ], “warnings”: [“string”] } }
Response body:
{ “code”: “string” }
Notes:
contentProfile, the route inspects the pages
itself (the contentRules.paths, or the base URL’s own path) and adds
"generatedBy" ("template" unless another generator set it) and
"pageInspection": { "status": "inspected" | "failed", "paths": [...],
"pages": n, "warnings": [...], "reason"?: "string" } to the response. A
failed inspection never blocks generation. Send "autoInspect": false to opt
out; the response is then exactly as before.Endpoint: POST /api/introspect
Request body:
{ “baseUrl”: “string (url)”, “paths”: [”/”, “/about”] }
Response body:
{ “scannedAt”: “ISO datetime”, “baseUrl”: “string”, “pages”: [ { “path”: “string”, “url”: “string”, “title”: “string”, “metaDescription”: “string”, “headings”: [“string”], “buttons”: [“string”], “links”: [“string”], “actionableElements”: [], “linkDetails”: [], “embeddedLinkDetails”: [], “visibleTextSnippets”: [“string”] } ], “warnings”: [“string”] }
Endpoint: POST /api/crawl
Request body:
{ “baseUrl”: “string (url)” }
Response body:
{ “crawlId”: “string”, “crawlStatus”: “running|completed|failed|cancelled”, “duration”: 0, “progress”: { “maxPages”: 100, “visitedUrls”: 0, “queuedUrls”: 0, “discoveredPages”: 0, “warningsCount”: 0, “currentUrl”: null, “currentPath”: null, “currentTitle”: null, “lastCompletedPath”: null, “lastCompletedTitle”: null }, “result”: { “crawledAt”: “ISO datetime”, “baseUrl”: “string”, “pageCount”: 0, “pages”: [ { “path”: “string”, “url”: “string”, “title”: “string”, “discoveredFrom”: “string|null” } ], “warnings”: [“string”] }, “error”: “string” }
Endpoint: GET /api/crawl?crawlId=…
Response body: same shape as start crawl snapshot.
Endpoint: DELETE /api/crawl
Request body:
{ “crawlId”: “string” }
Response body: same snapshot shape with cancellationRequested reflected via crawlStatus progression to cancelled.
Endpoint: POST /api/run
Request body:
{ “code”: “string (required)”, “selectedPractices”: [“string”], “auditMode”: “fast|deep”, “baseUrl”: “string”, “excludeTestTitles”: [“string”], “includeTestTitles”: [“string”] }
Response body:
{ “runId”: “string”, “runStatus”: “queued|running|passed|failed|cancelled”, “duration”: 0, “cancellationRequested”: false, “progress”: { “totalTests”: 0, “completedTests”: 0, “passed”: 0, “failed”: 0, “blocked”: 0, “flaky”: 0, “runningTestTitle”: null, “plannedExecutions”: [] }, “result”: { “runId”: “string”, “passed”: false, “output”: “string”, “duration”: 0, “report”: { “summary”: {}, “execution”: [], “defects”: {}, “coverage”: {}, “performance”: {}, “usability”: {}, “seo”: {} }, “progress”: { “totalTests”: 0, “completedTests”: 0 } } }
Endpoint: GET /api/run?runId=…
Response body: same run snapshot shape.
Endpoint: DELETE /api/run
Request body:
{ “runId”: “string” }
Response body: same run snapshot shape with cancellationRequested / runStatus transition.
Endpoint: POST /api/save-suite
Request body:
{ “code”: “string (required)”, “description”: “string (required)” }
Response body:
{ “fileName”: “string”, “filePath”: “string”, “suiteTitles”: [“string”] }
Run statuses:
Crawl statuses:
Before Phase 3 implementation starts: