Version: 1.0
Date: 2026-08-26
Status: Complete. TFP-001-004 and 010-026 landed 2026-08-28 (af0492d through 69e996f); TFP-033 cce15cf (2026-08-29); TFP-030 92b921b, TFP-032 c965442, TFP-005 and 031 4d58947 (all 2026-09-17). Decision record: docs/decisions/phase-16-local-first-decision-record.md. Reconciled with git 2026-09-29.
Ticket prefix is TFP-. This is distinct from the TFXX-NNN identifiers
TestForge assigns to tests inside generated suites at runtime.
TestForge is an AI-native test automation assistant for testers who understand quality but do not write automation code. A tester describes what to test in plain English; TestForge generates a Playwright suite, runs it, and returns a structured report covering execution, defects, coverage, performance, usability and SEO. It runs on the tester’s own machine against a local target.
localhost:3000 — the single front end since Phase 11.generate, run, crawl, introspect, save-suite.gpt-4o generation of TypeScript .spec.ts Playwright suites, with a
template fallback when no API key is set.app.py) that now only redirects, plus a
backend-proxy layer with no active consumer.TEST_PLAN.md.technical-debt, security, documentationDEPLOYMENT_CHECKLIST.md states “Ready for production
cutover” and .env.production points at a real hostname, while /api/run
executes arbitrary unauthenticated code. Any reader — human or agent — can
reasonably act on those files and expose a shell.DEPLOYMENT_CHECKLIST.md, .env.production, .env.staging.build:staging, build:production, start:staging,
start:production, dev:staging from package.json.!.env.staging and !.env.production allowlist entries from
.gitignore..env.example and
.env.development.ls .env.* lists exactly .env.development and .env.example.package.json script references a deleted env file.npm run build and npm run lint pass.security, documentationREADME.md./api/run executes caller-supplied code with the privileges of
the user running the dev server.README.md and a matching note in .env.example.README.md states the execution model above the installation steps./api/run explicitly.technical-debt, ciartifacts/ are tracked
despite artifacts/ being gitignored — .gitignore does not untrack
retroactively. The committed smoke report claims 1 test passed; there are now
git rm -r --cached artifacts/.artifacts/ remains ignored.git ls-files artifacts | wc -l returns 0.npm run test:self:allure still produces a report at
artifacts/allure-report/smoke.git status is clean after that run..gitattributes and a LICENSEtechnical-debt, chore.gitattributes, the working tree shows every
file as modified whenever git runs from a non-Windows view of the checkout,
which makes diffs unreadable and invites accidental whole-file commits. The
repository also has no licence, leaving reuse terms undefined..gitattributes normalising text files to LF in the index..gitattributes, LICENSE.git status is clean immediately after git add --renormalize . and a
commit.LICENSE exists at the repository root.chorecopilot/* branches remain on origin,
including copilot/install-cplusplus, which has nothing to do with this
project. They add noise to any branch listing and suggest work in flight that
is not.copilot/bridge-gap-between-testers-developers,
copilot/debug-chat-functionality, copilot/debug-chat-functionality-again,
copilot/install-cplusplus from origin.main as its only branch.git branch -r lists only origin/HEAD and origin/main.technical-debt, securityapp.py is a second, entirely untested code-execution
path — CI never installs Python and no pytest suite exists. It has served only
as a redirect since Phase 11, and templates/index.html has been dead since
the legacy UI was removed. Keeping it doubles the security surface for no
functional gain.app.py, requirements.txt, templates/.TESTFORGE_NEXT_UI_URL from .env.example and .env.development..vscode/ configuration.find . -name "*.py" -not -path "./node_modules/*" returns nothing.grep -rn "uvicorn\|fastapi\|pytest" --include="*.json" --include="*.ts" --include="*.md" . | grep -v node_modules returns nothing outside git history.npm run build, npm run lint, npm run test:self and
npm run test:regression all pass.technical-debt, refactorsrc/lib/backend-proxy.ts.isExternalBackendEnabled / proxyJsonRequest /
shouldFallbackToLocalBackend / getBackendBaseUrl branch from all six
routes: generate, run, crawl, introspect, save-suite and health.health must continue to report service status after the proxy metadata is
removed from it.TESTFORGE_BACKEND_BASE_URL from all environment files, README.md,
and the consolidation phase docs’ “current state” sections.grep -rn "TESTFORGE_BACKEND_BASE_URL\|backend-proxy" src .env.* *.md returns nothing.src/lib/backend-proxy.ts does not exist.bug, enhancementplaywright.config.ts declares
all three projects, but README.md and all three CI workflows install Chromium
only. Selecting Cross-Browser on a fresh clone fails with a
browser-not-installed error. The product currently advertises a feature it
cannot perform.cross-browser entry from BEST_PRACTICE_OPTIONS in
src/app/page.tsx and its keyword mapping in BEST_PRACTICE_KEYWORDS.firefox and webkit projects from playwright.config.ts.calculateWorkerCount,
calculateRunTimeout and the browserProjects construction in
src/app/api/run/route.ts.playwright.config.ts declares exactly one project.grep -rni "firefox\|webkit" src playwright.config.ts returns nothing.npx playwright install chromium.ci, chorepr-validation.yml and self-test.yml both trigger on
pull_request and both run lint → build → smoke. Every PR pays for the same
work twice, and a failure appears as two unrelated red checks.pull_request among its triggers.documentationREADME.md describes a Python pytest-playwright
product that no longer exists — the app generates TypeScript .spec.ts suites
run by the Playwright CLI. Its getting-started path ends at localhost:8000,
which redirects to a Next.js server the README never tells the reader to start.
Following the README start to finish does not produce a working application.npm install →
npx playwright install chromium → cp .env.example .env →
docker compose up -d → npm run dev → localhost:3000.package.json.README.md that is executable start to finish on a clean machine.README.md contains no occurrence of pytest, uvicorn, FastAPI,
requirements.txt, or .py.package.json script or a
documented external binary.src/lib/report/refactor, technical-debtsrc/app/page.tsx (HTML document builders, status mapping, fallback tables)
and src/app/api/run/route.ts (summary, defect, coverage, performance,
usability and SEO builders). The two must agree and nothing enforces it. This
is also the largest single body of logic that has no reason to live in either
file.src/lib/report/ with modules for types, HTML document building,
status mapping, and each report-section builder.buildReportHtmlDocument, buildExecutionOutputHtmlDocument,
buildResultHtmlDocument, escapeReportHtml, mapFallbackExecutionStatus,
and the fallback status helpers out of page.tsx.buildDefects, buildCoverageMatrix, buildSummary,
buildPerformanceReport, buildUsabilityReport, buildSeoReport,
buildDefectTrend and flattenSuites out of run/route.ts.src/lib/report/ with no module over 400 lines.page.tsx and run/route.ts declare no report-building function.refactor, technical-debtsrc/app/api/run/route.ts is 2,226 lines covering job
lifecycle, process spawning, progress reporting, output parsing, artifact
collection and rerun selection. No agent can hold it in view, and every change
to it produces an unreviewable diff.src/lib/run/jobs.ts.src/lib/run/executor.ts.src/lib/run/output.ts.src/lib/run/selection.ts.route.ts as request handling and validation only.src/lib/run/ modules; route.ts under 300 lines.wc -l src/app/api/run/route.ts reports under 300.src/lib/run/ exceeds 500 lines.refactor, technical-debtsrc/app/api/generate/route.ts is 2,415 lines, most of
it prompt construction, input normalisation and the ~100-line no-API-key mock
generator. The system prompt is the single highest-value thing in the product
to review and iterate on, and it currently shares a file with 2,300 lines of
unrelated code.src/lib/generate/prompt.ts.src/lib/generate/mock.ts.normalizeBaseUrl, normalizeSelectedPractices,
normalizeContentProfile, normalizeContentRules, normalizeTestAuditMode
into src/lib/generate/normalize.ts.route.ts as request handling and the OpenAI call only.src/lib/generate/ modules; route.ts under 200 lines.wc -l src/app/api/generate/route.ts reports under 200.OPENAI_API_KEY both produce runnable suites.page.tsx into section componentsrefactor, technical-debtsrc/app/page.tsx is 4,739 lines, of which the Home
component alone is 2,766. It is the worst review surface in the repository and
the file most likely to be edited by an agent working from partial context.CollapsibleSection, Chevron,
MetricCard, ReportPanel, DonutChart, LegendRow, SeverityBar,
TrendBars, ExecutionTable, FallbackExecutionTable) into
src/app/_components/.src/app/_hooks/.page.tsx as composition and top-level state only.src/app/_components/ and src/app/_hooks/; page.tsx under 400 lines.wc -l src/app/page.tsx reports under 400.src/app/_components/ or src/app/_hooks/ exceeds 500 lines.ci, choremax-lines rule for src/ at the decision record’s 500-line
limit.eslint.config.mjs.npm run lint fails when any file under src/ exceeds 500 lines.npm run lint passes on the decomposed codebase with no suppressions.refactor, generatorsrc/lib/generate/mock.ts is 2,028 lines and was never
itself a decomposition target — TFP-022 extracted it out of the API route but
did not further break it up. It is the deterministic generator, the core of
the product’s non-AI path, and it now fails the TFP-024 lint gate.src/lib/generate/mock/ submodules.buildActionableElementTests, buildTestMyLinksAuditTests,
buildContentSuites, and buildSharedBestPracticeSuites/buildGenericSuites
into their own modules, grouped by the concern they generate tests for.buildDemoQaSuites into its own module. This ticket only relocates
it — whether the demoqa.com special case is kept, generalized, or removed is
a separate, not-yet-made product decision and is out of scope here.mock.ts (or a thin index.ts) exporting mockGenerate and
re-exporting the public surface consumed by src/app/api/generate/route.ts.src/lib/generate/mock/ module split; no behavior change to generated
suite output.src/lib/generate/ exceeds 500 lines.npm run lint passes with no suppressions.buildDemoQaSuites’s behavior and call sites are unchanged — relocated, not
altered.refactor, introspectionsrc/app/api/introspect/route.ts is 850 lines and was
never ticketed for decomposition — it predates the audit that scoped TFP-020
through TFP-023, and it now fails the TFP-024 lint gate. Nearly all of it is
one POST handler wrapping a single large in-browser page.evaluate
DOM-scraping closure.page.evaluate) into a standalone, self-contained function in
src/lib/introspect/dom-snapshot.ts, passed to page.evaluate by
reference. It already takes all its inputs through the destructured
argument object, so no closure-captured state needs to move.chromium.launch, page.goto, warnings collection, snapshot assembly)
into src/lib/introspect/inspector.ts as an inspectPages(baseUrl, paths)
function.route.ts with only request parsing, the existing
normalizeBaseUrl/getDefaultInspectionPath/normalizePaths/
cleanTextList helpers (or their relocation), and the POST handler
calling inspectPages and returning the response.src/lib/introspect/ module split; route.ts reduced to request/response
wiring.wc -l src/app/api/introspect/route.ts reports under 200.src/lib/introspect/ exceeds 500 lines.npm run lint passes with no suppressions.TEST_PLAN.mddocumentation, testingTEST_PLAN.md at the repository root./api/run execution model.testing/api/health reports local in-process mode.tests/regression/..env.development.Moved word for word from docs/test-plan/HLT.md by TFP-253; the case’s row there links here.
Test: GET /api/health (automated: tests/regression/testforge.sections.spec.ts — “reports health and observability metadata”)
Expected result: Response is ok; JSON body includes status: "ok", service: "testforge-next", a string environment, mode: "local-in-process" (TFP-031 — every route runs in-process since TFP-010/011 deleted the FastAPI proxy layer, so there is no other mode to report), a siteUrl containing http, and an ISO timestamp; response carries X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, a Permissions-Policy restricting camera, and a Content-Security-Policy with default-src 'self'.
documentationrunJobs map), artifact storage, and per-tenant isolation as
prerequisites.docs/decisions/saas-prerequisites.md.bug, introspectionid-tagged javascript: or tel: href survives
the early-return filter in captureDomSnapshot’s link scan
(src/lib/introspect/dom-snapshot.ts) but then falls through to
fallbackHref = rawHref || (anchorId ? ... : ""), which — because rawHref
is truthy — never reaches the anchor-id fallback the filter’s own condition
implies. inferLinkType has no case for these schemes, so new URL(...)
resolves an opaque cross-origin URL and classifies the link external. That
link then flows into every request.get(link.url, ...) call in
src/lib/generate/mock/link-audits/ (coverage-tests.ts,
interaction-tests.ts, detail-tests.ts, experience-tests.ts), where
Playwright throws TypeError: apiRequestContext.get: Request path contains
unescaped characters — an uncaught crash, not a clean test failure.
Reproduced live against demoqa.com’s /links page (a javascript:-href
link labeled “Created”, carrying an id attribute). This will hit any real
site with id-tagged javascript:/tel: links — a common click-to-call or
JS-hook pattern — not just this practice page.src/lib/introspect/dom-snapshot.ts, correct the anchor-link branch so
an id-tagged javascript:/tel: link is classified as its own
linkType (not internal/external/download) rather than falling
through to new URL() resolution.linkDetails for its label/accessible-name value and the
existing protocol-safety check in experience-tests.ts, but ensure
coverage-tests.ts, interaction-tests.ts, detail-tests.ts, and
experience-tests.ts’s own request.get(link.url, ...) call sites never
receive a javascript:/tel: URL.javascript:/tel: links that have no id
attribute — those are already correctly dropped.experience-tests.ts protocol-safety assertion
(the one that correctly flags javascript: hrefs) beyond what’s needed to
keep it working under the corrected classification.src/lib/introspect/dom-snapshot.ts.id-tagged javascript: href
(reproducing the “Created” case) and an id-tagged tel: href:
introspecting it produces LinkDetails for both, with linkType outside
internal/external/download.TypeError: apiRequestContext.get crash.javascript:-protocol-safety test (experience-tests.ts)
still fires and still fails on the javascript: link — this ticket fixes
the crash, not the protocol-safety flag itself.npm run lint passes..gitattributes and LICENSEpage.tsxTEST_PLAN.mdTFP-001 through TFP-004 have no dependencies and are ordered first because they are cheap and remove the most misleading content in the repository. TFP-005 is last because branch deletion is irreversible and worth doing only once the phase is otherwise settled. TFP-020 precedes TFP-021, TFP-022 and TFP-023 because all three shrink substantially once report construction has already moved out — doing them in the other order means moving the same code twice. TFP-025 and TFP-026 follow TFP-024 because the lint gate it added is what surfaced them: both decompose files that TFP-020 through TFP-023’s original scoping missed, and both must land before Gate C can be honestly declared complete. TFP-033 depends on TFP-026 because it touches the same introspection module that ticket just finished decomposing, and it was found by exercising the shipped Phase 16 build against a real site rather than by any ticket in the original scope — it predates Phase 16 and is not a Gate requirement, but it should land before Phase 17 is locked.
git ls-files artifacts returns nothing.README.md states the local-execution security model.git status is clean on a fresh checkout from any platform.grep -rn "TESTFORGE_BACKEND_BASE_URL" returns nothing outside git history.playwright.config.ts declares one project.README.md is executable start to finish on a clean machine.src/ exceeds 500 lines, with one documented exception:
src/lib/introspect/dom-snapshot.ts, the function passed by reference to
Playwright’s page.evaluate (see the decision record, Decision 5).npm run lint enforces that limit.TEST_PLAN.md exists and maps every automated test to a case ID.docs/decisions/saas-prerequisites.md records what a deployed version needs.README.md.