@activate-core/test-forge 0.10.2 → 0.12.0

package/dist/core/harness.js

@@ -24,20 +24,57 @@ const MAP_PATH = 'testforge.md';
 export const HARNESS_CONTRACT = [
     `The testkit module MUST export exactly this stable API (CommonJS`,
     `module.exports), implemented against the project's real data layer:`,
-    `  - connect(): Promise<void>      open the DB connection (env DB var`,
-    `                                  from the map, e.g. process.env.DB_URL)`,
+    `  - connect(): Promise<void>      open the DB connection(s). Some apps`,
+    `                                  span MULTIPLE databases (e.g. a main DB,`,
+    `                                  a separate chat/conversation DB, and an`,
+    `                                  identity/IM DB) — READ the real data`,
+    `                                  config to find how many and their env-var`,
+    `                                  names, and connect to EACH. Do NOT assume`,
+    `                                  a single process.env.DB_URL.`,
     `  - disconnect(): Promise<void>   close it`,
-    `  - reset(): Promise<void>        remove all test data (only records`,
-    `                                  with the "qa-"/"QA-TEST" prefix)`,
+    `  - reset(): Promise<void>        remove ONLY test data (records with the`,
+    `                                  "qa-"/"QA-TEST" prefix or the well-known`,
+    `                                  TEST_IDS), cascading children by`,
+    `                                  projectId. MUST be gated — see SAFETY.`,
     `  - seed(spec?): Promise<object>  idempotently upsert the test records`,
     `                                  the tests need (using the real models`,
     `                                  /collections + enums), returning the`,
-    `                                  created ids/handles`,
-    `  - TEST_IDS: object              the stable well-known test ids/handles`,
+    `                                  created ids/handles. Seed EACH record`,
+    `                                  into the database it actually belongs to`,
+    `                                  (e.g. the identity/IM user in the IM DB,`,
+    `                                  a conversation in the chat DB) — not all`,
+    `                                  into one DB. Upsert with { $set: mutable,`,
+    `                                  $setOnInsert: { createdAt } } — never`,
+    `                                  replaceOne, never clobber creation`,
+    `                                  metadata or a pre-existing richer record.`,
+    `                                  Seeds are TRUSTED fixtures: do NOT let the`,
+    `                                  app's own schema quirks block them — if an`,
+    `                                  update-validator rejects a value the app`,
+    `                                  itself defaults (e.g. a required String`,
+    `                                  whose default is ''), write WITHOUT update`,
+    `                                  validators (runValidators:false) rather`,
+    `                                  than failing the whole seed.`,
+    `  - TEST_IDS: object              the stable well-known test ids/handles.`,
+    `                                  EVERY id MUST be env-overridable: resolve`,
+    `                                  each as process.env.TEST_<NAME>_ID ||`,
+    `                                  '<stable default>' (e.g. TEST_PROJECT_ID,`,
+    `                                  TEST_WEARER_ID). This lets a caller point`,
+    `                                  the suite at data created BY HAND on`,
+    `                                  staging/prod (with SEED_MODE=existing)`,
+    `                                  without editing code. Resolve non-id`,
+    `                                  handles (phone, email, auth subject) the`,
+    `                                  same env-overridable way.`,
     `  - 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;`,
+    `                                    1. connect()s; then seed()s — UNLESS`,
+    `                                       process.env.SEED_MODE === 'existing',`,
+    `                                       in which case it SKIPS seed() and`,
+    `                                       reset() and runs against data already`,
+    `                                       in the DB (staging/prod, where the`,
+    `                                       fixtures were created by hand and`,
+    `                                       addressed via the env-overridable`,
+    `                                       TEST_IDS);`,
     `                                    2. MINTS a fresh auth access token at`,
     `                                       runtime — read the project's REAL`,
     `                                       login/refresh auth (controllers/`,
@@ -64,11 +101,66 @@ export const HARNESS_CONTRACT = [
     `    fixture — \`const { request: apiRequest } = require('@playwright/`,
     `    test'); return apiRequest.newContext({ baseURL, extraHTTPHeaders })\`.`,
     `    The \`request\` FIXTURE has NO .newContext(); calling it throws.`,
-    `  - login(page): Promise<void>    drive/seed an authenticated UI session`,
+    `  - login(page): Promise<void>    establish an authenticated UI session`,
+    `                                  the webapp actually accepts. Inject the`,
+    `                                  SAME real minted access token (a valid,`,
+    `                                  decodable JWT — the app gate typically`,
+    `                                  jwtDecode()s it and checks exp) into the`,
+    `                                  EXACT localStorage/cookie keys the app`,
+    `                                  reads (GREP the auth reducer/guard for the`,
+    `                                  key names). A fabricated/opaque token that`,
+    `                                  fails the app's validity check leaves the`,
+    `                                  user logged-out (redirect loop). The token`,
+    `                                  owner MUST be the identity that owns the`,
+    `                                  seeded fixtures (see IDENTITY BINDING), so`,
+    `                                  the UI shows the seeded data.`,
     `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.`,
+    ``,
+    `SAFETY — this testkit must NEVER be able to damage a real environment:`,
+    `  - reset() and ANY delete/drop MUST refuse unless BOTH hold: the opt-in`,
+    `    flag process.env.TESTFORGE_ALLOW_RESET === 'true' is set, AND the`,
+    `    connection is clearly NOT production (e.g. host is localhost or the`,
+    `    DB name contains "test"). Otherwise throw a clear Error naming the`,
+    `    target. Default is SAFE: with the flag unset, reset() throws and`,
+    `    deletes nothing.`,
+    `  - When process.env.SEED_MODE === 'existing', reset() and all seed()`,
+    `    WRITES are skipped entirely — the suite runs against data already`,
+    `    present (hand-created on staging/prod), addressed via TEST_IDS. Do`,
+    `    not mutate that data destructively.`,
+    `  - Never widen a delete beyond the "qa-"/"QA-TEST" prefix + TEST_IDS`,
+    `    scope; always cascade children by projectId, never a bare drop.`,
+    ``,
+    `IDENTITY BINDING — the #1 cause of false failures, get this right.`,
+    `Owner-scoped endpoints ("my bookings", "my payouts") derive the owner`,
+    `from the AUTHENTICATED TOKEN, not from a query param — and a route`,
+    `declared auth:false may STILL populate request.user via a pre-auth`,
+    `extension when a Bearer is sent. Therefore:`,
+    `  - setup() MUST resolve the authenticated identity's REAL id (decode`,
+    `    the minted token's subject/_id claim, or call the profile/whoami`,
+    `    endpoint) and seed the OWNER fixtures (the maker/wearer/customer`,
+    `    whose data the tests read) under THAT id — then set the TEST_IDS`,
+    `    owner ids to it.`,
+    `  - Do NOT hardcode an owner id the token does not own: the seeded rows`,
+    `    would never be returned to the authenticated caller, and every`,
+    `    owner-scoped test would fail for a fake reason.`,
+    `  - A scope/IDOR test needing a SECOND, non-owner identity needs a`,
+    `    distinct token (env). If only one identity is available, make those`,
+    `    cases pending — never assert a scope the token cannot actually prove.`,
+    ``,
+    `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`,
+    `    use (e.g. mongoose.connection.readyState !== 1) and REOPEN if closed.`,
+    `    Do NOT gate reconnection behind a memoized "already set up" promise —`,
+    `    a cached promise that resolved once will NOT reopen a since-closed`,
+    `    connection. Guard on the ACTUAL connection state, not a boolean flag.`,
+    `  - Generated tests must NOT call disconnect() on the shared connection`,
+    `    in an afterAll/afterEach. Leave teardown to a single global teardown`,
+    `    (Playwright globalTeardown / Jest globalTeardown) that runs ONCE after`,
+    `    the whole run — never per-file.`,
 ].join('\n');
 /** Where an area's shared testkit lives, and how tests import it. */
 export function harnessInfo(areaDir, framework, ext) {
@@ -96,7 +188,10 @@ function buildHarnessPrompt(harnessPath, framework) {
         `You are inside the repository with read-only tools (Read, Grep, Glob,`,
         `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`,
+        `mints tokens the way the app actually does. Determine whether the app`,
+        `uses MORE THAN ONE database (e.g. a main DB, a chat/conversation DB, an`,
+        `identity/IM DB); if so, connect to and seed EACH via its own env-driven`,
+        `connection — do not collapse them into one. 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.`,
@@ -107,8 +202,10 @@ function buildHarnessPrompt(harnessPath, framework) {
                 `Because this is a JEST/backend area, do NOT require or import`,
                 `'@playwright/test' anywhere (it is not installed in a backend`,
                 `package — a top-level require would break every suite that loads`,
-                `this testkit). OMIT the Playwright-only apiContext/login exports;`,
-                `backend suites make HTTP calls with supertest, not Playwright.`,
+                `this testkit). OMIT the Playwright-only apiContext/login exports.`,
+                `Backend suites drive the server in-process via the framework's own`,
+                `inject (or an already-installed HTTP client) — never Playwright,`,
+                `and never a library this project has not installed.`,
                 ``,
             ]
             : []),
@@ -197,3 +294,54 @@ export function globalSetupContent() {
         ``,
     ].join('\n');
 }
+/**
+ * A fixture/environment guide written next to the testkit. Documents the
+ * two run modes and — crucially — how to run against data created BY HAND
+ * on staging/prod (env-addressable TEST_IDS + SEED_MODE=existing), plus the
+ * safety gates. Deterministic and project-agnostic; the exact per-entity
+ * shape lives in the generated seed()/TEST_IDS.
+ */
+export function fixturesDoc() {
+    return [
+        `# Test fixtures & environments`,
+        ``,
+        `Generated by testforge. The same tests run in two modes.`,
+        ``,
+        `## Modes`,
+        `- **auto** (default — local / CI): the testkit seeds its own fixtures`,
+        `  into a throwaway TEST database and resets them between runs. No manual`,
+        `  setup.`,
+        `- **existing** (staging / production): the testkit does NOT seed or`,
+        `  reset — it runs against data that already exists. Enable with:`,
+        ``,
+        `      SEED_MODE=existing`,
+        ``,
+        `## Running against data you created by hand (staging / prod)`,
+        `1. Create the fixture entities in the target database yourself (a`,
+        `   project, its price line(s), the wearer/maker users, etc.) — mirror`,
+        `   what the seed builders in \`helpers/testkit\` produce.`,
+        `2. Point the suite at them — every well-known id is env-overridable:`,
+        ``,
+        `      TEST_PROJECT_ID=<your project id>`,
+        `      TEST_WEARER_ID=<...>        # and any other TEST_*_ID the suite reads`,
+        ``,
+        `3. Provide auth + connection env (DB url/name(s), a seed/refresh token`,
+        `   or seeded login, Stripe test key).`,
+        `4. Run with \`SEED_MODE=existing\` so nothing is seeded or deleted.`,
+        ``,
+        `## Safety`,
+        `- \`reset()\` and any delete are DISABLED unless BOTH hold:`,
+        `  \`TESTFORGE_ALLOW_RESET=true\` AND the target DB is clearly`,
+        `  non-production (localhost, or a DB name containing "test"). Otherwise`,
+        `  it throws.`,
+        `- In \`SEED_MODE=existing\`, seeding and reset are skipped entirely —`,
+        `  your data is never mutated destructively.`,
+        `- NEVER point auto mode at a production database.`,
+        ``,
+        `## The exact fixture shape`,
+        `The precise fields/enums each fixture needs are defined by \`seed()\``,
+        `and \`TEST_IDS\` in \`helpers/testkit\`. Read those to reproduce a`,
+        `matching entity by hand.`,
+        ``,
+    ].join('\n');
+}

package/dist/core/playwright-writer.js

@@ -1,47 +1,62 @@
 /**
- * testforge — Playwright test file writer.
+ * testforge — deferred-stub writer (fallback only).
  *
- * Takes a Journey and its generated test cases and produces the
- * text of a runnable Playwright test file (.test.ts). It does not
- * write to disk itself; it returns the file content as a string so
- * the caller decides where to save it.
+ * When AI generation is unavailable (usage limit / repeated invalid
+ * output), testforge still needs to leave SOMETHING at the file path so
+ * the journey is visibly accounted for. It must NEVER be a test that
+ * runs and passes with no assertions — a silent false-green is the worst
+ * QA outcome. So this writer emits PENDING placeholders only:
+ *   - Jest       → test.todo(...)   (pending; no assertions; no import)
+ *   - Playwright → test.fixme(...)  (skipped; never counts as a pass)
  *
- * The generated tests use placeholder selectors and values, marked
- * with TODO comments, because testforge cannot know the real page
- * structure. A developer fills those in. Every test is tagged
- * @generated so it is easy to spot auto-created tests.
+ * It is also runner-aware: a Jest area never receives a
+ * `@playwright/test` import (which would break every suite that loads).
+ * A developer (or a later AI run) replaces these with real tests.
  */
-/** Build the import header and describe block opening. */
-function header(journey) {
+const BANNER = [
+    `// @generated by testforge — DEFERRED stub (AI generation was unavailable).`,
+    `// These are PLACEHOLDERS, not real tests: they are pending so they do`,
+    `// NOT pass silently. Regenerate with AI once available, or implement`,
+    `// them by hand.`,
+].join('\n');
+/** One pending entry, phrased for the area's runner. */
+function pendingLine(testCase, framework) {
+    const outcome = testCase.expect === 'pass' ? 'succeed' : 'be rejected';
+    const title = `${testCase.title} — TODO: implement (expected to ${outcome})`;
+    const safe = title.replace(/"/g, '\\"');
+    return framework === 'jest'
+        ? `  test.todo("${safe}");`
+        : `  test.fixme("${safe}", async () => {});`;
+}
+/**
+ * Build the full deferred-stub file for a journey, correct for the area's
+ * test runner. Every entry is pending, so the file contributes zero
+ * false-passing tests.
+ */
+export function writeDeferredStub(journey, cases, framework) {
+    const entries = (cases.length ? cases : [{ title: journey.name, expect: 'pass' }])
+        .map((c) => pendingLine(c, framework))
+        .join('\n');
+    if (framework === 'jest') {
+        // Jest globals — no import (a `@playwright/test` import here would
+        // break the whole suite in a backend package).
+        return [
+            BANNER,
+            ``,
+            `describe(${JSON.stringify(journey.name)}, () => {`,
+            entries,
+            `});`,
+            ``,
+        ].join('\n');
+    }
     return [
-        `import { test, expect } from "@playwright/test";`,
+        `import { test } from "@playwright/test";`,
+        ``,
+        BANNER,
         ``,
-        `// @generated by testforge — review before relying on these tests.`,
-        `test.describe("${journey.name}", () => {`,
+        `test.describe(${JSON.stringify(journey.name)}, () => {`,
+        entries,
+        `});`,
         ``,
     ].join('\n');
 }
-/** Build a single Playwright test block from one test case. */
-function testBlock(journey, testCase) {
-    const lines = [];
-    lines.push(`  // @generated`);
-    lines.push(`  test("${testCase.title}", async ({ page }) => {`);
-    lines.push(`    await page.goto("${journey.route}");`);
-    lines.push(``);
-    lines.push(`    // TODO: fill in the steps for this test.`);
-    if (testCase.expect === 'pass') {
-        lines.push(`    // This case is expected to succeed.`);
-        lines.push(`    // TODO: assert the success outcome (e.g. redirect or success message).`);
-    }
-    else {
-        lines.push(`    // This case is expected to fail / be rejected.`);
-        lines.push(`    // TODO: assert the error outcome (e.g. validation message shown).`);
-    }
-    lines.push(`  });`);
-    return lines.join('\n');
-}
-/** Build the full Playwright test file content for a journey. */
-export function writePlaywrightFile(journey, cases) {
-    const blocks = cases.map((c) => testBlock(journey, c)).join('\n\n');
-    return header(journey) + blocks + `\n\n});\n`;
-}