@sungen/driver-ui 3.2.34 → 3.3.0-alpha.2

package/dist/utils/url-path-regex.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * URL-path → RegExp-source conversion for page URL assertions (`toHaveURL`) and
+ * navigation waits (`waitForURL`).
+ *
+ * A selector's `value` may carry dynamic route placeholders (`:id`, `:receptionId`,
+ * …), e.g. `/cn22/view/so/ocr/results/:id`. A live URL populates those segments with
+ * real values (`…/results/rec-dummy-000017`), so a fully-escaped literal pattern would
+ * never match. Placeholder segments become a single-segment wildcard (`[^/]+`); every
+ * other segment is escaped so its regex metacharacters stay literal.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeRegex = escapeRegex;
+exports.pathToRegexSource = pathToRegexSource;
+exports.urlToPatternParts = urlToPatternParts;
+const REGEX_SPECIALS = /[.*+?^${}()|[\]\\/]/g;
+/** Escape a literal string for safe use inside a RegExp source. */
+function escapeRegex(text) {
+    return text.replace(REGEX_SPECIALS, '\\$&');
+}
+/**
+ * Convert a URL path into a RegExp source string, turning dynamic route
+ * placeholders (`:name`) into `[^/]+` wildcards while escaping literal segments.
+ * `/` is emitted as the escaped `\/` so the result drops straight into `/…/`. A query or
+ * fragment in the input is dropped — see the comment in the body.
+ */
+function pathToRegexSource(path) {
+    // Every caller compiles this into a pattern tested against `u.pathname`, which never carries a
+    // query or a fragment. A page selector whose `value` includes one ('/search?tab=1' — off the
+    // documented "the value carries the PATH only" contract, but written in the field) would
+    // otherwise escape the `?` into the pattern and produce a match no real URL can satisfy: an
+    // assertion that can never pass, a wait that can only time out. Dropped here, once, rather than
+    // in each of the four resolvers that build a pathname pattern.
+    return path
+        .replace(/[?#].*$/, '')
+        .split('/')
+        .map((segment) => /^:[A-Za-z_][A-Za-z0-9_]*$/.test(segment) ? '[^/]+' : escapeRegex(segment))
+        .join('\\/');
+}
+/**
+ * Split a page value into the host and path patterns the runtime matches separately.
+ *
+ * `u.hostname` never appears in `u.pathname`, so one concatenated regex cannot carry both — it
+ * only ever "worked" while the match ran unanchored across the whole URL, which is the looseness
+ * that let a wait resolve on a transient URL (#677). A page value that names an absolute URL
+ * therefore yields two patterns; a relative one yields the path pattern alone, exactly as before.
+ *
+ * Every caller that builds a pathname pattern for a URL assertion or wait goes through here, so
+ * the host half cannot be honoured on one step form and silently dropped on another: before this,
+ * only `wait for [X] page` split the host, while both assertion forms matched the path against
+ * ANY host — `see [X] page` with `https://admin.example.com/jobs` passed on the public site.
+ *
+ * Dynamic `:id` segments still wildcard; the host stays a literal. A value that starts like an
+ * absolute URL but does not parse falls back to the path-only reading rather than throwing — the
+ * pattern is then wrong in a way the author can read, which beats losing the step.
+ */
+function urlToPatternParts(path) {
+    if (!/^https?:\/\//i.test(path))
+        return { pathRegex: pathToRegexSource(path) };
+    try {
+        const url = new URL(path);
+        return { hostRegex: escapeRegex(url.hostname), pathRegex: pathToRegexSource(url.pathname) };
+    }
+    catch {
+        return { pathRegex: pathToRegexSource(path) };
+    }
+}
+//# sourceMappingURL=url-path-regex.js.map

package/dist/utils/url-path-regex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-path-regex.js","sourceRoot":"","sources":["../../src/utils/url-path-regex.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AAKH,kCAEC;AAQD,8CAcC;AA2BD,8CAQC;AA9DD,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAE9C,mEAAmE;AACnE,SAAgB,WAAW,CAAC,IAAY;IACtC,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,IAAY;IAC5C,+FAA+F;IAC/F,6FAA6F;IAC7F,yFAAyF;IACzF,4FAA4F;IAC5F,gGAAgG;IAChG,+DAA+D;IAC/D,OAAO,IAAI;SACR,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;SACtB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACf,2BAA2B,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAC3E;SACA,IAAI,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC;AAUD;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,iBAAiB,CAAC,IAAY;IAC5C,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,SAAS,EAAE,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;IAC/E,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC9F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,SAAS,EAAE,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;IAChD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-ui",
-  "version": "3.2.34",
+  "version": "3.3.0-alpha.2",
   "description": "Sungen UI capability (Playwright) — step patterns, viewpoint gate, and phase hooks. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -8,16 +8,20 @@
     "capability": "ui"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json"
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "prepack": "npm run build"
   },
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.34"
+    "@sun-asterisk/sungen": "3.3.0-alpha.2"
   },
   "peerDependencies": {
     "@playwright/test": "^1.57.0"
   },
+  "devDependencies": {
+    "@playwright/test": "1.63.0"
+  },
   "files": [
     "dist",
     "src"

package/src/index.ts

@@ -47,6 +47,10 @@ export interface UiGateInput {
   viewpoints: ViewpointEntry[];
   catalog: Catalog;
   focus: Parameters<typeof assertionDepth>[2];
+  /** `platform: mobile` — makes `mobile-*` page types candidates (#864). */
+  isMobile?: boolean;
+  /** The viewpoint text, so a declared `page-type:` wins over keyword detection (#864). */
+  viewpointText?: string;
 }
 export interface UiGateResult {
   gate: GateResult;
@@ -58,7 +62,7 @@ export interface UiGateResult {
  * functions verbatim, so the produced gate/depth (and therefore the score) are byte-identical.
  */
 const uiGateProvider = (input: UiGateInput): UiGateResult => {
-  const gate = viewpointGate(input.scenarios, input.viewpoints, input.catalog);
+  const gate = viewpointGate(input.scenarios, input.viewpoints, input.catalog, input.isMobile ?? false, input.viewpointText ?? '');
   const depth = assertionDepth(input.scenarios, dataThemesFor(input.catalog, gate.pageType), input.focus);
   return { gate, depth };
 };
@@ -121,6 +125,11 @@ export function register(registry: CapabilityRegistry): void {
     gateProvider: uiGateProvider as (i: unknown) => unknown, // viewpoint coverage + depth
     sensors: [uiViewpointGateSensor],
     appProfilePresets: APP_PROFILE_PRESETS, // qa/app.yaml `extends: native|radix|antd`
+    // Trace target identity (SPI §4.5, DOS-14.5) — required on first use, so registering the UI
+    // capability never loads Playwright. A typed `require`, not `import()`: under the tsx-run CLI a
+    // dynamic import is real ESM and cannot resolve an extension-less TypeScript path.
+    traceIdentity: (input) =>
+      (require('./trace-identity/playwright-identity-resolver') as typeof import('./trace-identity/playwright-identity-resolver')).resolveTraceIdentities(input),
   });
 }
 

package/src/trace-identity/aria-snapshot-head.ts

@@ -0,0 +1,33 @@
+/**
+ * The head line of a Playwright `locator.ariaSnapshot()` → role, accessible name, heading level.
+ *
+ * Owned here on purpose (G5): the spike loaded Playwright's private aria-YAML parser by absolute
+ * path, which breaks on any internal move. We only ever need the FIRST node of a single element's
+ * snapshot, whose grammar is small and documented in Playwright's aria snapshot docs:
+ *
+ *   - button "Login"
+ *   - heading "My Account" [level=1]
+ *   - textbox "Email": test@playground.dev      (a value after the colon)
+ *   - link "Products":                           (children on the next lines)
+ *   - text: Hi, Jane                             (a bare text node — no role)
+ *
+ * More than one top-level node (a fragment) has no single identity.
+ */
+export interface AriaHead { role: string; name: string; level?: number; note?: string }
+
+const LINE = /^- ([a-zA-Z]+)(?: "((?:[^"\\]|\\.)*)")?((?: \[[^\]]*\])*)(?::.*)?$/;
+
+function unescape(raw: string): string {
+  try { return JSON.parse(`"${raw}"`) as string; } catch { return raw.replace(/\\"/g, '"'); }
+}
+
+export function parseAriaHead(yaml: string): AriaHead {
+  const top = yaml.split(/\r?\n/).filter((l) => l.startsWith('- '));
+  if (top.length !== 1) return { role: 'generic', name: '', note: `fragment of ${top.length}` };
+  const m = LINE.exec(top[0].trimEnd());
+  if (!m) return { role: 'generic', name: '', note: `unparsed: ${top[0].slice(0, 60)}` };
+  const role = m[1];
+  if (role === 'text') return { role: 'text', name: '', note: 'text node' };
+  const level = /\[level=(\d)\]/.exec(m[3] ?? '')?.[1];
+  return { role, name: m[2] === undefined ? '' : unescape(m[2]), ...(level ? { level: Number(level) } : {}) };
+}

package/src/trace-identity/playwright-identity-resolver.ts

@@ -0,0 +1,123 @@
+/**
+ * `traceIdentity` for the UI capability (SPI §4.5, DOS-14.5): who a recorded action was aimed at,
+ * from Playwright's OWN accessibility engine on the replayed snapshot — the phase 07 method that
+ * agreed with the test's locator on 98/98 oracle-bearing actions over two real sites.
+ *
+ *   replay     the inert HTML core rendered, in a context with JavaScript disabled, offline,
+ *              service workers blocked, every request routed to abort AND Chromium's network
+ *              blocklist set to `*` (non-http schemes too) — nothing leaves the machine
+ *   identity   role + name from `ariaSnapshot()` of the element Playwright marked, re-resolved with
+ *              `getByRole(role, { name, exact })`: it must land on exactly that element
+ *   G3         if role+name matches several elements, look for a named scope (row, landmark,
+ *              dialog, card…) inside which it is unique; none → `low` (ambiguous)
+ *   low        any reason at all: core's caps (missing CSS, broken refs), no semantic role, empty
+ *              name, getByRole missing the target, ambiguity, a failed snapshot
+ * A missing browser is an ERROR, never a silent `low` for everything.
+ */
+import { chromium, type Browser, type Locator, type Page } from '@playwright/test';
+import type { CapabilityDescriptor } from '@sun-asterisk/sungen';
+import { parseAriaHead } from './aria-snapshot-head';
+
+type Resolver = NonNullable<CapabilityDescriptor['traceIdentity']>;
+type Input = Parameters<Resolver>[0];
+type Output = Awaited<ReturnType<Resolver>>;
+type Result = Output['results'][number];
+
+const NAMELESS = new Set(['generic', 'none', 'presentation', 'text', 'fragment', 'paragraph']);
+const SCOPE_ROLES = ['row', 'listitem', 'article', 'dialog', 'alertdialog', 'form', 'group', 'tabpanel', 'region', 'navigation', 'complementary', 'search', 'banner', 'contentinfo', 'main', 'menu', 'list', 'table', 'grid'];
+
+export const RESOLVER_ID = 'driver-ui/playwright-aria@1';
+
+/** At most this many snapshots per call — a bound on work, not a sampling. */
+export const MAX_REQUESTS = 2000;
+
+async function launch(): Promise<Browser> {
+  try { return await chromium.launch({ headless: true }); } catch (e) {
+    throw new Error(`trace identity needs Chromium for Playwright — run \`npx playwright install chromium\` (${(e as Error).message.split('\n')[0]})`);
+  }
+}
+
+/** A fresh page in a fresh isolated context: JS off, offline, SW blocked, every request aborted, CDP blocklist `*`. */
+async function isolatedPage(browser: Browser, counter: { blocked: number }): Promise<Page> {
+  const context = await browser.newContext({ javaScriptEnabled: false, offline: true, serviceWorkers: 'block' });
+  await context.route('**/*', (route) => route.abort('blockedbyclient'));
+  const page = await context.newPage();
+  page.on('request', () => { counter.blocked++; });
+  const cdp = await context.newCDPSession(page);
+  await cdp.send('Network.enable');
+  await cdp.send('Network.setBlockedURLs', { urls: ['*'] });
+  return page;
+}
+
+const byRole = (root: Page | Locator, role: string, name: string, level?: number): Locator =>
+  root.getByRole(role as Parameters<Page['getByRole']>[0], { ...(name ? { name, exact: true } : {}), ...(level ? { level } : {}) });
+
+/** A named container in which role+name is unique and lands on the target (G3). */
+async function scopeFor(page: Page, target: Locator, role: string, name: string, level?: number): Promise<Result['scope'] | undefined> {
+  for (const scopeRole of SCOPE_ROLES) {
+    const holders = byRole(page, scopeRole, '').filter({ has: target });
+    const n = await holders.count();
+    if (!n) continue;
+    const head = parseAriaHead((await holders.nth(n - 1).ariaSnapshot({ timeout: 3_000 }).catch(() => '')).split('\n')[0]);
+    if (!head.name) continue;
+    const scoped = byRole(byRole(page, scopeRole, head.name), role, name, level);
+    if ((await scoped.count()) === 1 && (await scoped.and(target).count()) === 1) return { role: scopeRole, name: head.name };
+  }
+  return undefined;
+}
+
+const lowResult = (key: string, reasons: string[]): Result => ({ key, role: 'generic', name: '', identityConfidence: 'low', reasons });
+
+async function identify(page: Page, req: Input['requests'][number]): Promise<Result> {
+  const low = (reasons: string[]): Result => lowResult(req.key, reasons);
+  await page.setViewportSize({ width: Math.max(1, req.viewport.width), height: Math.max(1, req.viewport.height) });
+  await page.setContent(req.html, { waitUntil: 'domcontentloaded', timeout: 10_000 });
+  const target = page.locator(req.targetSelector);
+  const marked = await target.count();
+  if (marked !== 1) return low([...req.capReasons, `marked-elements=${marked}`]);
+  let aria: string;
+  try { aria = await target.ariaSnapshot({ timeout: 3_000 }); } catch (e) { return low([...req.capReasons, `ariaSnapshot-failed: ${(e as Error).message.split('\n')[0]}`]); }
+  const head = parseAriaHead(aria);
+  const id = { role: head.role, name: head.name, ...(head.level ? { level: head.level } : {}) };
+  const reasons = [...req.capReasons];
+  if (NAMELESS.has(head.role)) reasons.push(`no-semantic-role(${head.role})`);
+  if (!head.name) reasons.push('empty-name');
+  let scope: Result['scope'];
+  if (!NAMELESS.has(head.role)) {
+    const all = byRole(page, head.role, head.name, head.level);
+    const count = await all.count();
+    if ((await all.and(target).count()) !== 1) reasons.push('getByRole-misses-target');
+    else if (count > 1) {
+      scope = head.name ? await scopeFor(page, target, head.role, head.name, head.level) : undefined;
+      if (!scope) reasons.push(`ambiguous(${count})`);
+    }
+  }
+  return reasons.length ? { key: req.key, ...id, identityConfidence: 'low', reasons } : { key: req.key, ...id, ...(scope ? { scope } : {}), identityConfidence: 'high', reasons: [] };
+}
+
+export async function resolveTraceIdentities(input: Input): Promise<Output> {
+  const requests = Array.isArray(input?.requests) ? input.requests : [];
+  if (requests.length > MAX_REQUESTS) throw new Error(`trace identity: ${requests.length} snapshots in one call (max ${MAX_REQUESTS})`);
+  const browser = await launch();
+  try {
+    const counter = { blocked: 0 };
+    let page = await isolatedPage(browser, counter);
+    const results: Result[] = [];
+    for (const req of requests) {
+      try {
+        results.push(await identify(page, req));
+      } catch (e) {
+        // One bad snapshot is a `low` answer for that snapshot, never a crash of the whole check.
+        const why = (e as Error).message.split('\n')[0].slice(0, 200);
+        results.push(lowResult(req.key, [`replay-failed: ${why}`]));
+        if (page.isClosed() || /closed/i.test(why)) {
+          await page.context().close().catch(() => undefined);
+          page = await isolatedPage(browser, counter);
+        }
+      }
+    }
+    return { resolver: RESOLVER_ID, browser: `chromium ${browser.version()}`, results, blockedRequests: counter.blocked };
+  } finally {
+    await browser.close();
+  }
+}

package/src/trace-identity/trace-run-record-reporter.ts

@@ -0,0 +1,105 @@
+/**
+ * Playwright reporter that records sungen's own RUN RECORD for trace conformance (DOS-14.6, G5).
+ *
+ * A Playwright trace carries no run id and no hash of the code that produced it, so a good trace of
+ * another test — or of the same test before the code was weakened — could be swapped in. This
+ * reporter writes, next to the traces it vouches for (`<outputDir>/sungen-run-record[.shard-i-of-n].json`):
+ *
+ *   runId        SUNGEN_RUN_ID when set (one id across CI shards), else a fresh UUID
+ *   specs        sha256 of every test file at run START (the code that ran)
+ *   attempts     per test attempt: testId, retry, status, window, and the sha256 of its trace.zip
+ *   report       where the JSON reporter wrote its report — traces are mapped THROUGH that report
+ *                (merge-reports renames trace files; their content, and so the sha256, stays)
+ *
+ * The outputDir is wiped at the start of every Playwright run, so a record and its traces always
+ * come from the same run. Enable it for free / impl:code tests together with `trace: 'on'`, in a
+ * config with its OWN outputDir — the compiled suite clears `test-results/` on every run (#941):
+ *
+ *   outputDir: 'test-results-free',
+ *   reporter: [['json', { outputFile: 'test-results-free/results.json' }],
+ *              ['@sungen/driver-ui/dist/trace-identity/trace-run-record-reporter.js']],
+ *   (the compiled file — Playwright does not transpile TypeScript inside node_modules; `prepack` builds it)
+ *   use: { trace: 'on' },
+ */
+import type { FullConfig, Reporter, Suite, TestCase, TestResult } from '@playwright/test/reporter';
+import { createHash, randomUUID } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+interface AttemptRecord {
+  testId: string; file: string; title: string; retry: number; status: string;
+  startTime: string; duration: number; trace: { sha256: string } | null;
+}
+
+const sha256File = (file: string): string | null => {
+  try { return createHash('sha256').update(fs.readFileSync(file)).digest('hex'); } catch { return null; }
+};
+const posix = (p: string): string => p.split(path.sep).join('/');
+
+class TraceRunRecordReporter implements Reporter {
+  private config?: FullConfig;
+  private root = process.cwd();
+  private runId = process.env.SUNGEN_RUN_ID || randomUUID();
+  private startedAt = new Date().toISOString();
+  private specs: Record<string, string> = {};
+  private results: Array<{ test: TestCase; result: TestResult }> = [];
+
+  printsToStdio(): boolean { return false; }
+
+  onBegin(config: FullConfig, suite: Suite): void {
+    this.config = config;
+    if (config.configFile) this.root = path.dirname(config.configFile);
+    for (const test of suite.allTests()) {
+      const rel = this.rel(test.location.file);
+      if (this.specs[rel] === undefined) this.specs[rel] = sha256File(test.location.file) ?? '';
+    }
+  }
+
+  onTestEnd(test: TestCase, result: TestResult): void {
+    this.results.push({ test, result });
+  }
+
+  async onEnd(): Promise<void> {
+    if (!this.config) return;
+    const attempts: AttemptRecord[] = this.results.map(({ test, result }) => {
+      const trace = result.attachments.find((a) => a.name === 'trace' && a.path);
+      const sha = trace?.path ? sha256File(trace.path) : null;
+      return {
+        testId: test.id, file: this.rel(test.location.file), title: test.title, retry: result.retry, status: result.status,
+        startTime: result.startTime.toISOString(), duration: result.duration, trace: sha ? { sha256: sha } : null,
+      };
+    });
+    const shard = this.config.shard;
+    const record = {
+      schema: 1, tool: 'sungen-trace-run-record', runId: this.runId, startedAt: this.startedAt,
+      playwrightVersion: this.config.version, shard: shard ? `${shard.current}/${shard.total}` : null,
+      report: this.jsonReportPath(), specs: this.specs, attempts,
+    };
+    const outDir = this.config.projects[0]?.outputDir ?? path.join(this.root, 'test-results');
+    const name = shard ? `sungen-run-record.shard-${shard.current}-of-${shard.total}.json` : 'sungen-run-record.json';
+    try {
+      fs.mkdirSync(outDir, { recursive: true });
+      fs.writeFileSync(path.join(outDir, name), JSON.stringify(record, null, 2));
+    } catch (e) {
+      // A missing record makes every free / impl:code test `unproven` — say so instead of hiding it.
+      console.error(`[sungen] could not write the trace run record: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+
+  /** The JSON reporter's output file, as the reporter itself resolves it (option, then env). */
+  private jsonReportPath(): string | null {
+    const json = this.config?.reporter.find(([name]) => name === 'json');
+    const opt = json && typeof (json[1] as { outputFile?: unknown })?.outputFile === 'string' ? (json[1] as { outputFile: string }).outputFile : undefined;
+    const fromEnv = process.env.PLAYWRIGHT_JSON_OUTPUT_FILE
+      ?? (process.env.PLAYWRIGHT_JSON_OUTPUT_NAME ? path.join(process.env.PLAYWRIGHT_JSON_OUTPUT_DIR ?? '', process.env.PLAYWRIGHT_JSON_OUTPUT_NAME) : undefined);
+    const chosen = opt ? path.resolve(this.root, opt) : fromEnv ? path.resolve(process.cwd(), fromEnv) : undefined;
+    return chosen ? this.rel(chosen) : null;
+  }
+
+  private rel(file: string): string {
+    const r = path.relative(this.root, file);
+    return posix(r.startsWith('..') || path.isAbsolute(r) ? path.basename(file) : r);
+  }
+}
+
+export default TraceRunRecordReporter;