@activate-core/test-forge 1.0.2 → 1.0.4

package/dist/cli/index.js

@@ -19,7 +19,7 @@
  *                                      (an auth-gated page can move unseen).
  */
 import { VERSION } from '../core/index.js';
-import { runGenerate, runHarness } from '../core/generate/run-generate.js';
+import { runGenerate } 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', '  testforge generate --harness         Regenerate only the shared harness (testkit), no test files');
+    console.log('  testforge generate --journey <name>  Generate just ONE journey');
     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,13 +144,6 @@ 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/generate/ai-generator.js

@@ -310,7 +310,7 @@ export function buildPrompt(journey, map, testPath, focus, harnessPath, transpor
         `    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,`,
+        `    pop-ups for a signed-in or new user (promotions, 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`,
@@ -337,6 +337,10 @@ export function buildPrompt(journey, map, testPath, focus, harnessPath, transpor
         `    (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.`,
+        `(20) CHECK STATE THROUGH WHAT THE HARNESS OFFERS. If the harness has`,
+        `    no database connection (the data lives in another repository), prove`,
+        `    persisted state through the app's own API — the list or detail`,
+        `    endpoint the client reads — never by importing a database client.`,
         `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

@@ -13,6 +13,7 @@
  */
 import { execFileSync, spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { loadConfig, splitCommand, withReadOnlyTools } from '../project/config.js';
 import { cleanOutput } from './ai-generator.js';
 const MAP_PATH = 'testforge.md';
@@ -183,50 +184,61 @@ export const HARNESS_CONTRACT = [
     `    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.`,
+    `env file, in WHATEVER stack this project uses. Decide everything below`,
+    `from what you read in THIS project; nothing here names a stack.`,
+    `  - PACKAGES: use Node built-ins, the test runner, and what the project`,
+    `    already has installed. If reaching the project's data layer needs a`,
+    `    client the project lacks (a driver for its database), require it`,
+    `    lazily, throw "testkit: missing package <name> — run: npm i -D <name>"`,
+    `    when absent, and list it in REQUIRED_PACKAGES (an array literal) so`,
+    `    the runner can check before the suite starts. Never add a package`,
+    `    for anything else.`,
+    `  - DATA LAYER IN ANOTHER REPOSITORY: when this repository does not own`,
+    `    its database (the project map or a related repo shows the data layer`,
+    `    belongs to another codebase, e.g. a frontend talking to a separate`,
+    `    API), do NOT connect to that database: no data-layer client, nothing`,
+    `    in REQUIRED_PACKAGES. seed() prepares data and tests read state`,
+    `    through the app's own API — log in with the env credentials and call`,
+    `    the endpoints the client itself calls. A state only a direct database`,
+    `    write could create is not seeded: the tests needing it skip with`,
+    `    that reason (the repository that owns the data tests it).`,
+    `  - NO OTHER RUNTIMES: never shell out to another language runtime, a`,
+    `    framework CLI or a container tool — the test machine need not have`,
+    `    them.`,
+    `  - CREDENTIALS COME FROM THE ENV FILE: every role the suite logs in as`,
+    `    (customer, staff, admin, second customer, …) is an account whose`,
+    `    login identifier and password are read from the env file`,
+    `    (TEST_<ROLE>_EMAIL / TEST_<ROLE>_PASSWORD, or the identifier the app`,
+    `    logs in with). The testkit NEVER hashes or invents a password. The`,
+    `    seed may fill in the profile data such an account needs (addresses,`,
+    `    vehicles, settings) but never its credential.`,
+    `  - EXTRA ACCOUNT STATES (unverified, banned, deleted, another role, an`,
+    `    expired credential): create them the way the app itself would —`,
+    `    through its API where one exists, otherwise through the data layer`,
+    `    by COPYING the stored credential of an env-provided account onto the`,
+    `    new record, then setting the state. Never compute a credential.`,
+    `  - SEED THE DATA TESTS NEED: codes, links, other customers' records —`,
+    `    seeded and exposed through TEST_IDS and the env setup() publishes,`,
+    `    so in auto mode no test waits on hand-made data. DB assertions (rows`,
+    `    created, state persisted) go through the same data-layer client.`,
     `  - 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.`,
+    `    reuse it; login(page) injects it. If the backend rate-limits and`,
+    `    its limiter state lives in a store the testkit can reach in local`,
+    `    mode, export resetRateLimits() that clears ONLY the limiter entries,`,
+    `    gated exactly like reset(), and call it from setup().`,
+    `  - SUPPRESS THE APP'S OWN POP-UPS: find, in the client, any dialog that`,
+    `    opens by itself for a seeded role (promotions, consent, onboarding,`,
+    `    permission prompts) and have login(page) and seeded browser storage`,
+    `    pre-set the flags that suppress it.`,
     `  - 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.`,
+    `    test cannot read (a code sent by message or email, a magic link, a`,
+    `    third-party sign-in), export bypassVerification(page, { url, role }):`,
+    `    route the request at \`url\` (the final verify/register call) and`,
+    `    fulfil it with the app's REAL success response shape (read the`,
+    `    server handler and the client that consumes it) carrying a REAL token`,
+    `    for an env-provided account of that role, obtained through the real`,
+    `    login. 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).`,
@@ -240,6 +252,21 @@ export const HARNESS_CONTRACT = [
     `    (Playwright globalTeardown / Jest globalTeardown) that runs ONCE after`,
     `    the whole run — never per-file.`,
 ].join('\n');
+/**
+ * Stamp written into every generated testkit: the contract it was built
+ * against. When TestForge's contract changes (a fix to how harnesses log in,
+ * seed or bypass verification), an existing testkit no longer matches and
+ * `generate` rebuilds it by itself — nobody has to remember a command.
+ */
+export const HARNESS_STAMP = `testforge-harness-contract: ${createHash('sha1').update(HARNESS_CONTRACT).digest('hex').slice(0, 12)}`;
+/** Was this testkit built against the current contract? */
+export function harnessIsCurrent(source) {
+    return source.includes(HARNESS_STAMP);
+}
+/** Prefix a freshly generated testkit with the stamp. */
+export function stampHarness(source) {
+    return `// ${HARNESS_STAMP}\n${source}`;
+}
 /** Where an area's shared testkit lives, and how tests import it. */
 export function harnessInfo(areaDir, framework, ext) {
     // Jest tests are flat inside <areaDir> (e.g. .../test/service), so the

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

@@ -33,7 +33,7 @@ import { groundJourney } from '../docs/grounding.js';
 import { generateSeed } from './seed-generator.js';
 import { isSyntaxValid, checkTestGates } from '../gates/validate.js';
 import { installedModules, transportHint, projectSelectors } from '../project/detect.js';
-import { harnessInfo, generateHarnessAsync, generateHarness, playwrightConfig, globalSetupContent, fixturesDoc, jestConfig, jestSetupContent, } from './harness.js';
+import { harnessInfo, generateHarnessAsync, harnessIsCurrent, stampHarness, generateHarness, playwrightConfig, globalSetupContent, fixturesDoc, jestConfig, jestSetupContent, } from './harness.js';
 import { hashContent, loadCache, saveCache } from '../docs/cache.js';
 import { findMarkdownFiles } from '../find-files.js';
 import { loadConfig, testDirForType, resolveFramework } from '../project/config.js';
@@ -160,7 +160,7 @@ export async function runHarness(only) {
             continue;
         }
         mkdirSync(dirname(info.path), { recursive: true });
-        writeFileSync(info.path, kit, 'utf-8');
+        writeFileSync(info.path, stampHarness(kit), 'utf-8');
         writeFileSync(join(info.dir, 'FIXTURES.md'), fixturesDoc(), 'utf-8');
         writeHarnessConfigs(framework, areaDir, info.dir, area);
         written.push(info.path);
@@ -246,8 +246,14 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
         // extra AI call (and no risk of that call eating the token limit).
         // Pass --force to rebuild a stale testkit (e.g. after upgrading).
         if (!force && existsSync(info.path)) {
-            harnessByArea.set(area, info.path);
-            return info.path;
+            if (harnessIsCurrent(readFileSync(info.path, 'utf-8'))) {
+                harnessByArea.set(area, info.path);
+                return info.path;
+            }
+            // Built by an older TestForge whose harness rules have since changed:
+            // rebuild it once here, so the fixes reach this project with no extra
+            // command. Test files are untouched.
+            console.log(`  the ${area} test harness predates this TestForge version — rebuilding it`);
         }
         const kit = await generateValidatedAsync(() => generateHarnessAsync(info.path, framework), ext.endsWith('.js') ? '.js' : '.ts');
         if (kit === null) {
@@ -255,7 +261,7 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
             return undefined;
         }
         mkdirSync(dirname(info.path), { recursive: true });
-        writeFileSync(info.path, kit, 'utf-8');
+        writeFileSync(info.path, stampHarness(kit), 'utf-8');
         writeFileSync(join(info.dir, 'FIXTURES.md'), fixturesDoc(), 'utf-8');
         // Config + globalSetup (playwright) / config + setup (jest) so the specs run
         // AND get their tokens minted once, plus the runner config scaffolding.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@activate-core/test-forge",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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": {