@sun-asterisk/sungen 3.2.19 → 3.2.20-beta.2

package/dist/orchestrator/templates/specs-url-assert.ts

@@ -0,0 +1,134 @@
+/* eslint-disable */
+/**
+ * Sungen URL assertion helper — auto-generated into specs/url-assert.ts. DO NOT EDIT.
+ *
+ * Every Then-side URL assertion (`see [X] page`, `is on [X] page`) compiles to one call here.
+ *
+ * Why a helper and not an inline predicate. The predicate used to be emitted inline into every
+ * spec, so each correction to what "the URL matches" MEANS was a breaking change for every
+ * generated suite in the field: regenerate everything, re-review every newly-red test. Behind a
+ * helper the same correction ships as a runtime patch. The generator's job shrinks to what it
+ * alone knows — the pathname pattern — and the semantics live in one readable place.
+ *
+ * Why a predicate and not two assertions. The shape before this one was
+ *   await expect(page).toHaveURL(/\/vi\/search/);      // unanchored: passes on /vi/search-x
+ *   expect(page.url()).toContain('<query>');           // synchronous, one-shot: never retries
+ * — two half-checks, neither anchored, and nothing ever compared pathname and query together.
+ * `toHaveURL(predicate)` is web-first (it retries like any other assertion), receives a parsed
+ * URL, and needs no regex escaping of runtime values, which is what forced the split.
+ */
+
+export interface UrlExpectation {
+  /**
+   * Anchored pathname pattern, compiled by the generator from the page selector's `value`
+   * (`:id` segments already wildcarded). Anchored against `u.pathname` ONLY: pathname never
+   * carries the query, so `^…$` is exact there — the same source that was unsafe to anchor
+   * against a full URL.
+   */
+  pathname: RegExp;
+  /**
+   * The `with {{v}}` value, raw from test-data: '?q=1' · '/vi/search?q=1' · '#tab' · ''.
+   * `undefined` means the step declared nothing, which is itself an assertion — see below.
+   */
+  declared?: string;
+  /** The test-data key behind `declared`, so a failure can name what an author must go fix. */
+  dataRef?: string;
+}
+
+/**
+ * Join a page's URL with the `with {{v}}` value for a NAVIGATION step
+ * (`Given User is on [X] page with {{v}}`).
+ *
+ * Why this is not a plain `base + path + value`. It used to be, and an author writing the value as a
+ * whole relative URL — the habit the assertion side already had to accommodate — navigated to
+ * `/vi/search/vi/search?q=1`: the page's own path, twice. The Then side then asserted the real path
+ * correctly, so the scenario could never go green.
+ *
+ * `base` (the configured baseURL, possibly '') and `path` (the page selector's value) arrive
+ * SEPARATELY so a value that carries its own rooted path replaces the page's path without also
+ * discarding a path prefix baked into the baseURL — a deployment under `https://host/tenant-a`
+ * would otherwise navigate to the wrong tenant, and only when a `with {{v}}` was present, which is
+ * exactly the kind of inconsistency nobody would think to look for.
+ *
+ * What it deliberately does NOT do is sanitize. A test may legitimately drive a MALFORMED query to
+ * prove the app rejects it (issue #464), so anything that is not a duplicated path is appended
+ * verbatim: no encoding, no normalising, no reordering.
+ */
+export function joinPath(base: string, path: string, declared?: string | null): string {
+  if (declared === undefined || declared === null || declared === '') return base + path;
+  const value = String(declared);
+  // A query/fragment appends — the overwhelmingly common shape, and the only one #464 needs.
+  if (value.startsWith('?') || value.startsWith('#')) return base + path + value;
+  // An absolute URL replaces everything: the author pasted a full address.
+  if (/^[a-z]+:\/\//i.test(value)) return value;
+  // A rooted path carries its own path, so it replaces the PAGE's path while everything the
+  // baseURL contributed — scheme, host, and any path prefix — is kept.
+  if (value.startsWith('/')) return base + value;
+  // Anything else is raw input the test wants appended as-is.
+  return base + path + value;
+}
+
+/**
+ * `u.pathname` is percent-encoded; a regex built from a selector's literal `value` is not, so a
+ * non-ASCII route (`/読取結果一覧`) could never match. Decoding can throw on a lone `%`, in which
+ * case the raw form is all there is.
+ */
+function decodedPath(pathname: string): string {
+  try {
+    return decodeURIComponent(pathname);
+  } catch {
+    return pathname;
+  }
+}
+
+/**
+ * Build the predicate for `expect(page).toHaveURL(...)`.
+ *
+ * Query semantics are deliberately asymmetric:
+ *   no `with {{v}}`  → the URL must carry NO query. A bare page means a bare page, so
+ *                      `/vi/search` does not pass on `/vi/search?x=1`.
+ *   `with {{v}}`     → every declared param must match; extra params are tolerated, so a
+ *                      tracking/UTM param the test never cared about cannot turn it red.
+ *                      A declared fragment is asserted too; a declared value carrying no query
+ *                      at all constrains the path only (the compiler warns: SG-W014).
+ */
+export function urlMatches({ pathname, declared, dataRef }: UrlExpectation): (u: URL) => boolean {
+  return (u: URL): boolean => {
+    if (!pathname.test(u.pathname) && !pathname.test(decodedPath(u.pathname))) return false;
+
+    // `dataRef`, not `declared`, decides which rule applies. Both "the step declared nothing" and
+    // "the step declared {{v}} but the key resolved to nothing at runtime" arrive here as
+    // undefined, and they mean opposite things: the first is a real assertion (a bare page must be
+    // bare), the second is broken test-data. Only the generator knows which, and it says so by
+    // emitting `dataRef` exactly when the step carried a `with {{v}}`.
+    if (!dataRef) return u.search === '';
+
+    // Silence is the whole bug class this assertion exists to kill, so an unusable declared value
+    // is an ERROR, not a quiet verdict. Returning false would read as "the app is wrong"; these
+    // throws say "your test-data is wrong, and here is the key". An empty value used to parse to
+    // an empty param list, and `[].every()` is vacuously TRUE — it passed on any query at all.
+    if (declared === undefined || declared === null) {
+      throw new Error(`url assertion: test-data key "${dataRef}" is missing — nothing to assert`);
+    }
+    if (String(declared).trim() === '') {
+      throw new Error(`url assertion: test-data key "${dataRef}" is empty — nothing to assert`);
+    }
+
+    // Parsing against the live pathname as base lets ONE expression handle every shape an author
+    // writes: '?q=1' (query only), '/vi/search?q=1' (a whole relative URL — its path is ignored,
+    // the page selector already owns the path), and '#tab' (fragment only). The predecessor
+    // regex-stripped the prefix instead, which silently turned a value with NO query
+    // ('/vi/search') into a bogus param NAME — an assertion that could never be satisfied.
+    const d = new URL(String(declared), 'http://sungen.invalid' + u.pathname);
+
+    // getAll, not get: a multi-select filter (?tag=a&tag=b) is the exact case this assertion is
+    // for, and `get()` returns only the first value — so the correct URL failed. Comparing as a
+    // subset per key keeps this consistent with "extra params are tolerated", and makes param
+    // order meaningless, which is what a URL actually means.
+    const queryOk = [...d.searchParams].every(([k, v]) => u.searchParams.getAll(k).includes(v));
+
+    // Only assert a fragment the author actually declared.
+    const hashOk = !d.hash || d.hash === u.hash;
+    return queryOk && hashOk;
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.19",
+  "version": "3.2.20-beta.2",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -39,8 +39,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.19",
-    "@sungen/driver-ui": "3.2.19",
+    "@sungen/driver-data-factory": "3.2.20-beta.2",
+    "@sungen/driver-ui": "3.2.20-beta.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/cli/commands/audit.ts

@@ -40,6 +40,14 @@ function render(r: AuditReport): void {
   if (r.gate.gaps.length) for (const g of r.gate.gaps) L(`      ✗ ${g.status === 'shallow' ? 'SHALLOW' : 'MISSING'}: ${g.theme}`);
   else L('      ✓ all critical themes covered (with data assertions)');
   L('');
+  if (r.flowQuality?.hasContract) {
+    const fq = r.flowQuality;
+    L(`  ①F Flow contract — goal: ${fq.contract!.goal}`);
+    L(`      outcome [${fq.contract!.outcome.screen}]: ${fq.outcomeProven ? '✓ proven (automated data assertion)' : fq.outcomeManualOnly ? '⚠ manual-only' : '✗ UNPROVEN'}`);
+    L(`      phases: ${fq.phases.map((p) => `${p.phase}=${p.covered ? (p.automated ? '✓' : 'manual') : '✗'}`).join('  ')}  → flowCoverage ${(fq.phaseRatio * 100).toFixed(0)}%`);
+    L(`      handoffs asserted: ${fq.handoffs.asserted}/${fq.handoffs.total}${fq.offGoal.length ? `   ⚠ off-goal scenarios: ${fq.offGoal.length} (${fq.offGoalCategories.join(', ')})` : ''}`);
+    L('');
+  }
   L(`  ② Assertion depth — ${r.depth.businessCriticalShallow}/${r.depth.businessCriticalTotal} business-critical scenarios are shallow (visibility/nav only)`);
   for (const s of r.depth.shallowBusinessCritical.slice(0, 8)) L(`      ⚠ ${s.category}: ${s.name}`);
   if (r.depth.shallowBusinessCritical.length > 8) L(`      … +${r.depth.shallowBusinessCritical.length - 8} more`);

package/src/cli/commands/delivery.ts

@@ -688,6 +688,12 @@ async function exportMatrixTarget(
   }
 
   log(`${COLOR.bold}${paths.label}${COLOR.reset} — ${model.manifest.itemCount} delivery item(s), ${model.manifest.variantCount} coverage variant(s), state: ${model.manifest.approvalState}`);
+  if (model.perf) {
+    const p = model.perf;
+    const tone = p.pass ? COLOR.green : COLOR.yellow;
+    log(`  ${tone}PERF ${p.pass ? 'PASS' : 'OVER BUDGET'}${COLOR.reset}: p${p.percentile} ${p.metric.replace('_ms', '')} ${p.measuredMs}ms ${p.pass ? '≤' : '>'} budget ${p.budgetMs}ms (${p.samples} run${p.samples === 1 ? '' : 's'})`);
+    for (const s of p.slowest) log(`    ${COLOR.yellow}slowest:${COLOR.reset} ${s.ms}ms — ${s.title.slice(0, 90)}`);
+  }
   printFindings(model.findings);
 
   if (opts.check) {

package/src/cli/commands/generate.ts

@@ -208,9 +208,14 @@ export function registerGenerateCommand(program: Command): void {
         }
 
         // Security S0 — warn (never block) if test-data looks to hold a real secret.
+        // Scoped to the unit being generated: --area used to fall through to the
+        // enumerate-everything branch, so `generate --area X` printed OTHER units'
+        // secret-scan and dead-data lint findings under X's run (field report: one
+        // unit's "service_url is dead data" warning repeated on all 10 API units).
         const scanDirs: string[] = [];
         if (screenName) scanDirs.push(path.join(process.cwd(), 'qa', 'screens', screenName));
         else if (flowName) scanDirs.push(path.join(process.cwd(), 'qa', 'flows', flowName));
+        else if (apiName) scanDirs.push(path.join(process.cwd(), 'qa', 'api', apiName));
         else {
           // qa/api units are yaml sinks too (apis.yaml headers, mock bodies once shared);
           // api/flows nests one level deeper. A file entry in the list is harmless —

package/src/exporters/matrix/build.ts

@@ -15,6 +15,7 @@ import {
   splitVpAndName,
 } from '../feature-parser';
 import { getCasesDatasetRows, resolveResultVariants } from '../result-variants';
+import { renderDynamicTokens } from '../test-data-resolver';
 import { classifyManualComments, renderAction, renderExpected, renderPrecondition, renderSetupInstruction, runtimeVarsOf } from './wording';
 import { scenarioFingerprint, combinedFingerprint, mapContentFingerprint } from './fingerprint';
 import {
@@ -265,7 +266,7 @@ function substituteDisplayVars(
   // `remember … as {{v}}` DECLARES v — leave that token for renderAction, which
   // turns it into a quoted name ("note it as …"), not a value to look up.
   const isCapture = /\bremember\b/i.test(text);
-  return text.replace(/\{\{\s*([^}\s]+)\s*\}\}/g, (m, key: string, offset: number) => {
+  const out = text.replace(/\{\{\s*([^}\s]+)\s*\}\}/g, (m, key: string, offset: number) => {
     if (isCapture && /\bas\s+$/i.test(text.slice(0, offset))) return m;
     // A value the test produces at run time has no static form — name it so the
     // tester knows to compare against what the earlier step captured.
@@ -273,6 +274,9 @@ function substituteDisplayVars(
     if (!(key in vars)) return m; // unknown stays literal → Gate D flags it
     return displayValue(vars[key]);
   });
+  // A dynamic token written straight into a step (`{{$uuid}}`) never reaches
+  // displayValue — name it here so the same wording covers both routes.
+  return renderDynamicTokens(out);
 }
 
 /**
@@ -281,6 +285,10 @@ function substituteDisplayVars(
  * The canonical value is never changed — only its presentation.
  */
 export function displayValue(v: string): string {
+  // Runtime-generated tokens nested in a value ("Summary intro {{$timestamp}}")
+  // are presentation, not canon — name them before the fidelity checks below,
+  // which judge the value's real whitespace.
+  v = renderDynamicTokens(v);
   if (v === '') return '(empty)';
   if (/^\s+$/.test(v)) return `(${v.length} space${v.length > 1 ? 's' : ''})`;
   if (v !== v.trim()) return `"${v}"`;

package/src/exporters/matrix/export.ts

@@ -16,6 +16,7 @@ import { mergeFeatureAndSpec } from '../scenario-merger';
 import { getPackageVersion } from '../package-info';
 import { writeCsv } from '../csv-exporter';
 import { writeXlsx } from '../xlsx-exporter';
+import { loadPerfConfig, perfVerdict } from '../../harness/perf';
 import { loadDeliveryMap, writeDeliveryMap } from './map-loader';
 import { mapContentFingerprint } from './fingerprint';
 import { buildMatrix, deriveVariants } from './build';
@@ -75,6 +76,16 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
   });
+  // Perf verdict (#569): budgets are config (qa/perf.yaml), samples are the run's
+  // per-test durations. Advisory — reported here because delivery is where runs
+  // are read; the audit's score stays a pure function of the design artifacts.
+  const perfConfig = loadPerfConfig(paths.cwd);
+  if (perfConfig && results) {
+    const samples = [...results.values()]
+      .filter((r) => (r.status === 'passed' || r.status === 'failed' || r.status === 'timedOut') && typeof r.duration === 'number')
+      .map((r) => ({ title: r.testTitle, ms: r.duration as number }));
+    model.perf = perfVerdict(perfConfig, paths.unit, samples);
+  }
   return { model, map, mapErrors: [] };
 }
 

package/src/exporters/matrix/render-xlsx.ts

@@ -315,6 +315,21 @@ function addCoverageSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersio
 
   let rowIdx = 7;
 
+  // --- Performance budget (#569) — advisory: config (qa/perf.yaml) vs measured runs.
+  if (model.perf) {
+    const p = model.perf;
+    dataCell(ws.getRow(rowIdx).getCell(2), 'Performance budget', { bold: true });
+    rowIdx++;
+    const r = ws.getRow(rowIdx);
+    dataCell(r.getCell(2), `p${p.percentile} ${p.metric.replace('_ms', ' time')}`);
+    dataCell(r.getCell(3), p.pass ? 'PASS' : 'OVER BUDGET', { bold: true });
+    dataCell(r.getCell(4), `measured ${p.measuredMs}ms`);
+    dataCell(r.getCell(5), `budget ${p.budgetMs}ms`);
+    dataCell(r.getCell(6), `${p.samples} runs`);
+    if (!p.pass && p.slowest.length) dataCell(r.getCell(8), `slowest: ${p.slowest.map((x) => `${x.ms}ms ${x.title.slice(0, 40)}`).join(' · ')}`);
+    rowIdx += 2;
+  }
+
   // --- Requirement coverage (review §6): every requirement id gets ONE explicit status.
   if (model.requirements.length > 0) {
     dataCell(ws.getRow(rowIdx).getCell(2), 'Requirement coverage — every id has an explicit status', { bold: true });

package/src/exporters/matrix/types.ts

@@ -220,6 +220,8 @@ export interface MatrixModel {
   requirements: RequirementCoverage[];
   findings: MatrixFinding[];
   manifest: MatrixManifest;
+  /** Perf verdict (#569) — present when qa/perf.yaml sets a budget AND the run produced durations. */
+  perf?: import('../../harness/perf').PerfVerdict | null;
 }
 
 /** Complexity warning threshold (rules draft Gate I; raised for compact grouping) — echoed in the manifest. */

package/src/exporters/playwright-report-parser.ts

@@ -54,6 +54,7 @@ interface PlaywrightSpec {
     projectId?: string;
     results?: Array<{
       status?: string;           // 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted'
+      duration?: number;         // ms — Playwright emits this on every result (#569 perf budgets)
       startTime?: string;
       error?: { message?: string; stack?: string };
       attachments?: Array<{ name?: string; path?: string; contentType?: string }>;
@@ -120,6 +121,7 @@ export function loadPlaywrightReport(reportPath: string): Map<string, Playwright
     result.set(stripped, {
       testTitle: stripped,
       status,
+      duration: typeof res?.duration === 'number' ? res.duration : undefined,
       startTime: res?.startTime,
       error: errorMsg,
       tracePath: trace,

package/src/exporters/test-data-resolver.ts

@@ -141,10 +141,43 @@ function truncate(s: string, max: number): string {
  * test-data map (or resolving to empty) is left as the literal `{{var}}` — never blanked.
  */
 export function substituteTestDataVars(text: string, testData: Record<string, string>): string {
-  return text.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (m, key: string) => {
+  const out = text.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (m, key: string) => {
     const v = testData[key];
     return v === undefined || v === null || v === '' ? m : String(v);
   });
+  // A substituted value may itself carry a dynamic token ("Award-{{$timestamp}}").
+  // String.replace never re-scans its own replacement, so name them afterwards.
+  return renderDynamicTokens(out);
+}
+
+/**
+ * Give the documented dynamic vars (`{{$timestamp}}`, `{{$uuid}}`,
+ * `{{$random:min:max}}`, `{{$date}}`, `{{$datetime}}`) a form a tester can act on.
+ *
+ * These are resolved by TestDataLoader at execution time, never from
+ * test-data.yaml — so at export time they have no static value, exactly like a
+ * value the run captures (`remember … as {{v}}` → `the captured v`). Left raw,
+ * the token ships into the deliverable and the matrix's Gate D rejects the
+ * whole export. Named, the tester reads what to type: any value of that shape,
+ * uniqueness being the whole point.
+ *
+ * An UNKNOWN `{{$foo}}` stays literal on purpose — the runtime resolver also
+ * leaves it raw, so it is an authoring typo and must keep failing Gate D.
+ */
+export function renderDynamicTokens(text: string): string {
+  return text.replace(/\{\{\s*\$(\w+)(?::([^}]*))?\s*\}\}/g, (m, name: string, args?: string) => {
+    switch (name) {
+      case 'timestamp': return '<unique timestamp>';
+      case 'uuid': return '<unique id>';
+      case 'random': {
+        const [min, max] = (args || '1:9999').split(':');
+        return `<random ${min}-${max}>`;
+      }
+      case 'date': return "<today's date>";
+      case 'datetime': return '<current date-time>';
+      default: return m;
+    }
+  });
 }
 
 /**

package/src/exporters/types.ts

@@ -121,6 +121,8 @@ export interface SpecFileData {
 export interface PlaywrightResult {
   testTitle: string;
   status: 'passed' | 'failed' | 'skipped' | 'timedOut' | 'interrupted' | 'unknown';
+  /** Wall-clock run time in ms (from Playwright's results[].duration) — perf budgets (#569). */
+  duration?: number;
   startTime?: string;
   error?: string;
   tracePath?: string;

package/src/generators/test-generator/adapters/adapter-interface.ts

@@ -67,7 +67,7 @@ export interface TestGeneratorAdapter {
   // Template rendering methods
   renderTestFile(data: TestFileData): string;
   renderScenario(data: ScenarioData): string;
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean }): string;
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean; urlAssertImports?: string }): string;
   renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderBeforeAll(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderAfterEach(data: { steps: Array<{ comment?: string; code: string }> }): string;

package/src/generators/test-generator/adapters/appium/appium-adapter.ts

@@ -31,7 +31,7 @@ export class AppiumAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderScenario(data);
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean }): string {
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean; urlAssertImports?: string }): string {
     return this.templateEngine.renderImports(options);
   }
 

package/src/generators/test-generator/adapters/playwright/playwright-adapter.ts

@@ -26,7 +26,7 @@ export class PlaywrightAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderScenario(data);
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean }): string {
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean; urlAssertImports?: string }): string {
     return this.templateEngine.renderImports(options);
   }
 

package/src/generators/test-generator/adapters/playwright/templates/imports.hbs

@@ -12,6 +12,9 @@ import { api } from '{{basePath}}/api';
 {{#if needsMock}}
 import { mock } from '{{basePath}}/mock';
 {{/if}}
+{{#if urlAssertImports}}
+import { {{urlAssertImports}} } from '{{basePath}}/url-assert';
+{{/if}}
 
 // This file is auto-generated from Gherkin feature files
 // DO NOT EDIT MANUALLY - changes will be overwritten

package/src/generators/test-generator/adapters/playwright/templates/steps/navigation/navigation.hbs

@@ -1,2 +1,6 @@
+{{#if query}}
+await page.goto(joinPath('{{#if baseURL}}{{baseURL}}{{/if}}', '{{path}}', '{{escapeQuotes query}}'), { waitUntil: 'load' });
+{{else}}
 await page.goto('{{#if baseURL}}{{baseURL}}{{/if}}{{path}}', { waitUntil: 'load' });
+{{/if}}
 await page.waitForLoadState('domcontentloaded');

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/url-assertion.hbs

@@ -2,9 +2,14 @@
       Both used to carry their own copy and drifted apart: `see [X] page` wildcarded a dynamic
       `:id` segment but silently dropped `with {{v}}`, while `is on [X] page` asserted the query
       but escaped `:id` literally into a regex that can never match. One partial, one behaviour.
-      `pathRegex` is pre-escaped by pathToRegexSource (`:id` → `[^/]+`); the query is asserted
-      separately because its value is runtime data full of regex-special characters. --}}
-await expect(page).toHaveURL(/{{pathRegex}}/);
-{{#if query}}
-expect(page.url()).toContain('{{escapeQuotes query}}');
-{{/if}}
+
+      The predicate itself lives in specs/url-assert.ts (template: specs-url-assert.ts) — read it
+      for the semantics. It is a runtime helper rather than an inline lambda so that correcting
+      what "the URL matches" MEANS is a runtime patch, not a regenerate-the-world breaking change
+      for every suite in the field.
+
+      Only `pathRegex` is the generator's business: it alone knows the page selector's value and
+      its `:id` wildcards, and it is pre-escaped by pathToRegexSource. `\/?$` normalises a
+      trailing slash so `/vi/search/` does not read as a different page. The declared value stays
+      a plain string literal so the runtime-data marker pass can rewrite it to testData.get(…). --}}
+await expect(page).toHaveURL(urlMatches({ pathname: /^{{pathRegex}}\/?$/{{#if query}}, dataRef: '{{escapeQuotes dataRef}}', declared: '{{escapeQuotes query}}'{{/if}} }));

package/src/generators/test-generator/code-generator.ts

@@ -316,11 +316,19 @@ export class CodeGenerator {
       for (const h of capabilityRegistry.get(id)?.runtimeHelpers ?? []) this.syncGeneratedHelper(outputDir, h.file, h.template);
     }
 
-    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb, needsApi, needsMock });
-
     // Generate test code (async now to support AI mapping)
     const testCode = await this.generateTestCode(feature);
 
+    // `url-assert` is imported from what the body actually emitted, not from an active capability:
+    // page assertions belong to the DEFAULT ui capability, so a capability flag would import the
+    // helper into every UI spec — including the many that touch no URL at all. Hence the body is
+    // rendered BEFORE the imports. Importing exactly the names used keeps the import honest; the
+    // helper file itself is synced only when something needs it (an api-only unit carries none).
+    const urlAssertImports = ['urlMatches', 'joinPath'].filter((n) => testCode.includes(`${n}(`)).join(', ');
+    if (urlAssertImports) this.syncGeneratedHelper(outputDir, 'url-assert.ts', 'specs-url-assert.ts');
+
+    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb, needsApi, needsMock, urlAssertImports });
+
     // Combine and collapse any runs of 3+ newlines down to 2 (one blank line max)
     const raw = `${imports}\n\n${testCode}`;
     let code = raw.replace(/\n{3,}/g, '\n\n');

package/src/generators/test-generator/diagnostics.ts

@@ -26,12 +26,21 @@
  *   SG-W012 — a mock-install step AFTER a navigation step in the same block: page.route()
  *             registered after goto() misses every request fired during page load — move
  *             the install before the navigation (or into Background)
+ *   SG-W013 — a page assertion whose path came from a FALLBACK, not from a `type: page` selector
+ *             entry: the `[Ref]` did not resolve (or resolved to a non-page entry), so the step
+ *             asserts the feature's own path (or `/<ref>/`) instead of the page it names. The
+ *             assertion is anchored, so this is now a test that cannot pass rather than one that
+ *             always passed — either way it is not asserting what it reads as
+ *   SG-W014 — `[X] page with {{v}}` where the value carries no query and no fragment: there is
+ *             nothing for the query half to assert, so the step checks the PATH only. Not an
+ *             error (the value may legitimately vary per environment), but the step asserts
+ *             strictly less than it appears to
  *
  * Diagnostics never block generation by themselves; `sungen generate --strict`
  * turns any collected diagnostic into a non-zero exit.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014';
 
 export interface Diagnostic {
   code: DiagnosticCode;

package/src/generators/test-generator/step-mapper.ts

@@ -333,6 +333,8 @@ export class StepMapper {
         console.log(`  ✓ Pattern matched: ${step.text.substring(0, 50)}...`);
       }
       this.checkDataRefConsumed(step, mappedStep);
+      this.checkPageAssertionFallback(step, mappedStep);
+      this.checkDeclaredUrlHasNoQuery(step, mappedStep);
       return mappedStep;
     }
 
@@ -400,6 +402,58 @@ export class StepMapper {
     return expr || undefined;
   }
 
+  /**
+   * SG-W013 — a page assertion whose path came from a fallback rather than from a `type: page`
+   * selector entry. Both resolvers degrade quietly when `[Ref]` does not resolve: `see [X] page`
+   * falls back to the feature's own path, `is on [X] page` to `/<ref>/`. Before the assertion was
+   * anchored that produced a test which always PASSED; anchored, it produces one that can never
+   * pass. Neither is the assertion the author wrote, and nothing said so.
+   *
+   * Detected here rather than in the resolver on purpose: `MappedStep` carries only
+   * `{code, comment, imports}`, and the resolvers live in the driver packages while the collector
+   * lives in core. Re-asking the SAME resolver the step-mapper already owns costs three lines and
+   * duplicates no logic — the alternative is widening the adapter contract for every driver.
+   */
+  private checkPageAssertionFallback(step: ParsedStep, mapped: MappedStep): void {
+    if (!this.diagnostics || !step.selectorRef || step.elementType !== 'page') return;
+    if (!(mapped.code || '').includes('urlMatches(')) return;
+    let resolvedAsPage = false;
+    try {
+      const resolved = this.selectorResolver.resolveSelector(
+        step.selectorRef, this.featureName, step.elementType, step.nth
+      );
+      resolvedAsPage = resolved.selectorType === 'page' && !!resolved.value;
+    } catch {
+      resolvedAsPage = false;
+    }
+    if (resolvedAsPage) return;
+    this.diagnostics.add('SG-W013',
+      `page assertion for "[${step.selectorRef}]" has no "type: page" selector entry, so it asserts a FALLBACK path — the anchored assertion cannot match the real URL. Declare the page, e.g. "${step.selectorRef.toLowerCase()}:\\n  type: page\\n  value: '/your/path'"`,
+      { feature: this.featureName, step: step.text });
+  }
+
+  /**
+   * SG-W014 — `[X] page with {{v}}` where the value carries neither a query nor a fragment, so the
+   * query half of the assertion has nothing to check and the step asserts the PATH only.
+   *
+   * Deliberately a warning, not an error, and deliberately judged on the BASE test-data value: an
+   * env overlay can supply a query the base file lacks, so failing generation here would block a
+   * suite over data that is fine at run time. But it must not be silent either — asserting less
+   * than the step reads as is exactly the false-positive class this assertion exists to remove.
+   * Distinct from SG-W002: there the value is DROPPED, here it is used and found to hold no query.
+   */
+  private checkDeclaredUrlHasNoQuery(step: ParsedStep, mapped: MappedStep): void {
+    if (!this.diagnostics || !step.dataRef || step.elementType !== 'page') return;
+    if (!(mapped.code || '').includes('urlMatches(')) return;
+    // The base value, never resolveData(): in runtime mode that returns the marker, which carries
+    // no query by construction — the diagnostic would then fire on every single step.
+    const value = this.dataResolver.peekBaseValue(step.dataRef, this.featureName);
+    if (value == null || /[?#]/.test(value)) return;
+    this.diagnostics.add('SG-W014',
+      `{{${step.dataRef}}} = "${value}" carries no query and no fragment, so this page assertion checks the PATH only. Pass a value like "?q=…" (or drop the "with" and let the step assert a bare page).`,
+      { feature: this.featureName, step: step.text });
+  }
+
   /**
    * SG-W002 — a step carried a parsed {{dataRef}} but the matched pattern's generated
    * code never uses it (neither the runtime marker, the ${ref} fallback, nor the

package/src/generators/test-generator/template-engine.ts

@@ -277,8 +277,8 @@ export class TemplateEngine {
     this.baseContext = { ...this.persistentContext };
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean }): string {
-    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb, needsApi: options?.needsApi, needsMock: options?.needsMock });
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean; urlAssertImports?: string }): string {
+    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb, needsApi: options?.needsApi, needsMock: options?.needsMock, urlAssertImports: options?.urlAssertImports });
   }
 
   renderTestFile(data: {

package/src/generators/test-generator/utils/data-resolver.ts

@@ -64,6 +64,25 @@ export class DataResolver {
     return this.resolveValue(dataRef, featureName);
   }
 
+  /**
+   * The value as the BASE test-data file spells it, whatever the mode — for compile-time
+   * diagnostics that must judge the value itself, not the `__SUNGEN_TD$…$__` marker that
+   * `resolveData` returns in runtime mode.
+   *
+   * Returns undefined rather than throwing when the ref cannot be read (unknown path, or a
+   * captured var that only exists at runtime): a diagnostic must never break generation. Callers
+   * must treat the result as the base value only — an env overlay can change it at run time, so
+   * anything said about it belongs in a warning, never a gate.
+   */
+  peekBaseValue(dataRef: string, featureName?: string): string | undefined {
+    if (this.capturedVars.has(dataRef)) return undefined;
+    try {
+      return this.resolveValue(dataRef, featureName);
+    } catch {
+      return undefined;
+    }
+  }
+
   private resolveValue(dataRef: string, featureName?: string): string {
     const { fileName, valuePath } = this.parseDataRef(dataRef, featureName);
     const data = this.loadDataFile(fileName);