@sun-asterisk/sungen 3.2.5 → 3.2.6

package/src/exporters/json-exporter.ts

@@ -22,6 +22,7 @@ import {
 } from './playwright-report-parser';
 import { EnvironmentInfo, PlaywrightResult } from './types';
 import { SelectorKeyMap, substituteSelectorKeysInStep } from './selector-key-resolver';
+import { resolveResultVariants } from './result-variants';
 import {
   ScenarioSnapshot,
   ScreenSnapshot,
@@ -62,11 +63,6 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
   let fallbackIndex = 1;
 
   for (const m of input.merged) {
-    const { vpId, category1 } = splitVpAndName(m.feature.name);
-    const tcId = generateTcId(input.screen, vpId, fallbackIndex);
-    if (!vpId) fallbackIndex++;
-
-    const category2 = mapVpToCategory2(vpId, category1);
     const priority = extractPriority(m.feature.tags) as ScenarioSnapshot['priority'];
     const baseType = extractTestcaseType(m.feature.tags);
     const authRole = extractAuthRole(m.feature.tags);
@@ -87,27 +83,32 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
     // key/value per line instead of the CSV-friendly "; " join.
     const testDataStr = formatTestData(m.feature.referencedVars, input.testData, Infinity, '\n');
 
-    let result: PlaywrightResult | undefined;
-    if (input.results && m.spec) {
-      result = input.results.get(m.spec.testTitle);
-    }
+    // @cases scenarios expand to one snapshot entry per executed dataset row (shared with the CSV
+    // exporter via resolveResultVariants), so their per-row pass/fail is counted — not collapsed
+    // into one Pending/N/A entry as before.
+    const variants = resolveResultVariants(m, input.results ?? null);
+    for (const variant of variants) {
+      const displayName = `${m.feature.name}${variant.nameSuffix}`;
+      const { vpId, category1 } = splitVpAndName(displayName);
+      const tcId = generateTcId(input.screen, vpId, fallbackIndex);
+      if (!vpId) fallbackIndex++;
+      const category2 = mapVpToCategory2(vpId, category1);
+      const result = variant.result;
 
-    let status: ScenarioSnapshot['status'];
-    let executedDate: string | undefined;
-    let errorMessage: string | undefined;
-    let tracePath: string | undefined;
-    let testEnvironment: string | undefined;
-    let testExecutor: string | undefined;
-    let type: ScenarioSnapshot['type'];
+      let status: ScenarioSnapshot['status'];
+      let executedDate: string | undefined;
+      let errorMessage: string | undefined;
+      let tracePath: string | undefined;
+      let testEnvironment: string | undefined;
+      let testExecutor: string | undefined;
+      let type: ScenarioSnapshot['type'];
 
-    if (!m.spec) {
-      type = baseType === 'Manual' ? 'Manual' : 'Not compiled';
-      status = baseType === 'Manual' ? 'Pending' : 'N/A';
-    } else {
-      type = baseType;
-      if (!result) {
-        status = 'Pending';
-      } else {
+      if (result) {
+        // A result exists → the scenario compiled AND ran; authoritative over the `!m.spec`
+        // "not compiled" heuristic. A @cases test title carries a `— <label>` suffix, so
+        // findMatchingSpecTest (base-name match) often leaves m.spec null even though rows ran —
+        // without checking `result` first, those passed/failed rows were mislabelled N/A / Pending.
+        type = baseType;
         status = statusToTestResult(result.status) as ScenarioSnapshot['status'];
         executedDate = formatExecutedDate(result.startTime);
         if (result.error) {
@@ -126,31 +127,39 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
         if (result.tracePath) tracePath = result.tracePath;
         testEnvironment = formatTestEnvironment(input.env.baseURL, input.featurePath, result.projectName || input.env.projectName);
         testExecutor = input.env.executor;
+      } else if (!m.spec) {
+        // No result AND no compiled test → Manual if @manual, else genuinely not compiled.
+        type = baseType === 'Manual' ? 'Manual' : 'Not compiled';
+        status = baseType === 'Manual' ? 'Pending' : 'N/A';
+      } else {
+        // Compiled but no execution record → Pending.
+        type = baseType;
+        status = 'Pending';
       }
-    }
 
-    scenarios.push({
-      tcId,
-      category1,
-      category2,
-      category3: input.featureName,
-      category4: input.screen,
-      featureBaseName: input.featureBaseName ?? input.screen,
-      vpId,
-      priority,
-      type,
-      status,
-      tags: m.feature.tags,
-      precondition,
-      testData: testDataStr,
-      steps,
-      expectedResults,
-      executedDate,
-      errorMessage,
-      tracePath,
-      testEnvironment,
-      testExecutor,
-    });
+      scenarios.push({
+        tcId,
+        category1,
+        category2,
+        category3: input.featureName,
+        category4: input.screen,
+        featureBaseName: input.featureBaseName ?? input.screen,
+        vpId,
+        priority,
+        type,
+        status,
+        tags: m.feature.tags,
+        precondition,
+        testData: testDataStr,
+        steps,
+        expectedResults,
+        executedDate,
+        errorMessage,
+        tracePath,
+        testEnvironment,
+        testExecutor,
+      });
+    }
   }
 
   return {

package/src/exporters/result-variants.ts

@@ -0,0 +1,47 @@
+/**
+ * Result-variant resolution — the single seam the CSV (delivery) and JSON (dashboard) exporters
+ * share so they can never drift on @cases handling again (they did: the dashboard mislabelled
+ * every @cases row while delivery expanded them).
+ */
+import { MergedScenario } from './scenario-merger';
+import { PlaywrightResult } from './types';
+
+export interface ResultVariant {
+  /** Appended to the scenario display name: `''` for a plain scenario, ` — <label>` per executed
+   *  @cases dataset row (so each row gets a distinct category1). */
+  nameSuffix: string;
+  result?: PlaywrightResult;
+}
+
+/**
+ * Resolve the execution-result variant(s) for a merged scenario.
+ *
+ * A `@cases:<dataset>` scenario compiles to one `test()` per dataset row, whose Playwright title is
+ * `<scenario> — <label>` — expand into one variant per EXECUTED row by matching that prefix (so an
+ * already-run row carries its real pass/fail). A plain scenario resolves its single result by the
+ * spec test title. With no results — or a @cases scenario with no matching result yet — a lone
+ * variant with no result is returned, so the caller marks it Pending / N/A.
+ *
+ * NOTE: this deliberately does NOT gate on `m.spec`. For @cases the compiled test title carries a
+ * `— ${__row.__label}` suffix, so `findMatchingSpecTest` (base-name match) often leaves `m.spec`
+ * null even though the rows ran; the marker match still finds their results. Callers must let a
+ * present `result` win over the "not compiled" (`!m.spec`) heuristic.
+ */
+export function resolveResultVariants(
+  m: MergedScenario,
+  results: Map<string, PlaywrightResult> | null,
+): ResultVariant[] {
+  const isCases = m.feature.tags.some((t) => t.startsWith('@cases:'));
+  if (isCases && results) {
+    const marker = `${m.feature.name} — `;
+    const rows = [...results.entries()].filter(([t]) => t.includes(marker));
+    if (rows.length) {
+      return rows.map(([t, r]) => ({ nameSuffix: ` — ${t.slice(t.indexOf(marker) + marker.length)}`, result: r }));
+    }
+    return [{ nameSuffix: '' }];
+  }
+  if (results && m.spec) {
+    return [{ nameSuffix: '', result: results.get(m.spec.testTitle) }];
+  }
+  return [{ nameSuffix: '' }];
+}

package/src/exporters/xlsx-exporter.ts

@@ -267,11 +267,29 @@ function addOverviewSheet(wb: ExcelJS.Workbook, sheets: LocaleSheet[]): void {
     });
   };
 
+  // Each detail sheet carries a LIVE summary band (row 7): C7 Total · D7 Passed · E7 Failed ·
+  // F7 Pending · G7 N/A · H7 Remaining, all COUNTA/COUNTIF over the data area. The Overview
+  // REFERENCES those cells (`='<sheet>'!D7`) instead of freezing a number at export time — so when
+  // QA adds/edits/removes a row in the Auto or Manual sheet, the roll-up recomputes automatically.
+  const qname = (name: string): string => name.replace(/'/g, "''"); // Excel escapes ' by doubling
+  const ref = (name: string, cell: string, result: number): ExcelJS.CellFormulaValue =>
+    ({ formula: `'${qname(name)}'!${cell}`, result });
+
   let rowIdx = HEADER_ROW + 1;
+  const firstDataRow = rowIdx;
   sheets.forEach((s, i) => {
     const su = s.summary;
     const remain = Math.max(0, su.total - su.passed - su.na);
-    writeDataRow(rowIdx, [i + 1, s.sheetName, su.passed, su.failed, su.pending, su.na, remain, su.total], false);
+    writeDataRow(rowIdx, [
+      i + 1,
+      s.sheetName,
+      ref(s.sheetName, 'D7', su.passed),
+      ref(s.sheetName, 'E7', su.failed),
+      ref(s.sheetName, 'F7', su.pending),
+      ref(s.sheetName, 'G7', su.na),
+      ref(s.sheetName, 'H7', remain),
+      ref(s.sheetName, 'C7', su.total),
+    ], false);
     totals.passed += su.passed;
     totals.failed += su.failed;
     totals.pending += su.pending;
@@ -280,10 +298,23 @@ function addOverviewSheet(wb: ExcelJS.Workbook, sheets: LocaleSheet[]): void {
     totals.total += su.total;
     rowIdx += 1;
   });
+  const lastDataRow = rowIdx - 1;
 
+  // Grand total = SUM of the per-sheet Overview cells (also live — recomputes with the references
+  // above). Overview count columns are D..I (Passed·Failed·Pending·N/A·Remain·Total).
+  const sumCol = (col: string, result: number): ExcelJS.CellFormulaValue =>
+    ({ formula: `SUM(${col}${firstDataRow}:${col}${lastDataRow})`, result });
   writeDataRow(
     rowIdx,
-    ['', 'Total', totals.passed, totals.failed, totals.pending, totals.na, totals.remain, totals.total],
+    [
+      '', 'Total',
+      sumCol('D', totals.passed),
+      sumCol('E', totals.failed),
+      sumCol('F', totals.pending),
+      sumCol('G', totals.na),
+      sumCol('H', totals.remain),
+      sumCol('I', totals.total),
+    ],
     true,
   );
 }
@@ -313,7 +344,7 @@ function addTestcaseSheet(
     { width: 17 },    // E — Test Object
     { width: 25.5 },  // F — Pre-condition
     { width: 24.88 }, // G — Test Data
-    { width: 24.88 }, // H — Steps
+    { width: 50 },    // H — Steps (widened ~2× — steps are the longest cell)
     { width: 41 },    // I — Expected results
     { width: 12 },    // J — Priority
     { width: 13.5 },  // K — Testcase type
@@ -346,16 +377,18 @@ function addTestcaseSheet(
   // No explicit height → Excel auto-fits this row's content.
 
   // -- Row 7: Counts (cols C..H), live formulas referencing the data area --
-  // Data table starts at row 15 (col header at row 14, divider at row 14? actually
-  // header at row 13 + divider at 14 + first data at 15). The formulas read col L
-  // (Test Result) for status counts, col A (TC ID) for total via COUNTA.
+  // The data region begins at row 14 — the row immediately AFTER the column-header row (row 13).
+  // Start the ranges there (NOT row 15): the first category divider usually sits at row 14 with a
+  // BLANK col A (so COUNTA skips it), but a sheet whose first row after the header is real data —
+  // no leading divider — would be UNDER-counted by a range that started at 15. Row 14 covers both.
+  const COUNT_RANGE_START = 14;
   const COUNT_RANGE_END = 10000;
   const r7Values: Record<string, ExcelJS.CellValue> = {
-    C: { formula: `COUNTA(A15:A${COUNT_RANGE_END})`, result: summary.total } as ExcelJS.CellFormulaValue,
-    D: { formula: `COUNTIF(L15:L${COUNT_RANGE_END},"Passed")`, result: summary.passed } as ExcelJS.CellFormulaValue,
-    E: { formula: `COUNTIF(L15:L${COUNT_RANGE_END},"Failed")`, result: summary.failed } as ExcelJS.CellFormulaValue,
-    F: { formula: `COUNTIF(L15:L${COUNT_RANGE_END},"Pending")`, result: summary.pending } as ExcelJS.CellFormulaValue,
-    G: { formula: `COUNTIF(L15:L${COUNT_RANGE_END},"N/A")`, result: summary.na } as ExcelJS.CellFormulaValue,
+    C: { formula: `COUNTA(A${COUNT_RANGE_START}:A${COUNT_RANGE_END})`, result: summary.total } as ExcelJS.CellFormulaValue,
+    D: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"Passed")`, result: summary.passed } as ExcelJS.CellFormulaValue,
+    E: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"Failed")`, result: summary.failed } as ExcelJS.CellFormulaValue,
+    F: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"Pending")`, result: summary.pending } as ExcelJS.CellFormulaValue,
+    G: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"N/A")`, result: summary.na } as ExcelJS.CellFormulaValue,
     H: { formula: 'C7-D7-G7', result: summary.failed + summary.pending } as ExcelJS.CellFormulaValue,
   };
   for (const [col, val] of Object.entries(r7Values)) {
@@ -435,8 +468,10 @@ function addTestcaseSheet(
     applyBorder(cell);
   });
 
-  // Freeze everything above and below the header row — reveal header when scrolling.
-  ws.views = [{ state: 'frozen', ySplit: headerRow.number }];
+  // No freeze — the whole sheet scrolls freely (the masthead + summary band + header scroll away
+  // with the data). QA asked for this so the wide Steps/Expected columns aren't pinned under a frozen
+  // header on smaller screens.
+  ws.views = [{ state: 'normal' }];
 
   // -- Data rows grouped by category --
   const order = ['Accessing', 'GUI', 'Function'];

package/src/generators/test-generator/adapters/appium/templates/scenario.hbs

@@ -1,4 +1,4 @@
-  it('{{scenarioName}}', async () => {
+  it('{{escapeQuotes scenarioName}}', async () => {
 {{#each steps}}
 {{#if comment}}
     // {{comment}}

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

@@ -1,9 +1,9 @@
 {{#if casesDataset}}
   for (const __row of testData.cases('{{casesDataset}}')) {
 {{#if tags}}
-  test(`{{scenarioName}} — ${__row.__label}`, { tag: [{{{tags}}}] }, async ({{#if isParallel}}{ page }{{/if}}) => {
+  test('{{escapeQuotes scenarioName}} — ' + __row.__label, { tag: [{{{tags}}}] }, async ({{#if isParallel}}{ page }{{/if}}) => {
 {{else}}
-  test(`{{scenarioName}} — ${__row.__label}`, async ({{#if isParallel}}{ page }{{/if}}) => {
+  test('{{escapeQuotes scenarioName}} — ' + __row.__label, async ({{#if isParallel}}{ page }{{/if}}) => {
 {{/if}}
     const rowData = testData.withRow(__row);
 {{#each steps}}
@@ -17,9 +17,9 @@
 {{else}}
 {{#if isParallel}}
 {{#if tags}}
-  test('{{scenarioName}}', { tag: [{{{tags}}}] }, async ({ page }) => {
+  test('{{escapeQuotes scenarioName}}', { tag: [{{{tags}}}] }, async ({ page }) => {
 {{else}}
-  test('{{scenarioName}}', async ({ page }) => {
+  test('{{escapeQuotes scenarioName}}', async ({ page }) => {
 {{/if}}
 {{#each steps}}
 {{#if comment}}
@@ -30,9 +30,9 @@
   });
 {{else}}
 {{#if tags}}
-  test('{{scenarioName}}', { tag: [{{{tags}}}] }, async () => {
+  test('{{escapeQuotes scenarioName}}', { tag: [{{{tags}}}] }, async () => {
 {{else}}
-  test('{{scenarioName}}', async () => {
+  test('{{escapeQuotes scenarioName}}', async () => {
 {{/if}}
 {{#each steps}}
 {{#if comment}}

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/expand-action.hbs

@@ -1,11 +1,33 @@
+{ const el = {{> locator}};
+{{#if expanded.state}}
+{{!-- Toggle-only: component exposes no observable expanded state → click without asserting. --}}
+await el.click();
+{{else if expanded.class}}
+{{!-- State signalled by a class on a descendant (e.g. an accordion chevron icon). --}}
 {{#if (eq direction 'expand')}}
-if (await {{> locator}}.getAttribute('aria-expanded') !== 'true') {
-  await {{> locator}}.click();
-}
-await expect({{> locator}}).toHaveAttribute('aria-expanded', 'true');
+if (!(await el.locator('.{{expanded.class}}').count())) { await el.click(); }
+await expect(el.locator('.{{expanded.class}}')).toBeVisible();
+{{else}}
+if (await el.locator('.{{expanded.class}}').count()) { await el.click(); }
+await expect(el.locator('.{{expanded.class}}')).toHaveCount(0);
+{{/if}}
+{{else if expanded.attribute}}
+{{!-- Explicit boolean attribute ('true'/'false'), custom or aria-expanded. --}}
+{{#if (eq direction 'expand')}}
+if (await el.getAttribute('{{expanded.attribute}}') !== 'true') { await el.click(); }
+await expect(el).toHaveAttribute('{{expanded.attribute}}', 'true');
+{{else}}
+if (await el.getAttribute('{{expanded.attribute}}') !== 'false') { await el.click(); }
+await expect(el).toHaveAttribute('{{expanded.attribute}}', 'false');
+{{/if}}
+{{else}}
+{{!-- Default (zero-config): drive by aria-expanded, but assert it ONLY when the element exposes it. --}}
+{{#if (eq direction 'expand')}}
+if (await el.getAttribute('aria-expanded') !== 'true') { await el.click(); }
+if (await el.getAttribute('aria-expanded') !== null) { await expect(el).toHaveAttribute('aria-expanded', 'true'); }
 {{else}}
-if (await {{> locator}}.getAttribute('aria-expanded') !== 'false') {
-  await {{> locator}}.click();
+if (await el.getAttribute('aria-expanded') !== 'false') { await el.click(); }
+if (await el.getAttribute('aria-expanded') !== null) { await expect(el).toHaveAttribute('aria-expanded', 'false'); }
+{{/if}}
+{{/if}}
 }
-await expect({{> locator}}).toHaveAttribute('aria-expanded', 'false');
-{{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/selected-assertion.hbs

@@ -1 +1,16 @@
-await expect({{> locator}}).toHaveAttribute('aria-selected', 'true');
+{{#if (or (eq role 'checkbox') (eq role 'radio') (eq role 'switch'))}}
+{{!-- Form control: "selected" is the checked state, never aria-selected. A native checkbox/radio
+     exposes no aria-selected attribute — its state lives in the `checked` property. --}}
+await expect({{> locator}}).toBeChecked();
+{{else}}
+{{!-- Other/unknown role (tab, option, or a text/testid/css selector): probe at runtime. An ARIA
+     single-select widget exposes aria-selected → assert it; anything without it falls back to the
+     checked state. Never hardcode aria-selected — it breaks on native form controls. --}}
+{ const el = {{> locator}};
+if ((await el.getAttribute('aria-selected')) !== null) {
+await expect(el).toHaveAttribute('aria-selected', 'true');
+} else {
+await expect(el).toBeChecked();
+}
+}
+{{/if}}

package/src/generators/test-generator/patterns/expect-patterns.ts

@@ -17,6 +17,14 @@ import { MappedStep } from '../step-mapper';
 const VALUE = String.raw`\{\{[^}]+\}\}|"[^"]*"|'[^']*'|-?\d+(?:\.\d+)?`;
 const reExpect = new RegExp(`^\\s*(?:User\\s+)?expect\\s+(${VALUE})\\s+is\\s+(not\\s+|at\\s+least\\s+|at\\s+most\\s+)?(${VALUE})\\s*$`, 'i');
 
+/** `expect {{name.body}} matches schema [Ref]` — validate a bound API response body against a named
+ *  JSON Schema (from qa/api/schemas.yaml, populated by `sungen api import`). Requires the API Driver
+ *  (the scenario carries `@api:<name>`, so the `api` runtime helper is imported).
+ *  Two regexes: the MATCHER sees ref contents masked (`{{~}}`, `[~]` — see maskRefsForMatching); the
+ *  GENERATOR gets the ORIGINAL step text, so it extracts the real `[Ref]`. */
+const reMatchesSchemaMasked = /^\s*(?:User\s+)?expect\s+\{\{~\}\}\s+matches\s+schema\s+\[~\]\s*$/i;
+const reMatchesSchema = new RegExp(`^\\s*(?:User\\s+)?expect\\s+(\\{\\{[^}]+\\}\\})\\s+matches\\s+schema\\s+\\[([A-Za-z0-9_.-]+)\\]\\s*$`, 'i');
+
 /** Render a value token (`{{var}}` | "literal" | 'literal' | number) as a JS expression. */
 function valueExpr(token: string): string {
   const t = token.trim();
@@ -29,6 +37,21 @@ function valueExpr(token: string): string {
 }
 
 export const expectPatterns: StepPattern[] = [
+  {
+    name: 'expect-matches-schema',
+    priority: 63, // above expect-data; its regex needs `matches schema`, so no overlap
+    matcher: (step: ParsedStep) => reMatchesSchemaMasked.test(step.text),
+    generator: (step: ParsedStep, _ctx: PatternContext): MappedStep => {
+      // The masked matcher is looser than this extraction regex, so a malformed step (empty var/ref,
+      // odd chars) can claim the pattern yet not re-match here — emit a clear TODO instead of crashing.
+      const m = step.text.match(reMatchesSchema);
+      if (!m) return { code: `// TODO: malformed 'matches schema' step (expected: expect {{name.body}} matches schema [Ref]): ${step.text}`, comment: 'Unrecognized matches-schema step' };
+      const value = valueExpr(m[1]);
+      const ref = m[2];
+      const code = `{ const __schema = api.assertSchema(${value}, ${JSON.stringify(ref)}); expect(__schema.ok, \`matches schema [${ref}]: \${__schema.errors}\`).toBe(true); }`;
+      return { code, comment: `Expect ${m[1]} matches schema [${ref}]` };
+    },
+  },
   {
     name: 'expect-data',
     priority: 62, // above generic see-assertions; sibling of the DB assertions

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

@@ -39,6 +39,17 @@ interface SelectorEntry {
   // === v2: Assertion Helpers ===
   attribute?: string;     // Attribute to check (for "has" assertions)
   pattern?: string;       // Regex for attribute value
+
+  // === Expand/collapse state signal ===
+  // How the open/closed state of an expandable element is observed. Many accordions expose no
+  // `aria-expanded` (state shows only via an icon class swap), so hardcoding it makes the assertion
+  // time out. When omitted, codegen drives by aria-expanded but asserts it ONLY if present — a safe
+  // zero-config fallback. Provide one of these to verify a non-aria component explicitly.
+  expanded?: {
+    class?: string;       // class present on a descendant when open (e.g. 'mdi-chevron-up')
+    attribute?: string;   // boolean attribute ('true'/'false') on the toggle element
+    state?: 'none';       // no observable state → toggle-click only, skip the assertion
+  };
 }
 
 // New selector file structure: flat key-value pairs
@@ -64,6 +75,12 @@ export interface ResolvedSelector {
   strategy: 'testid' | 'id' | 'placeholder' | 'label' | 'text' | 'css' | 'role' | 'locator'
     | 'accessibility-id' | 'xpath' | 'android-uiautomator' | 'ios-predicate';
   value: string;
+  // Original YAML `type:` of the matched entry (before it collapses into a `strategy`). Callers
+  // that assign meaning to the entry kind — e.g. page assertions, whose `value` is a URL ONLY when
+  // the entry is a `page` selector — must verify this instead of trusting a key match. A key can
+  // collide across types (one `読取結果一覧` entry, type `role`, reused for a page assertion), so a
+  // key-only lookup can hand back an entry whose `value` ('button') is meaningless as a URL.
+  selectorType?: SelectorType;
   // Mobile per-platform variant (`android:`/`ios:` in selectors.yaml). When set, the appium codegen
   // emits a runtime `driver.isIOS ? '<ios>' : '<android>'` so one @platform:mobile spec resolves the
   // right native selector per OS. Each side carries its own strategy+value (issue #392).
@@ -87,6 +104,7 @@ export interface ResolvedSelector {
   pagination?: Record<string, string>;
   attribute?: string;   // Attribute to check
   pattern?: string;     // Regex for attribute value
+  expanded?: { class?: string; attribute?: string; state?: 'none' };  // Expand/collapse state signal
 }
 
 /**
@@ -460,8 +478,14 @@ export class SelectorResolver {
     const type = entry.type || 'placeholder';
     // Check if value exists in entry (even if empty string), use it; otherwise use originalLabel
     const rawValue = entry.value !== undefined && entry.value !== null ? entry.value : originalLabel;
-    // Check if name exists in entry (even if empty string), use it; otherwise use originalLabel
-    const rawName = entry.name !== undefined && entry.name !== null ? entry.name : originalLabel;
+    // Name resolution has three cases:
+    //   - key absent (undefined)      → fall back to originalLabel (the [Reference] text)
+    //   - explicit null / empty string → disable the name filter entirely (rawName = '')
+    //   - a real string               → use it verbatim
+    // Explicit `name: null` in YAML is a deliberate opt-out (e.g. a role selector that must NOT
+    // filter by accessible name); it must not be conflated with "unset". The role template omits
+    // `{ name }` when this resolves to a falsy value.
+    const rawName = entry.name === undefined ? originalLabel : (entry.name ?? '');
     const value = SelectorResolver.resolveTemplateVars(rawValue);
     const name = SelectorResolver.resolveTemplateVars(rawName);
     const nth = entry.nth !== undefined && entry.nth !== null ? entry.nth : undefined;
@@ -480,10 +504,14 @@ export class SelectorResolver {
     if (entry.pagination) v2Fields.pagination = entry.pagination;
     if (entry.attribute) v2Fields.attribute = entry.attribute;
     if (entry.pattern) v2Fields.pattern = entry.pattern;
+    if (entry.expanded) v2Fields.expanded = entry.expanded;
 
     // Helper to attach v2 fields and inputMethod
     const withExtras = (resolved: ResolvedSelector): ResolvedSelector => {
       if (inputMethod) resolved.inputMethod = inputMethod;
+      // Preserve the entry's original YAML type so callers can verify the entry kind (a key match
+      // alone does not guarantee the entry means what the step expects — see ResolvedSelector.selectorType).
+      resolved.selectorType = type;
       return { ...resolved, ...v2Fields };
     };
 

package/src/orchestrator/project-initializer.ts

@@ -4,6 +4,7 @@
  */
 
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { execSync } from 'child_process';
 import { buildOutputs } from './ai-skills/build';
@@ -47,18 +48,53 @@ export function mergeCodexMcpToml(existing: string, mobileOnly: boolean): string
   const serverKey = mobileOnly ? 'appium-mcp' : 'playwright';
   // Already configured (by the user or a previous run) → preserve, do nothing.
   if (new RegExp(String.raw`^\s*\[mcp_servers\.(?:"?${serverKey}"?)\]`, 'm').test(existing)) return null;
+  // startup_timeout_sec: Codex's default is 10s, which `npx <pkg>@latest` blows past on a cold
+  // cache (it downloads the package first) — the server then "fails to start" and Codex drops it.
+  // default_tools_approval_mode: Codex gates every MCP tool call behind an approval elicitation;
+  // non-interactive runs (`codex exec`, full-auto) auto-CANCEL it — "user cancelled MCP tool call"
+  // — so run-test could never drive the browser headlessly. Auto-approve is scoped to this server
+  // only and the whole file already requires project trust.
+  const serverOpts = 'startup_timeout_sec = 120\ndefault_tools_approval_mode = "approve"\n';
   const block = mobileOnly
-    ? '[mcp_servers.appium-mcp]\ncommand = "npx"\nargs = ["-y", "appium-mcp"]\n'
-    : '[mcp_servers.playwright]\ncommand = "npx"\nargs = ["@playwright/mcp@latest"]\n';
+    ? `[mcp_servers.appium-mcp]\ncommand = "npx"\nargs = ["-y", "appium-mcp"]\n${serverOpts}`
+    : `[mcp_servers.playwright]\ncommand = "npx"\nargs = ["@playwright/mcp@latest"]\n${serverOpts}`;
   if (existing.trim() === '') return CODEX_MCP_HEADER + block;
   return existing + (existing.endsWith('\n') ? '\n' : '\n\n') + block;
 }
 
+/**
+ * Whether the user's global Codex config (`~/.codex/config.toml`) marks `projectDir` trusted.
+ * Codex loads a project `.codex/config.toml` ONLY for trusted projects and skips it SILENTLY
+ * otherwise — the #1 "Codex doesn't see the Playwright MCP server" failure — so init checks and
+ * warns instead of leaving the user with a config that never loads. Pure string scan (no toml dep).
+ */
+export function codexTrustsProject(configText: string, projectDir: string): boolean {
+  let currentProject: string | null = null;
+  const trusted: string[] = [];
+  for (const line of configText.split('\n')) {
+    const header = line.match(/^\s*\[(.+)\]\s*$/);
+    if (header) {
+      const m = header[1].trim().match(/^projects\.(?:"(.+)"|'(.+)'|(.+))$/);
+      currentProject = m ? (m[1] ?? m[2] ?? m[3]) : null;
+      continue;
+    }
+    if (currentProject && /^\s*trust_level\s*=\s*"trusted"\s*$/.test(line)) trusted.push(currentProject);
+  }
+  // Codex resolves the project by walking UP from cwd (git root / trusted ancestor), so a dir
+  // nested inside a trusted project is itself trusted — verified live: `codex mcp list` inside
+  // examples/<new>/ loads its .codex/config.toml with only the repo root in the trust list.
+  return trusted.some(
+    (dir) => projectDir === dir || projectDir.startsWith(dir.endsWith(path.sep) ? dir : dir + path.sep),
+  );
+}
+
 export class ProjectInitializer {
   private baseCwd: string;
   private cwd: string;
   private createdItems: string[] = [];
   private skippedItems: string[] = [];
+  /** set by createCodexMCPConfig when the project isn't Codex-trusted (config would never load) */
+  private codexTrustWarning = false;
   private agents: AdapterKey[];
   private force: boolean;
   private mobile: MobileInitOptions;
@@ -360,12 +396,23 @@ export class ProjectInitializer {
     const existed = fs.existsSync(filePath);
     const existing = existed ? fs.readFileSync(filePath, 'utf-8') : '';
     const merged = mergeCodexMcpToml(existing, this.mobileOnly);
-    if (merged === null) {
+    if (merged !== null) {
+      fs.writeFileSync(filePath, merged, 'utf-8');
+      this.createdItems.push(existed ? '.codex/config.toml (updated)' : '.codex/config.toml');
+    } else {
       this.skippedItems.push('.codex/config.toml');
-      return;
     }
-    fs.writeFileSync(filePath, merged, 'utf-8');
-    this.createdItems.push(existed ? '.codex/config.toml (updated)' : '.codex/config.toml');
+
+    // Trust gate: without a trusted entry in the GLOBAL Codex config, the project config above
+    // is silently ignored and run-test never gets the MCP browser. Warn in the summary.
+    const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+    let trusted = false;
+    try {
+      trusted = codexTrustsProject(fs.readFileSync(path.join(codexHome, 'config.toml'), 'utf-8'), this.cwd);
+    } catch {
+      // no global config yet → definitely untrusted
+    }
+    this.codexTrustWarning = !trusted;
   }
 
   /**
@@ -436,6 +483,16 @@ export class ProjectInitializer {
       });
     }
 
+    if (this.codexTrustWarning) {
+      console.log('\n⚠ Codex: this project is not trusted yet, so .codex/config.toml (the MCP browser');
+      console.log('  config for run-test) will be SILENTLY IGNORED by Codex. To fix, either:');
+      console.log('    • open the project with `codex` once and approve the trust prompt, or');
+      console.log('    • add to ~/.codex/config.toml:');
+      console.log(`        [projects."${this.cwd}"]`);
+      console.log('        trust_level = "trusted"');
+      console.log('  Then verify with `codex mcp list` — it should show the sungen MCP server.');
+    }
+
     console.log('\nNext steps:');
     let stepIndex = 1;
     if (projectName) {
@@ -597,10 +654,11 @@ export class ProjectInitializer {
     // Ensure standard scripts exist in package.json
     this.ensurePackageScripts(packageJsonPath);
 
-    // Mobile-only drops @playwright/test (no web runner needed).
+    // Mobile-only drops @playwright/test (no web runner needed). `ajv`/`ajv-formats` back the API
+    // Driver's `expect {{name.body}} matches schema [Ref]` (loaded lazily; harmless if unused).
     const requiredDeps = this.mobileOnly
-      ? ['@types/node', 'yaml']
-      : ['@playwright/test', '@types/node', 'yaml'];
+      ? ['@types/node', 'yaml', 'ajv', 'ajv-formats']
+      : ['@playwright/test', '@types/node', 'yaml', 'ajv', 'ajv-formats'];
 
     let missingDeps: string[] = requiredDeps;
     try {