@activate-core/test-forge 1.0.0 → 1.0.2

package/dist/cli/index.js

@@ -19,7 +19,7 @@
  *                                      (an auth-gated page can move unseen).
  */
 import { VERSION } from '../core/index.js';
-import { runGenerate } from '../core/generate/run-generate.js';
+import { runGenerate, runHarness } from '../core/generate/run-generate.js';
 import { runTests } from '../core/run/run-tests.js';
 import { runDiscover } from '../core/docs/discover.js';
 import { runMap } from '../core/project/map.js';
@@ -79,7 +79,7 @@ function printUsage() {
     console.log('  testforge generate --force   Regenerate everything');
     console.log('  testforge generate --no-wait  Stop when the AI hits its usage limit (default: wait for the reset and resume)');
     console.log('  testforge generate --no-verify  Skip running each journey once after generating (default: run and repair)');
-    console.log('  testforge generate --journey <name>  Generate just ONE journey');
+    console.log('  testforge generate --journey <name>  Generate just ONE journey', '  testforge generate --harness         Regenerate only the shared harness (testkit), no test files');
     console.log('  testforge generate --area <area>     Generate a whole area (e.g. api)');
     console.log('  testforge discover          Draft journey docs (asks: map or reference)');
     console.log('  testforge discover --journey <name>  Draft just ONE journey doc');
@@ -144,6 +144,13 @@ async function main() {
         });
         process.exitCode = code;
     }
