mr-onion

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.

Phase 2 - API Contract (Canonical)

Goal: lock stable request/response contracts for the Next.js UI workflow while the backend implementation is migrated.

Scope for this phase:

Canonical Surface

Base path: same-origin Next.js API routes under /api/*

Shared Conventions

1) Generate Contract

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:

2) Introspect Contract

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”] }

3) Crawl Contracts

3.1 Start crawl

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” }

3.2 Poll crawl

Endpoint: GET /api/crawl?crawlId=…

Response body: same shape as start crawl snapshot.

3.3 Cancel crawl

Endpoint: DELETE /api/crawl

Request body:

{ “crawlId”: “string” }

Response body: same snapshot shape with cancellationRequested reflected via crawlStatus progression to cancelled.

4) Run Contracts

4.1 Start run

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 } } }

4.2 Poll run

Endpoint: GET /api/run?runId=…

Response body: same run snapshot shape.

4.3 Cancel run

Endpoint: DELETE /api/run

Request body:

{ “runId”: “string” }

Response body: same run snapshot shape with cancellationRequested / runStatus transition.

5) Save Suite Contract

Endpoint: POST /api/save-suite

Request body:

{ “code”: “string (required)”, “description”: “string (required)” }

Response body:

{ “fileName”: “string”, “filePath”: “string”, “suiteTitles”: [“string”] }

Lifecycle Status Semantics

Run statuses:

Crawl statuses:

Backward Compatibility Rules During Migration

Validation Gates For Next Phase

Before Phase 3 implementation starts: