@sun-asterisk/sungen 3.2.18 → 3.2.19

package/src/orchestrator/templates/playwright.config.ts

@@ -1,4 +1,33 @@
 import { defineConfig, devices } from '@playwright/test';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Web baseURL per environment — one compiled suite runs on dev/uat/stg by
+ * switching SUNGEN_ENV, no config edit and no recompile.
+ *
+ * Precedence (first hit wins):
+ *   1. `SUNGEN_BASE_URL` from the shell/CI env
+ *   2. `SUNGEN_BASE_URL=` in `.env.qa.<SUNGEN_ENV>` (e.g. `.env.qa.uat`)
+ *   3. `SUNGEN_BASE_URL=` in `.env.qa`
+ *   4. the static fallback below (written by `sungen init --base-url`)
+ *
+ * Mirrors how the runtime resolves `${QA_*}` test-data refs and API/DB
+ * datasource URLs, so every layer of a run agrees on the environment.
+ */
+function resolveBaseUrl(fallback: string): string {
+  if (process.env.SUNGEN_BASE_URL) return process.env.SUNGEN_BASE_URL;
+  for (const name of [`.env.qa.${process.env.SUNGEN_ENV || ''}`, '.env.qa']) {
+    if (name.endsWith('.')) continue;
+    const p = path.join(process.cwd(), name);
+    if (!fs.existsSync(p)) continue;
+    for (const line of fs.readFileSync(p, 'utf8').split('\n')) {
+      const m = line.match(/^\s*SUNGEN_BASE_URL\s*=\s*(.*?)\s*$/);
+      if (m) return m[1].replace(/^["']|["']$/g, '');
+    }
+  }
+  return fallback;
+}
 
 /**
  * Resolve the JSON reporter output path.
@@ -61,8 +90,10 @@ export default defineConfig({
   ],
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
   use: {
-    /* Base URL to use in actions like `await page.goto('')`. */
-    baseURL: 'https://example.com',
+    /* Base URL to use in actions like `await page.goto('')`. The quoted value is the
+       static fallback (pre-filled by `sungen init --base-url`); SUNGEN_BASE_URL in the
+       shell or .env.qa[.<SUNGEN_ENV>] overrides it per environment. */
+    baseURL: resolveBaseUrl('https://example.com'),
 
     /* Per-action timeout (click, fill, etc.) */
     actionTimeout: 10_000,

package/src/orchestrator/templates/specs-mock.ts

@@ -0,0 +1,179 @@
+/* eslint-disable */
+/**
+ * Sungen Mock Driver — runtime network-mocking helper (auto-generated into specs/mock.ts).
+ *
+ * One module singleton (same import shape as db/api); ALL state lives per-page in a
+ * WeakMap<Page, MockState>, so routes and call counters follow the page's lifetime on
+ * both isolation paths: a fresh page per test destroys them for free, and the @serial
+ * shared page is reset by the compiler-emitted mock.reset(page) at the end of each
+ * @mock scenario (scoped — only routes THIS router installed are unrouted; a blanket
+ * page.unrouteAll() would also kill Background-installed mocks and third-party routes).
+ *
+ * Blocking posture (fail-on-unmocked, the project default): the first install() also
+ * registers a catch-all route. Playwright matches routes last-registered-first, so
+ * registering the catch-all FIRST makes every named mock win over it. The catch-all
+ * only judges fetch/XHR/websocket traffic — documents/scripts/styles/images pass, the
+ * app shell must still load; what is being isolated is API traffic. An unmatched API
+ * request aborts and throws (fails the test) unless the scenario opted out via
+ * @mock:passthrough (compiled to mock.setPassthrough(page)).
+ *
+ * DO NOT EDIT — regenerated by `sungen generate`.
+ */
+import type { Page, Route } from '@playwright/test';
+
+export interface MockConfig {
+  name: string;
+  method: string;               // HTTP verb or '*'
+  url: string;                  // page.route glob, or 're:<pattern>' for a regex
+  status: number;
+  headers?: Record<string, string>;
+  body?: string;                // pre-serialized by the compiler (JSON string)
+  delay_ms?: number;
+}
+
+interface InstalledRoute {
+  pattern: string | RegExp;
+  handler: (route: Route) => Promise<void>;
+}
+
+interface MockState {
+  counts: Map<string, number>;      // per-mock handled-request counters
+  installed: Set<string>;           // names installed in this scenario (callCount guard)
+  routes: InstalledRoute[];         // exactly what WE routed (scoped reset)
+  guardInstalled: boolean;
+  passthrough: boolean;
+  violations: string[];             // unmocked requests the guard aborted (fail-on-unmocked)
+  /** @serial only: routes[0..N) / names installed by Background (beforeAll) persist across
+   *  scenarios — reset() removes only what a scenario added on top. -1 = no snapshot
+   *  (the default per-test path), where reset() drops the whole state. */
+  backgroundRouteCount: number;
+  backgroundNames: Set<string>;
+}
+
+/** Resource types the fail-on-unmocked guard judges; everything else passes through.
+ *  NOTE: page.route() does NOT intercept WebSocket connections (that is
+ *  page.routeWebSocket, a separate API) — the shipped posture is fetch/XHR only. */
+const GUARDED_TYPES = new Set(['fetch', 'xhr']);
+
+class MockRouter {
+  private state = new WeakMap<Page, MockState>();
+
+  private stateFor(page: Page): MockState {
+    let st = this.state.get(page);
+    if (!st) {
+      st = { counts: new Map(), installed: new Set(), routes: [], guardInstalled: false, passthrough: false, violations: [], backgroundRouteCount: -1, backgroundNames: new Set() };
+      this.state.set(page, st);
+    }
+    return st;
+  }
+
+  /** `@mock:passthrough` — unmatched requests reach the real backend for this page/scenario.
+   *  Also forgives violations already recorded (Background installs + goto run BEFORE the
+   *  scenario body can set this flag — boot-time requests of an opted-out scenario must not
+   *  fail its assertNoUnmocked verdict). The compiler additionally arms the flag inside
+   *  beforeEach via test.info().tags, before the Background installs, so boot requests are
+   *  not even aborted on the default path. */
+  setPassthrough(page: Page): void {
+    const st = this.stateFor(page);
+    st.passthrough = true;
+    st.violations.length = 0;
+  }
+
+  /** Install one catalog entry. The first install also arms the fail-on-unmocked guard. */
+  async install(page: Page, cfg: MockConfig): Promise<void> {
+    const st = this.stateFor(page);
+    if (!st.guardInstalled) {
+      st.guardInstalled = true;
+      const guard = async (route: Route) => {
+        const req = route.request();
+        if (!GUARDED_TYPES.has(req.resourceType()) || st.passthrough) return route.fallback();
+        // Record + abort — NEVER throw here: a route handler runs outside any test
+        // stack, so a throw surfaces as an unhandled rejection (a hard process crash
+        // outside @playwright/test, flaky attribution inside it). The compiler emits
+        // `await mock.assertNoUnmocked(page)` at the end of every @mock scenario,
+        // which fails the test deterministically with the FULL violation list.
+        st.violations.push(`${req.method()} ${req.url()}`);
+        await route.abort('failed');
+      };
+      await page.route('**/*', guard); // FIRST → matched last → every named mock wins
+      st.routes.push({ pattern: '**/*', handler: guard });
+    }
+
+    const pattern = cfg.url.startsWith('re:') ? new RegExp(cfg.url.slice(3)) : cfg.url;
+    const handler = async (route: Route) => {
+      if (cfg.method !== '*' && route.request().method() !== cfg.method) return route.fallback();
+      st.counts.set(cfg.name, (st.counts.get(cfg.name) ?? 0) + 1);
+      if (cfg.delay_ms) await new Promise((r) => setTimeout(r, cfg.delay_ms));
+      // A delayed fulfill can race a page close / reset at teardown — that race must
+      // not surface as an unhandled rejection from inside a route handler.
+      try { await route.fulfill({ status: cfg.status, headers: cfg.headers, body: cfg.body }); } catch { /* page closing */ }
+    };
+    await page.route(pattern, handler);
+    st.routes.push({ pattern, handler });
+    st.installed.add(cfg.name);
+    if (!st.counts.has(cfg.name)) st.counts.set(cfg.name, 0);
+  }
+
+  /** Handled-request count for a mock installed in THIS scenario — throws for a name
+   *  that was never installed here (an exact 0 on an uninstalled mock must be a loud
+   *  error, not a passing assertion). */
+  callCount(page: Page, name: string): number {
+    const st = this.state.get(page);
+    if (!st || !st.installed.has(name)) {
+      throw new Error(`mock "${name}" was never installed in this scenario — add \`Given [${name}] mock is active\``);
+    }
+    return st.counts.get(name) ?? 0;
+  }
+
+  /** Fail-on-unmocked verdict — emitted by the compiler as the LAST statement of every
+   *  @mock scenario. Throws with the full list of aborted unmatched requests; a scenario
+   *  whose app swallowed those failed fetches must not stay green for the wrong reason. */
+  async assertNoUnmocked(page: Page): Promise<void> {
+    const st = this.state.get(page);
+    if (!st || st.violations.length === 0) return;
+    const list = st.violations.slice();
+    st.violations.length = 0;
+    throw new Error(
+      `${list.length} unmocked request(s) hit the fail-on-unmocked guard:\n  - ${list.join('\n  - ')}\n` +
+      'Add entries to mock/mocks.yaml, or opt out with @mock:passthrough.');
+  }
+
+  /** @serial only, emitted by the compiler at the END of the Background block (beforeAll):
+   *  everything installed so far — Background mocks and the guard — persists across the
+   *  feature's scenarios; reset() removes only what each scenario added on top. Without
+   *  this, scenario 1's reset would kill the Background mocks and scenarios 2+ would run
+   *  against the REAL backend with no guard — the silent-green class this driver exists
+   *  to prevent. */
+  snapshotBackground(page: Page): void {
+    const st = this.stateFor(page);
+    st.backgroundRouteCount = st.routes.length;
+    st.backgroundNames = new Set(st.installed);
+  }
+
+  /** Scoped teardown for the @serial shared page: unroute exactly what THIS scenario
+   *  installed (Background routes captured by snapshotBackground persist), zero every
+   *  counter, clear flags/violations. Emitted at the end of each @mock scenario on the
+   *  serial path; the default per-test path never needs it (page dies with the test). */
+  async reset(page: Page): Promise<void> {
+    const st = this.state.get(page);
+    if (!st) return;
+    if (st.backgroundRouteCount < 0) {
+      // No Background snapshot → drop everything (the pre-snapshot / default behavior).
+      for (const r of st.routes) {
+        try { await page.unroute(r.pattern, r.handler); } catch { /* page may be closing */ }
+      }
+      this.state.delete(page);
+      return;
+    }
+    for (const r of st.routes.slice(st.backgroundRouteCount)) {
+      try { await page.unroute(r.pattern, r.handler); } catch { /* page may be closing */ }
+    }
+    st.routes.length = st.backgroundRouteCount;
+    st.installed = new Set(st.backgroundNames);
+    st.counts = new Map();
+    st.violations.length = 0;
+    st.passthrough = false;
+  }
+}
+
+export const mock = new MockRouter();

package/src/orchestrator/test-data-guide.ts

@@ -129,6 +129,10 @@ const ENV_QA_EXAMPLE = `# Secret test data referenced as \${QA_*} in qa/**/test-
 # Per-environment overrides: .env.qa.<env> + run with SUNGEN_ENV=<env>.
 #
 # QA_ADMIN_PASSWORD=
+#
+# Web baseURL for this environment — overrides the static value in
+# playwright.config.ts (declare per env: .env.qa.dev, .env.qa.uat, ...).
+# SUNGEN_BASE_URL=
 `;
 
 /**