+    else if (command === 'generate' && process.argv.includes('--harness')) {
+        // Regenerate only the shared harness (testkit), leaving every test file
+        // as it is — e.g. after a TestForge upgrade changes what a harness does.
+        console.log('Regenerating the shared test harness...\n');
+        const written = await runHarness(flagValue('--area'));
+        console.log(written.length ? `Written:\n  ${written.join('\n  ')}` : 'No harness written.');
+    }
     else if (command === 'generate') {
         const useAI = !useBasic;
         console.log(useAI

package/dist/core/docs/review.js

@@ -41,6 +41,9 @@ export function buildReviewPrompt(docPath, srcDir, reference) {
         `- Code branches: read the code this journey runs, client and server.`,
         `  Is every validation, error response and conditional branch an`,
         `  [observed] criterion or a Question? Add the missing ones.`,
+        `- [observed]: open the exact code each [observed] criterion rests on and`,
+        `  confirm it states what that code DOES (follow the real state shape and`,
+        `  call path, not a similarly named field). Fix any that misread it.`,
         `- Tiers: does every [spec] criterion quote a real source sentence?`,
         `  Re-tag any that does not. Does any criterion contradict the code`,
         `  with nothing to test (a rule the screen has no way to break)? Turn`,

package/dist/core/docs/source-of-truth.js

@@ -22,7 +22,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { isInteractive, promptChoice, promptLine } from '../prompt.js';
-import { SOURCE_PATH } from '../paths.js';
+import { SOURCE_PATH, ensureStateDirIgnored } from '../paths.js';
 /** Read the remembered source choice, or null if none/invalid. */
 export function loadSourceChoice() {
     if (!existsSync(SOURCE_PATH))
@@ -58,6 +58,7 @@ export function saveSourceChoice(choice) {
     if (journeys && Object.keys(journeys).length)
         next.journeys = journeys;
     mkdirSync(dirname(SOURCE_PATH), { recursive: true });
+    ensureStateDirIgnored();
     writeFileSync(SOURCE_PATH, JSON.stringify(next, null, 2), 'utf-8');
 }
 /**

package/dist/core/gates/lint.js

@@ -17,7 +17,7 @@
  */
 import { spawnSync } from 'node:child_process';
 import { resolve } from 'node:path';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 /** Walk up from a file to the nearest package that has ESLint installed. */
 function eslintFor(file) {
@@ -77,7 +77,9 @@ export function lintGenerated(files) {
             encoding: 'utf-8',
             timeout: 120_000,
         });
-        const after = readProblems(g.bin, cwd, g.files);
+        let after = readProblems(g.bin, cwd, g.files);
+        if (relaxTypingRules(after.typingRules))
+            after = readProblems(g.bin, cwd, g.files);
         checked += g.files.length;
         fixed += Math.max(0, before - after.count);
         remaining.push(...after.lines);
@@ -87,6 +89,32 @@ export function lintGenerated(files) {
 function countProblems(bin, cwd, files) {
     return readProblems(bin, cwd, files).count;
 }
+/**
+ * Strictness rules a house config applies to app code that say nothing about
+ * whether a generated TEST is right: `any` in a fixture, `require` in a
+ * CommonJS helper. Left in place they fail `npm run lint` in CI on files no
+ * one hand-edits, so a generated file gets a header turning off exactly the
+ * ones it trips — every other rule stays on.
+ */
+const TYPING_RULES = new Set([
+    '@typescript-eslint/no-explicit-any',
+    '@typescript-eslint/no-require-imports',
+    '@typescript-eslint/no-var-requires',
+    '@typescript-eslint/ban-ts-comment',
+]);
+/** Add the header to each file; true when any file changed. */
+function relaxTypingRules(byFile) {
+    let changed = false;
+    for (const [file, rules] of byFile) {
+        if (!rules.size)
+            continue;
+        const text = readFileSync(file, 'utf-8');
+        const header = `/* eslint-disable ${[...rules].sort().join(', ')} -- generated by testforge */\n`;
+        writeFileSync(file, header + text, 'utf-8');
+        changed = true;
+    }
+    return changed;
+}
 function readProblems(bin, cwd, files) {
     const res = spawnSync(bin, ['-f', 'json', '--no-error-on-unmatched-pattern', ...files], {
         cwd,
@@ -99,14 +127,20 @@ function readProblems(bin, cwd, files) {
         parsed = JSON.parse(res.stdout || '[]');
     }
     catch {
-        return { count: 0, lines: [] }; // linter unavailable or output unusable
+        return { count: 0, lines: [], typingRules: new Map() }; // linter unavailable or output unusable
     }
     const lines = [];
+    const typingRules = new Map();
     let count = 0;
     for (const file of parsed) {
         for (const m of file.messages) {
             if (m.severity !== 2)
                 continue; // warnings do not fail a build
+            if (m.ruleId && TYPING_RULES.has(m.ruleId)) {
+                const set = typingRules.get(file.filePath) ?? new Set();
+                set.add(m.ruleId);
+                typingRules.set(file.filePath, set);
+            }
             count += 1;
             if (lines.length < 20) {
                 const rel = file.filePath.replace(cwd + '/', '');
@@ -114,5 +148,5 @@ function readProblems(bin, cwd, files) {
             }
         }
     }
-    return { count, lines };
+    return { count, lines, typingRules };
 }

package/dist/core/generate/ai-generator.js

@@ -297,6 +297,46 @@ export function buildPrompt(journey, map, testPath, focus, harnessPath, transpor
         `    list, and treat a template placeholder (DUMMY, replace_me, an empty`,
         `    value, a bracketed name) as absent rather than as a credential.`,
         `    Say which actor was missing in the skip reason.`,
+        `(13) A [baseline] CHECK PROVES ROBUSTNESS, NOT A VALUE. "Opens without a`,
+        `    crash" is proved by the page loading with no error and no 5xx — not by`,
+        `    an exact URL, trailing slash, heading text or element the document`,
+        `    does not name. Never add an extra condition the criterion does not`,
+        `    state (e.g. "double-click opens exactly one pop-up" when the document`,
+        `    only says the button opens it), and never assert data in a place the`,
+        `    page does not render it — check where the app shows it first.`,
+        `(14) SCOPE EVERY LOCATOR TO THE JOURNEY'S OWN UI. Global components`,
+        `    (a login pop-up, a header, a cookie bar) share ids and labels with`,
+        `    the page under test — "#password" can match the login modal's field.`,
+        `    Locate inside the journey's form/container, never page-wide by a`,
+        `    bare id or label that another always-mounted component also uses.`,
+        `(15) NOTHING YOU ARE NOT TESTING MAY BLOCK YOU. Apps open their own`,
+        `    pop-ups for a signed-in or new user (referral/promo, cookie consent,`,
+        `    onboarding tips, notification prompts). Use the harness's login /`,
+        `    storage helpers that pre-suppress them; if one still opens, close it`,
+        `    before you continue. A click intercepted by an overlay the test is`,
+        `    not about is your bug, not the product's.`,
+        `(16) "INSIDE" MEANS THE MIDDLE. To click inside a panel, click its centre`,
+        `    or a non-interactive child — never a corner offset like (5,5): with a`,
+        `    border-radius that point is outside the element and lands on the`,
+        `    overlay behind it.`,
+        `(17) LET THE APP SETTLE BEFORE YOU CHANGE THE SESSION. After a login,`,
+        `    sign-out or navigation the app sends its own requests and may`,
+        `    redirect by itself. Wait for the network to go idle before rotating`,
+        `    a session, logging in elsewhere or navigating away, and assert the`,
+        `    URL the APP chooses — never force a navigation that can cut off the`,
+        `    app's own redirect.`,
+        `(18) ONE SOURCE FOR SEEDED IDS. Read every seeded id and handle from the`,
+        `    harness (TEST_IDS / the values setup() publishes). If a test needs a`,
+        `    private account, override EVERY id that belongs to it, never a`,
+        `    subset — a leftover shared id makes you compare against another`,
+        `    customer's row.`,
+        `(19) VERIFICATION CODES THE TEST CANNOT READ (SMS/email OTP, magic`,
+        `    links, OAuth). Drive the real UI up to the code step, then use the`,
+        `    harness's bypassVerification() so the final verify/register request`,
+        `    is answered with a REAL account and a REAL token; everything after it`,
+        `    (logged-in state, redirect, payment) is then tested for real. Put`,
+        `    "(verification bypassed)" in that test's title. Wrong-code and`,
+        `    expired-code tests do NOT bypass: the real server must refuse them.`,
         `When rules conflict, prefer reporting LESS: a pending test costs a line`,
         `in the report; a false failure costs the team a release.`,
         ``,

package/dist/core/generate/harness.js

@@ -105,6 +105,8 @@ export const HARNESS_CONTRACT = [
     `                                       process.env work with NO hand-`,
     `                                       pasted tokens.`,
     `  - token(role?): string          the current access token accessor`,
+    `  - REQUIRED_PACKAGES, resetRateLimits(), bypassVerification(): see`,
+    `    RUN ENVIRONMENT below.`,
     `Plus, for Playwright suites, ALSO export:`,
     `  - apiContext(request): a helper that returns an authed API request`,
     `    context (Bearer = the minted token — NEVER hardcode a secret).`,
@@ -180,6 +182,52 @@ export const HARNESS_CONTRACT = [
     `    distinct token (env). If only one identity is available, make those`,
     `    cases pending — never assert a scope the token cannot actually prove.`,
     ``,
+    `RUN ENVIRONMENT — the suite must run on a fresh machine given only the`,
+    `env file. Every rule below exists because breaking it stopped a real run.`,
+    `  - PACKAGES: use only Node built-ins, the test runner, and libraries the`,
+    `    project already lists in package.json. If the data layer needs a`,
+    `    driver or helper the project lacks (mysql2, pg, mongodb, bcryptjs),`,
+    `    require it lazily and, when missing, throw "testkit: missing package`,
+    `    <name> — run: npm i -D <name>". Also export REQUIRED_PACKAGES: an`,
+    `    array literal naming every such package, so the runner can check them`,
+    `    before the suite starts.`,
+    `  - NO OTHER RUNTIMES: never shell out to php, python, artisan, docker or`,
+    `    any CLI — the test machine need not have them. Hash a password in`,
+    `    Node: bcrypt via bcryptjs, and for PHP/Laravel rewrite the "$2a$" /`,
+    `    "$2b$" prefix to "$2y$" (the same algorithm).`,
+    `  - THE SEED OWNS ITS CREDENTIALS: an account the seed CREATES gets a`,
+    `    fixed test password constant that satisfies the app's password rule`,
+    `    (e.g. 'QaTest#2026pass'), overridable by TEST_<ROLE>_PASSWORD. Never`,
+    `    require env for a credential the seed itself sets.`,
+    `  - SEED EVERYTHING A TEST NEEDS: special accounts (unverified, banned,`,
+    `    soft-deleted, other roles, expired temporary passwords), codes`,
+    `    (valid / expired / restricted coupons), shareable links, a second`,
+    `    customer's records — all seeded and exposed through TEST_IDS and the`,
+    `    env setup() publishes. In auto mode no test waits on hand-made data.`,
+    `  - LOG IN ONCE: mint each role's token once per run (globalSetup) and`,
+    `    reuse the cached token; login(page) injects it. Backends rate-limit`,
+    `    by IP (e.g. 60 requests/minute) and a suite that calls the login API`,
+    `    per test is throttled (HTTP 429). If the limiter's state lives in a`,
+    `    store the testkit reaches in local mode (e.g. the backend's Redis`,
+    `    cache), export resetRateLimits(): clear ONLY the limiter keys, gated`,
+    `    exactly like reset(), and call it from setup().`,
+    `  - SUPPRESS APP POP-UPS: read the client for pop-ups that open by`,
+    `    themselves for the seeded roles (referral/promo, cookie consent,`,
+    `    onboarding, notification prompts) and have login(page) and any`,
+    `    seeded browser storage pre-set the flags that suppress them, like a`,
+    `    "prompt already shown" flag. Give the seeded user a first name so`,
+    `    greetings render.`,
+    `  - VERIFICATION BYPASS (Playwright): when the app verifies by a code the`,
+    `    test cannot read (SMS/email OTP, magic link, OAuth), export`,
+    `    bypassVerification(page, { url, account }): route the request at`,
+    `    \`url\` (the final verify/register call); in the handler, seed the`,
+    `    account (verified, with the given email/phone/name and the seed`,
+    `    password), log it in through the REAL login API, and fulfil the`,
+    `    intercepted request with the app's REAL success response shape (read`,
+    `    the controller and the client that consumes it) carrying that real`,
+    `    token and user. Only the code check is skipped — everything after it`,
+    `    runs against the real backend.`,
+    ``,
     `CONNECTION LIFECYCLE — setup() must be safe to call repeatedly across`,
     `suites, or one suite's teardown breaks the next (MongoNotConnectedError).`,
     `  - connect() and setup() MUST check the live connection state before`,
@@ -303,7 +351,7 @@ export function generateHarnessAsync(harnessPath, framework) {
  * dir, treats *.test.js as specs, and runs the testkit's setup() once via
  * globalSetup (mints/populates tokens before any worker starts).
  */
-export function playwrightConfig(testDirRelToPackage, globalSetupRelToPackage, category = 'web') {
+export function playwrightConfig(testDirRelToPackage, globalSetupRelToPackage, category = 'web', outputDirRelToPackage = 'test-results') {
     return [
         `// @generated by testforge`,
         `// Minimal Playwright config so testforge's generated specs run.`,
@@ -315,6 +363,9 @@ export function playwrightConfig(testDirRelToPackage, globalSetupRelToPackage, c
         `  testMatch: /.*\\.(test|spec)\\.[jt]s$/,`,
         `  globalSetup: require.resolve('${globalSetupRelToPackage}'),`,
         `  timeout: 60000,`,
+        `  // Run output (failure reports, traces) stays with testforge's local state,`,
+        `  // which is not committed.`,
+        `  outputDir: '${outputDirRelToPackage}',`,
         `  // Serial, like the Jest config: these suites share ONE test database`,
         `  // and seed/reset it, so parallel workers race on the same rows and the`,
         `  // same run gives different answers twice. It also keeps --headed to a`,

package/dist/core/generate/run-generate.js

@@ -17,8 +17,8 @@
  * generated-tests/ when not configured.
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync, } from 'node:fs';
-import { join, dirname, basename, extname } from 'node:path';
-import { CACHE_PATH } from '../paths.js';
+import { join, dirname, basename, extname, relative, resolve, sep } from 'node:path';
+import { CACHE_PATH, RESULTS_DIR, ensureStateDirIgnored } from '../paths.js';
 import { lintGenerated } from '../gates/lint.js';
 import { parseJourney, notAJourneyDoc } from '../docs/parser.js';
 import { writeCoverageManifest } from '../gates/coverage.js';
@@ -27,7 +27,8 @@ import { aiFailureNote, aiUnavailableReason, confirmAiAlive, lastAiFailureWasPro
 import { generateTestCases } from './generator.js';
 import { writeDeferredStub } from './playwright-writer.js';
 import { generateWithAI, generateWithAIAsync, repairWithAIAsync, } from './ai-generator.js';
-import { verifyFiles } from './verify.js';
+import { verifyFiles, browserPreflight, missingPackages } from './verify.js';
+import { packageRoot } from '../run/run-tests.js';
 import { groundJourney } from '../docs/grounding.js';
 import { generateSeed } from './seed-generator.js';
 import { isSyntaxValid, checkTestGates } from '../gates/validate.js';
@@ -183,6 +184,20 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
     const ext = config.testExtension ?? '.test.ts';
     const seedDir = config.seedOutput ?? 'generated-tests/seed';
     const seedExt = ext.endsWith('.js') ? '.seed.js' : '.seed.ts';
+    // A browser that cannot start fails every verify, and each failure would be
+    // sent for repair. Find out once, before any AI call is spent.
+    if (useAI && verifyOn) {
+        for (const area of Object.keys(config.testOutput ?? {})) {
+            if (resolveFramework(config, area, area) !== 'playwright')
+                continue;
+            const problem = browserPreflight(packageRoot(testDirForType(config, area)));
+            if (problem) {
+                throw new Error(`Cannot verify "${area}" tests: ${problem}.\n` +
+                    'Fix that and re-run, or pass --no-verify to write tests without running them.');
+            }
+        }
+    }
+    ensureStateDirIgnored();
     const cache = loadCache(CACHE_PATH);
     const results = [];
     resetAiSession();
@@ -559,6 +574,10 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
         const lintTargets = [
             ...testFiles.map((t) => (typeof t === 'string' ? t : t.path)),
             ...(seedPath ? [seedPath] : []),
+            // The shared harness and the runner config are generated too, and CI
+            // lints them like any other file.
+            // Only files testforge generated: a project's own config is never edited.
+            ...[harnessPath, join(dirname(testDir), 'playwright.config.js')].filter((f) => !!f && existsSync(f) && readFileSync(f, 'utf-8').includes(GEN_MARKER)),
         ];
         const lint = lintGenerated(lintTargets);
         if (lint.fixed > 0) {
@@ -575,9 +594,23 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
         // is reported and left UNCACHED, so it is retried rather than trusted.
         let verified;
         const targets = testFiles.filter((t) => t.status === 'ai').map((t) => t.path);
-        if (useAI && verifyOn && targets.length) {
+        const missing = harnessPath ? missingPackages(harnessPath, packageRoot(testDir)) : [];
+        if (useAI && verifyOn && targets.length && missing.length) {
+            // The suite cannot even start; running it would only feed repair a
+            // failure no test edit can fix.
+            verified = false;
+            warnings.push(`verify: not run — install the packages the harness needs: npm i -D ${missing.join(' ')}`);
+        }
+        else if (useAI && verifyOn && targets.length) {
             for (let attempt = 0; attempt <= verifyAttempts; attempt += 1) {
                 const outcome = verifyFiles(config, journey.area, targets);
+                if (outcome.infra) {
+                    // Not the tests' fault, so no repair; and not verified, so the
+                    // journey stays uncached and the next run checks it again.
+                    verified = false;
+                    warnings.push(`verify: not run — ${outcome.reason}`);
+                    break;
+                }
                 if (!outcome.ran) {
                     // Say WHY once. The reason is a property of the project (no env
                     // file, no runner), not of this journey, so repeating it per
@@ -689,25 +722,39 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
  * Config files are written only if absent, so a project's hand-tuned config is
  * never clobbered. `harnessDir` is the area's helpers dir (where setup lives).
  */
-function writeHarnessConfigs(framework, areaDir, harnessDir, area) {
-    const pkgRoot = dirname(areaDir);
-    const rel = areaDir.slice(pkgRoot.length + 1) || '.';
+export function writeHarnessConfigs(framework, areaDir, harnessDir, area) {
+    const posix = (from, to) => relative(from, resolve(to)).split(sep).join('/') || '.';
     if (framework === 'playwright') {
         const gsPath = join(harnessDir, 'global-setup.js');
         writeFileSync(gsPath, globalSetupContent(), 'utf-8');
-        const cfg = join(pkgRoot, 'playwright.config.js');
+        const home = configHome(areaDir, 'playwright.config.js');
+        const cfg = join(home, 'playwright.config.js');
         if (!existsSync(cfg)) {
-            const gsRel = gsPath.slice(pkgRoot.length + 1);
-            writeFileSync(cfg, playwrightConfig(`./${rel}`, `./${gsRel}`, area), 'utf-8');
+            writeFileSync(cfg, playwrightConfig(`./${posix(home, areaDir)}`, `./${posix(home, gsPath)}`, area, posix(home, RESULTS_DIR)), 'utf-8');
         }
     }
     else if (framework === 'jest') {
         const setupPath = join(harnessDir, 'jest.setup.js');
         writeFileSync(setupPath, jestSetupContent(), 'utf-8');
-        const cfg = join(pkgRoot, 'jest.config.js');
+        const home = configHome(areaDir, 'jest.config.js');
+        const cfg = join(home, 'jest.config.js');
         if (!existsSync(cfg)) {
-            const setupRel = setupPath.slice(pkgRoot.length + 1);
-            writeFileSync(cfg, jestConfig(rel, setupRel, area), 'utf-8');
+            writeFileSync(cfg, jestConfig(posix(home, areaDir), posix(home, setupPath), area), 'utf-8');
         }
     }
 }
+/**
+ * Where a runner config goes: the package root, where `npx playwright test`
+ * and `npx jest` look for it by themselves — so CI, a teammate or a custom
+ * testCommand finds it with no --config flag. Tests can sit any depth below
+ * (tests/e2e, not just tests/). Only when the project already has its own
+ * config there do we fall back to the test folder's parent, never touching
+ * the project's file.
+ */
+function configHome(areaDir, name) {
+    const root = packageRoot(areaDir);
+    const existing = join(root, name);
+    if (!existsSync(existing) || readFileSync(existing, 'utf-8').includes(GEN_MARKER))
+        return root;
+    return resolve(dirname(areaDir));
+}

package/dist/core/generate/verify.js

@@ -13,8 +13,9 @@
  * anything we could infer.
  */
 import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { relative } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, relative } from 'node:path';
 import { loadEnvFile, testDirForType, resolveFramework, } from '../project/config.js';
 import { runnerCommand, packageRoot } from '../run/run-tests.js';
 /** How much runner output to carry into a repair prompt. */
@@ -44,6 +45,39 @@ function countsFrom(output) {
         return null;
     return { passed: passed ?? 0, skipped: skipped ?? 0 };
 }
+/**
+ * Failures no test edit can fix. Sending one to the repair prompt burns AI
+ * calls rewriting correct tests against an error they cannot cause (one
+ * night: 877 failures, every one a missing browser).
+ */
+const INFRA_FAILURES = [
+    [
+        /Executable doesn't exist at|browserType\.launch:|Host system is missing dependencies|does not support (chromium|firefox|webkit) on/i,
+        'the test browser cannot start — install the one this Playwright version needs (`npx playwright install chromium`), or pin a Playwright version your OS supports',
+    ],
+    [
+        /missing package|package is not installed|Cannot find module '(?![./])/i,
+        'a package the tests or their harness need is not installed in the project — install it as a dev dependency (the error names it)',
+    ],
+    [
+        /net::ERR_CONNECTION_REFUSED|ECONNREFUSED/i,
+        'the app (or a service it needs) is not reachable — start it and check BASE_URL / the DB settings in the env file',
+    ],
+];
+export function infraFailure(output) {
+    return INFRA_FAILURES.find(([re]) => re.test(output))?.[1] ?? null;
+}
+/**
+ * Can the test browser start? Asked once before generation spends anything,
+ * so a missing browser stops the run instead of failing every verify.
+ */
+export function browserPreflight(root) {
+    const res = spawnSync(process.execPath, ['-e', "require('@playwright/test').chromium.launch().then((b) => b.close())"], { cwd: root, encoding: 'utf-8', timeout: 120_000 });
+    if (res.status === 0)
+        return null;
+    const output = `${res.stdout ?? ''}\n${res.stderr ?? ''}`;
+    return infraFailure(output) ?? (output.trim().split('\n').find((l) => l.trim()) || 'the test browser could not start');
+}
 /**
  * Run exactly the given generated files. Never throws: a verify step that
  * breaks generation would be worse than no verify step at all.
@@ -90,6 +124,9 @@ export function verifyFiles(config, area, files) {
     if (/command not found|Cannot find module '@playwright|is not recognized/i.test(output)) {
         return { ran: false, ok: false, output, reason: 'test runner is not installed' };
     }
+    const infra = infraFailure(output);
+    if (infra)
+        return { ran: false, infra: true, ok: false, output, reason: infra };
     if (res.status !== 0)
         return { ran: true, ok: false, output };
     // A suite where every test skipped ALSO exits 0. Treating that as verified
@@ -106,3 +143,30 @@ export function verifyFiles(config, area, files) {
     }
     return { ran: true, ok: true, output };
 }
+/**
+ * Packages the generated harness declares it needs (REQUIRED_PACKAGES) that
+ * the project cannot resolve. Read from the source, never executed.
+ */
+export function missingPackages(harnessFile, root) {
+    let src = '';
+    try {
+        src = readFileSync(harnessFile, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const list = src.match(/REQUIRED_PACKAGES\s*=\s*\[([^\]]*)\]/);
+    if (!list)
+        return [];
+    const names = [...list[1].matchAll(/['"]([^'"]+)['"]/g)].map((m) => m[1]);
+    const req = createRequire(join(root, 'package.json'));
+    return names.filter((n) => {
+        try {
+            req.resolve(n);
+            return false;
+        }
+        catch {
+            return true;
+        }
+    });
+}

package/dist/core/paths.js

@@ -1,3 +1,4 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 /**
  * Single source of truth for TestForge's per-project state directory and the
@@ -17,3 +18,17 @@ export const SOURCE_PATH = join(STATE_DIR, 'source.json');
 export const COVERAGE_PATH = join(STATE_DIR, 'coverage.json');
 /** Per-journey generation plans, organised per area: <PLANS_DIR>/<area>/<id>.json */
 export const PLANS_DIR = join(STATE_DIR, 'test-plans');
+/** Where Playwright writes its per-run output (failure reports, traces). */
+export const RESULTS_DIR = join(STATE_DIR, 'playwright-results');
+/**
+ * Keep the state dir out of git without touching the project's own
+ * .gitignore: caches, plans and run output are local and regenerated, only
+ * the source-of-truth choice is worth sharing with the team.
+ */
+export function ensureStateDirIgnored() {
+    const file = join(STATE_DIR, '.gitignore');
+    if (existsSync(file))
+        return;
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(file, '# testforge local state: regenerated as needed, so not committed.\n*\n!.gitignore\n!source.json\n', 'utf-8');
+}

package/dist/core/project/env-template.js

@@ -15,6 +15,7 @@ import { readFileSync, writeFileSync, existsSync, readdirSync, } from 'node:fs';
 import { join } from 'node:path';
 import { findMarkdownFiles } from '../find-files.js';
 import { STATE_DIR, LEGACY_STATE_DIR } from '../paths.js';
+import { loadConfig } from './config.js';
 /** Pull env var names from a chunk of text. */
 function extractEnvVars(text) {
     const vars = new Set();
@@ -25,6 +26,10 @@ function extractEnvVars(text) {
     for (const m of text.matchAll(/process\.env\[\s*['"]([A-Z0-9_]+)['"]\s*\]/gi)) {
         vars.add(m[1]);
     }
+    // A generated suite often reads env through a small helper: env('TEST_X', default).
+    for (const m of text.matchAll(/\benv\(\s*['"]([A-Z][A-Z0-9_]+)['"]/g)) {
+        vars.add(m[1]);
+    }
     // backtick-wrapped ALL_CAPS names in "env var" lines
     for (const line of text.split('\n')) {
         if (/env var|secret|credential/i.test(line)) {
@@ -189,6 +194,15 @@ export function runEnvTemplate(docsDir, outPath, srcDir = '.', testDirs = []) {
         return;
     }
     const files = findMarkdownFiles(docsDir);
+    // Every caller gets the generated suite scanned, not only the one that
+    // remembered to pass its dirs: the tests' own TEST_* variables are exactly
+    // what a developer cannot guess.
+    const config = loadConfig();
+    if (!testDirs.length) {
+        testDirs = [...Object.values(config.testOutput ?? {}), config.seedOutput ?? '']
+            .filter((d) => !!d && existsSync(d));
+    }
+    const envFile = config.envFile ?? '.env.testing';
     // area -> var -> set of journeys
     const byArea = new Map();
     for (const file of files) {
@@ -254,9 +268,9 @@ export function runEnvTemplate(docsDir, outPath, srcDir = '.', testDirs = []) {
         '# .env.testing.example',
         '#',
         '# Test credentials the generated tests/seeds need, grouped by area.',
-        '# Copy this to .env.testing and fill in real values.',
+        `# Copy this to ${envFile} and fill in real values.`,
         '# Only variables for the features you actually run are required.',
-        '# Keep .env.testing OUT of version control.',
+        `# Keep ${envFile} OUT of version control.`,
         '',
         `# ${'='.repeat(40)}`,
         '# TESTFORGE DASHBOARD (auto-publish each run)',
@@ -296,5 +310,5 @@ export function runEnvTemplate(docsDir, outPath, srcDir = '.', testDirs = []) {
     }
     writeFileSync(outPath, lines.join('\n'), 'utf-8');
     console.log(`Env template written to ${outPath}`);
-    console.log('Copy it to .env.testing and fill in real values.');
+    console.log(`Copy it to ${envFile} and fill in real values.`);
 }

package/dist/core/run/run-tests.js

@@ -37,8 +37,13 @@ export function packageRoot(dir) {
 export function runnerCommand(config, area, framework, root, rel, journey, targets) {
     const explicit = config.testCommand?.[area];
     const paths = (targets ?? []).map((t) => relative(root, t) || t);
-    if (explicit)
-        return paths.length ? `${explicit} ${paths.join(' ')}` : explicit;
+    if (explicit) {
+        if (paths.length)
+            return `${explicit} ${paths.join(' ')}`;
+        // A custom command still honours --journey: narrow it to that journey's
+        // tests, or `run --journey x` silently runs the whole suite.
+        return journey ? `${explicit} ${framework === 'playwright' ? `${rel}/${journey}` : `--testPathPattern "${journey}"`}` : explicit;
+    }
     if (framework === 'playwright') {
         const target = paths.length
             ? paths.join(' ')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@activate-core/test-forge",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "AI-powered QA automation. Scans a project, drafts journey docs, and generates seeded Jest/Playwright tests. Works in any project, with any AI CLI.",
   "type": "module",
   "bin": {