@activate-core/test-forge 0.6.1 → 0.8.0

package/dist/cli/index.js

@@ -15,13 +15,15 @@
  *   testforge generate --force         Regenerate everything, ignoring the cache.
  */
 import { VERSION } from '../core/index.js';
-import { runGenerate } from '../core/run-generate.js';
+import { runGenerate, runHarness } from '../core/run-generate.js';
 import { runDiscover } from '../core/discover.js';
 import { runMap } from '../core/map.js';
 import { runInit } from '../core/init.js';
 import { runSetup } from '../core/setup.js';
 import { runUpdate } from '../core/update.js';
 import { runEnvTemplate } from '../core/env-template.js';
+import { loadConfig } from '../core/config.js';
+import { dirname } from 'node:path';
 const command = process.argv[2];
 const useBasic = process.argv.includes('--basic');
 const force = process.argv.includes('--force');
@@ -39,6 +41,22 @@ function flagValue(name) {
 function sourceOptions() {
     return { reference: flagValue('--reference'), source: flagValue('--source') };
 }
+/**
+ * The output dirs to scan for env vars the GENERATED suite reads (test
+ * output dirs + their sibling helpers/ + the seed dir). Shared by the
+ * `generate` and `env` commands so the example always reflects the suite.
+ */
+function generatedScanDirs() {
+    const cfg = loadConfig();
+    const dirs = new Set();
+    for (const out of Object.values(cfg.testOutput ?? {})) {
+        dirs.add(out);
+        dirs.add(dirname(out));
+    }
+    if (cfg.seedOutput)
+        dirs.add(cfg.seedOutput);
+    return [...dirs];
+}
 function printUsage() {
     console.log(`testforge v${VERSION}`);
     console.log('');
@@ -57,6 +75,7 @@ function printUsage() {
     console.log('  testforge init              Inspect project and write config');
     console.log('  testforge update            Re-check and update only what changed');
     console.log('  testforge env               Write .env.testing.example from docs');
+    console.log('  testforge harness [--area <a>]  (Re)generate the shared testkit only');
 }
 async function main() {
     if (command === 'update') {
@@ -87,7 +106,20 @@ async function main() {
         console.log('then run `testforge generate`.');
     }
     else if (command === 'env') {
-        runEnvTemplate('docs', '.env.testing.example');
+        runEnvTemplate('docs', '.env.testing.example', '.', generatedScanDirs());
+    }
+    else if (command === 'harness') {
+        console.log('(Re)generating the shared test harness (testkit)...\n');
+        const written = await runHarness(flagValue('--area'));
+        if (written.length === 0) {
+            console.log('No harness generated. Check the --area or run `generate` first.');
+        }
+        else {
+            for (const p of written)
+                console.log(`  testkit: ${p}`);
+            console.log('\nDone. Existing tests import this testkit unchanged; its setup()' +
+                ' seeds + mints/populates the auth tokens they read.');
+        }
     }
     else if (command === 'generate') {
         const useAI = !useBasic;
@@ -130,6 +162,11 @@ async function main() {
             if (seedFailures > 0) {
                 console.log(`Warning: ${seedFailures} seed file(s) could not be generated — see notes above.`);
             }
+            // Auto-refresh the env template so running `generate` on its own (not
+            // just `setup`) tells the developer exactly which credentials the
+            // generated suite needs — including vars the tests themselves read.
+            console.log('');
+            runEnvTemplate('docs', '.env.testing.example', '.', generatedScanDirs());
         }
     }
     else {

package/dist/core/env-template.js

@@ -55,7 +55,8 @@ const SOURCE_EXT = /\.(c|m)?[jt]sx?$/i;
  * skipping vendored/build/test output, with a file cap so a huge repo
  * can't stall the run.
  */
-function scanSourceEnvVars(srcDir, maxFiles = 4000) {
+function scanSourceEnvVars(srcDir, opts = {}) {
+    const { includeTests = false, maxFiles = 4000 } = opts;
     const vars = new Set();
     let seen = 0;
     const walk = (dir) => {
@@ -78,8 +79,10 @@ function scanSourceEnvVars(srcDir, maxFiles = 4000) {
                 walk(full);
             }
             else if (SOURCE_EXT.test(entry.name)) {
-                // Skip test files — we want app source, not existing tests.
-                if (/\.(test|spec)\./i.test(entry.name))
+                // App-source scan skips test files; the generated-suite scan
+                // (includeTests) WANTS them — that is where the tests' own env
+                // vars (tokens, ids, base URLs) live.
+                if (!includeTests && /\.(test|spec)\./i.test(entry.name))
                     continue;
                 seen++;
                 try {
@@ -108,7 +111,7 @@ function areaAndJourney(file) {
     // Fallback: flat file with no area folder.
     return { area: 'general', journey: noExt };
 }
-export function runEnvTemplate(docsDir, outPath, srcDir = '.') {
+export function runEnvTemplate(docsDir, outPath, srcDir = '.', testDirs = []) {
     if (!existsSync(docsDir)) {
         console.log(`No docs found at "${docsDir}". Run \`testforge setup\` first.`);
         return;
@@ -153,7 +156,21 @@ export function runEnvTemplate(docsDir, outPath, srcDir = '.') {
     }
     const sourceVars = scanSourceEnvVars(srcDir);
     const bootVars = [...sourceVars].filter((v) => !knownFromDocs.has(v)).sort();
-    if (byArea.size === 0 && bootVars.length === 0) {
+    // Vars the GENERATED suite (tests + seeds + testkit) actually reads —
+    // scanned from the output dirs, INCLUDING test files. This is what
+    // captures tokens/ids/base-URLs the generated code needs but that no
+    // doc/source mentioned.
+    const suiteScan = new Set();
+    for (const d of testDirs) {
+        for (const v of scanSourceEnvVars(d, { includeTests: true })) {
+            suiteScan.add(v);
+        }
+    }
+    const alreadyShown = new Set([...knownFromDocs, ...bootVars]);
+    const suiteVars = [...suiteScan]
+        .filter((v) => !alreadyShown.has(v))
+        .sort();
+    if (byArea.size === 0 && bootVars.length === 0 && suiteVars.length === 0) {
         console.log('No environment variables found in the docs or source.');
         return;
     }
@@ -167,6 +184,15 @@ export function runEnvTemplate(docsDir, outPath, srcDir = '.') {
         '# Keep .env.testing OUT of version control.',
         '',
     ];
+    if (suiteVars.length > 0) {
+        lines.push(`# ${'='.repeat(40)}`);
+        lines.push('# GENERATED SUITE (env the generated tests/testkit read)');
+        lines.push(`# ${'='.repeat(40)}`);
+        for (const v of suiteVars) {
+            lines.push(`${v}=            # used by: generated tests`);
+        }
+        lines.push('');
+    }
     if (bootVars.length > 0) {
         lines.push(`# ${'='.repeat(40)}`);
         lines.push('# APP (read directly from source — REQUIRED to boot)');

package/dist/core/harness.js

@@ -34,11 +34,37 @@ export const HARNESS_CONTRACT = [
     `                                  /collections + enums), returning the`,
     `                                  created ids/handles`,
     `  - TEST_IDS: object              the stable well-known test ids/handles`,
+    `  - setup(): Promise<void>        THE one-call entry point (idempotent,`,
+    `                                  safe to call from every beforeAll AND`,
+    `                                  from a Playwright globalSetup). It:`,
+    `                                    1. connect()s + seed()s;`,
+    `                                    2. MINTS a fresh auth access token at`,
+    `                                       runtime — read the project's REAL`,
+    `                                       login/refresh auth (controllers/`,
+    `                                       middleware) and either exchange a`,
+    `                                       seed token (env, e.g. a refresh`,
+    `                                       token) or log in the seeded qa-`,
+    `                                       user to obtain it;`,
+    `                                    3. CACHES the minted token to a temp`,
+    `                                       file so parallel workers reuse it`,
+    `                                       (one mint per run, no churn);`,
+    `                                    4. POPULATES process.env for EVERY`,
+    `                                       token/id env var the suite reads`,
+    `                                       — GREP the sibling test files for`,
+    `                                       process.env.*TOKEN*/*ID* names and`,
+    `                                       set each to the minted/seeded`,
+    `                                       value, so tests that read`,
+    `                                       process.env work with NO hand-`,
+    `                                       pasted tokens.`,
+    `  - token(role?): string          the current access token accessor`,
     `Plus, for Playwright suites, ALSO export:`,
     `  - apiContext(request): a helper that returns an authed API request`,
-    `    context (Bearer token from an env var — NEVER hardcode a secret)`,
+    `    context (Bearer = the minted token — NEVER hardcode a secret)`,
     `  - login(page): Promise<void>    drive/seed an authenticated UI session`,
     `Use only env var NAMES for secrets/connection — never literal values.`,
+    `The ONLY credentials a developer should have to provide are the DB`,
+    `connection, a Stripe test key, and ONE seed/refresh token (or seeded`,
+    `login) — everything else setup() derives at runtime.`,
 ].join('\n');
 /** Where an area's shared testkit lives, and how tests import it. */
 export function harnessInfo(areaDir, framework, ext) {
@@ -64,8 +90,12 @@ function buildHarnessPrompt(harnessPath, framework) {
         `the project's REAL data layer and auth.`,
         ``,
         `You are inside the repository with read-only tools (Read, Grep, Glob,`,
-        `LS). READ the real DB config, the models/schemas, and the auth`,
-        `middleware, then implement the testkit against them.`,
+        `LS). READ the real DB config, the models/schemas, AND the real auth`,
+        `flow (login / refresh-token / OTP controllers + middleware) so setup()`,
+        `mints tokens the way the app actually does. Also GREP the sibling test`,
+        `files next to this testkit for every process.env.<NAME> they read`,
+        `(especially *TOKEN*, *_ID, base URLs) and make setup() POPULATE those`,
+        `exact names — the tests must run without any hand-pasted token.`,
         ``,
         `This is a ${framework === 'jest' ? 'Jest/backend' : 'Playwright/UI'} area.`,
         HARNESS_CONTRACT,
@@ -112,9 +142,10 @@ export function generateHarnessAsync(harnessPath, framework) {
 /**
  * A minimal Playwright config so a webapp/ops area that currently uses
  * Cypress can actually run the generated specs. Points at the area's test
- * dir and treats *.test.js as specs.
+ * 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) {
+export function playwrightConfig(testDirRelToPackage, globalSetupRelToPackage) {
     return [
         `// @generated by testforge`,
         `// Minimal Playwright config so testforge's generated specs run.`,
@@ -124,6 +155,7 @@ export function playwrightConfig(testDirRelToPackage) {
         `module.exports = defineConfig({`,
         `  testDir: '${testDirRelToPackage}',`,
         `  testMatch: /.*\\.(test|spec)\\.[jt]s$/,`,
+        `  globalSetup: require.resolve('${globalSetupRelToPackage}'),`,
         `  timeout: 60000,`,
         `  use: {`,
         `    baseURL: process.env.BASE_URL || 'http://localhost:3000',`,
@@ -133,3 +165,21 @@ export function playwrightConfig(testDirRelToPackage) {
         ``,
     ].join('\n');
 }
+/**
+ * Playwright globalSetup file: runs the testkit's one-call setup() once
+ * before the suite (connect + seed + mint/populate tokens). Sits next to
+ * the testkit and just delegates to it.
+ */
+export function globalSetupContent() {
+    return [
+        `// @generated by testforge`,
+        `// Runs once before the Playwright suite: seeds data and mints/`,
+        `// populates the auth tokens the specs read (via the testkit).`,
+        `const testkit = require('./testkit');`,
+        ``,
+        `module.exports = async () => {`,
+        `  await testkit.setup();`,
+        `};`,
+        ``,
+    ].join('\n');
+}

package/dist/core/run-generate.js

@@ -25,7 +25,7 @@ import { generateWithAI, generateWithAIAsync } from './ai-generator.js';
 import { generateSeed } from './seed-generator.js';
 import { planSuite } from './suite-planner.js';
 import { isSyntaxValid } from './validate.js';
-import { harnessInfo, generateHarnessAsync, playwrightConfig, } from './harness.js';
+import { harnessInfo, generateHarnessAsync, generateHarness, playwrightConfig, globalSetupContent, } from './harness.js';
 import { hashContent, loadCache, saveCache } from './cache.js';
 import { findMarkdownFiles } from './find-files.js';
 import { loadConfig, testDirForType, resolveFramework } from './config.js';
@@ -140,6 +140,53 @@ function collisionWarning(testDir, id, ext) {
         return null;
     return `an existing test with different naming already covers this journey: ${clashes.join(', ')} — new file may duplicate it`;
 }
+/**
+ * (Re)generate ONLY the shared harness for one or all areas — without
+ * touching any test file. Use this after upgrading the harness (e.g. to
+ * add token-minting): the new testkit populates process.env for the token
+ * vars the existing tests read, so they run unchanged. Cheap: one AI call
+ * per area, no test regeneration.
+ */
+export async function runHarness(only) {
+    const config = loadConfig();
+    const ext = config.testExtension ?? '.test.ts';
+    const areas = Object.keys(config.testOutput ?? {});
+    const written = [];
+    for (const area of areas) {
+        if (only && area !== only)
+            continue;
+        const areaDir = testDirForType(config, area);
+        const framework = resolveFramework(config, area, area);
+        const info = harnessInfo(areaDir, framework, ext);
+        let kit;
+        try {
+            kit = generateHarness(info.path, framework);
+        }
+        catch {
+            console.log(`  harness generation failed for area "${area}" — skipped`);
+            continue;
+        }
+        if (!isSyntaxValid(kit, ext.endsWith('.js') ? '.js' : '.ts')) {
+            console.log(`  harness for area "${area}" did not parse — skipped`);
+            continue;
+        }
+        mkdirSync(dirname(info.path), { recursive: true });
+        writeFileSync(info.path, kit, 'utf-8');
+        if (framework === 'playwright') {
+            const gsPath = join(info.dir, 'global-setup.js');
+            writeFileSync(gsPath, globalSetupContent(), 'utf-8');
+            const pkgRoot = dirname(areaDir);
+            const cfg = join(pkgRoot, 'playwright.config.js');
+            if (!existsSync(cfg)) {
+                const rel = areaDir.slice(pkgRoot.length + 1) || '.';
+                const gsRel = gsPath.slice(pkgRoot.length + 1);
+                writeFileSync(cfg, playwrightConfig(`./${rel}`, `./${gsRel}`), 'utf-8');
+            }
+        }
+        written.push(info.path);
+    }
+    return written;
+}
 /** Does this doc file / journey match a --journey selector? */
 function matchesJourney(file, journeyId, sel) {
     const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-');
@@ -175,13 +222,17 @@ export async function runGenerate(docsDir, useAI = true, force = false, only) {
         }
         mkdirSync(dirname(info.path), { recursive: true });
         writeFileSync(info.path, kit, 'utf-8');
-        // Playwright areas need a config so the specs can actually run.
+        // Playwright areas need a config + globalSetup so the specs can run
+        // AND get their tokens minted once before the suite.
         if (framework === 'playwright') {
+            const gsPath = join(info.dir, 'global-setup.js');
+            writeFileSync(gsPath, globalSetupContent(), 'utf-8');
             const pkgRoot = dirname(areaDir);
             const cfg = join(pkgRoot, 'playwright.config.js');
             if (!existsSync(cfg)) {
                 const rel = areaDir.slice(pkgRoot.length + 1) || '.';
-                writeFileSync(cfg, playwrightConfig(`./${rel}`), 'utf-8');
+                const gsRel = gsPath.slice(pkgRoot.length + 1);
+                writeFileSync(cfg, playwrightConfig(`./${rel}`, `./${gsRel}`), 'utf-8');
             }
         }
         harnessByArea.set(area, info.path);

package/package.json

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