@sun-asterisk/sungen 3.2.5 → 3.2.7

package/src/dashboard/types.ts

@@ -76,6 +76,25 @@ export interface FeatureSnapshot {
   locales?: LocaleSnapshot[];          // locale overlays WITHIN this entry (base + at least one overlay)
   platform?: 'android' | 'ios';        // one OS run of a @platform:mobile feature (separate entry per OS)
   executedPlatforms?: ('android' | 'ios')[]; // OSes that produced a result file this run (mobile only)
+  /** API detail sheet rows (api-kind units only) — precomputed by the snapshot
+   *  builder with the same buildApiDetailRows call the delivery CLI uses, so the
+   *  dashboard XLSX export appends an "API detail" sheet identical to delivery's. */
+  apiDetail?: ApiDetailRow[];
+}
+
+/**
+ * One endpoint row of the "API detail" sheet (api-kind units). Structural copy
+ * of ApiDetailRow in src/exporters/types.ts — kept local so this file stays
+ * import-free (it is mirrored verbatim into dashboard/src/types.ts).
+ */
+export interface ApiDetailRow {
+  endpoint: string;                    // catalog path, e.g. /users/count?email=:email
+  method: string;                      // HTTP method
+  authDatasource: string;              // datasource + any @auth tag
+  requestShape: string;                // body fields / params / encoding
+  expectedStatusMatrix: string;        // expect.status + @cases dataset pointer
+  flowSteps: string;                   // ordered @api:<name> chain for flow scenarios
+  concurrencyInvariant: string;        // @concurrent invariant, when present
 }
 
 /**

package/src/exporters/api-catalog-loader.ts

@@ -0,0 +1,44 @@
+/**
+ * Load the apis.yaml endpoint catalog for an api-kind unit — shared by the
+ * delivery CLI (CSV/XLSX export) and the dashboard snapshot builder so both
+ * surfaces render the identical request/response contract for API test cases.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { ApiCatalogEntry } from './types';
+
+/**
+ * Load the apis.yaml catalog for an api-kind unit, merging the shared catalog under
+ * the unit catalog. The runtime resolves an endpoint unit-scope-first then falls back
+ * to the shared catalog (driver-api api-catalog.ts), so an endpoint defined only in
+ * `qa/api/apis.yaml` still runs — we must load it too, or its request block would come
+ * back empty (the very bug this feature fixes). Unit wins on a name collision.
+ * Returns an empty object when neither file is present (graceful degradation).
+ */
+export function loadApiCatalog(
+  cwd: string,
+  kind: 'screen' | 'flow' | 'api',
+  screen: string,
+): Record<string, ApiCatalogEntry> {
+  if (kind !== 'api') return {};
+  const shared = readApiCatalogFile(path.join(cwd, 'qa', 'api', 'apis.yaml'));
+  const unit = readApiCatalogFile(path.join(cwd, 'qa', 'api', screen, 'api', 'apis.yaml'));
+  return { ...shared, ...unit };
+}
+
+/** Parse one apis.yaml file into an endpoint map, unwrapping the optional `apis:` wrapper. */
+export function readApiCatalogFile(catalogPath: string): Record<string, ApiCatalogEntry> {
+  if (!fs.existsSync(catalogPath)) return {};
+  try {
+    const parsed = parseYaml(fs.readFileSync(catalogPath, 'utf-8')) as Record<string, unknown> | null;
+    if (parsed && typeof parsed === 'object') {
+      // The runtime loader accepts both a flat map and an `apis:` wrapper — unwrap it
+      // here too so both loaders read the same file identically.
+      const root = parsed.apis && typeof parsed.apis === 'object' ? parsed.apis : parsed;
+      return root as Record<string, ApiCatalogEntry>;
+    }
+  } catch { /* malformed yaml — skip */ }
+  return {};
+}

package/src/exporters/csv-exporter.ts

@@ -25,6 +25,7 @@ import {
 import { ApiCatalogEntry, EnvironmentInfo, PlaywrightResult, ScreenSummary, TestCaseRow } from './types';
 import { collectSecretValues, formatApiExpected, formatApiRequest, hasApiCalls, redactSecrets } from './api-testcase-formatter';
 import { SelectorKeyMap, substituteSelectorKeysInStep } from './selector-key-resolver';
+import { resolveResultVariants } from './result-variants';
 
 export interface BuildCsvInput {
   screen: string;
@@ -66,21 +67,10 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
   let fallbackIndex = 1;
 
   for (const m of input.merged) {
-    // Data-driven (@cases): one scenario ran once per input row — emit one CSV row per
-    // executed input. The Playwright results are titled "<scenario> — <label>"; expand
-    // by matching that prefix. With no results yet, fall back to a single (Pending) row.
-    const isCases = m.feature.tags.some((t) => t.startsWith('@cases:'));
-    let variants: Array<{ nameSuffix: string; result?: PlaywrightResult }> = [{ nameSuffix: '' }];
-    if (isCases && input.results) {
-      // Result titles are "<describe> > <scenario> — <label>"; match the scenario+label marker.
-      const marker = `${m.feature.name} — `;
-      const rowResults = [...input.results.entries()].filter(([t]) => t.includes(marker));
-      if (rowResults.length) {
-        variants = rowResults.map(([t, r]) => ({ nameSuffix: ` — ${t.slice(t.indexOf(marker) + marker.length)}`, result: r }));
-      }
-    } else if (input.results && m.spec) {
-      variants = [{ nameSuffix: '', result: input.results.get(m.spec.testTitle) }];
-    }
+    // Data-driven (@cases): expand to one CSV row per executed dataset input (Playwright titles
+    // "<scenario> — <label>"); plain scenarios resolve their single result. Shared with the
+    // dashboard/JSON exporter via resolveResultVariants so the two can't drift on @cases handling.
+    const variants = resolveResultVariants(m, input.results);
 
    for (const variant of variants) {
     const displayName = `${m.feature.name}${variant.nameSuffix}`;
@@ -154,21 +144,26 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
     let environment = '';
     let executor = '';
 
-    if (!m.spec) {
-      // Scenario not compiled → Manual if @manual, else Not compiled
+    if (result) {
+      // An execution record exists → the scenario compiled AND ran; that is authoritative and
+      // MUST win over the `!m.spec` "not compiled" heuristic below. A @cases scenario compiles to
+      // per-row test titles carrying a `— <label>` suffix, so `findMatchingSpecTest` (base-name
+      // match) frequently leaves `m.spec` null even though the rows ran — without checking `result`
+      // first, those already-passed/failed rows were mislabelled N/A ("not compiled").
+      testResult = statusToTestResult(result.status);
+      executedDate = formatExecutedDate(result.startTime);
+      note = formatNote(result, expectedResults);
+      environment = formatEnv(input.env.baseURL, input.featurePath, result.projectName || input.env.projectName);
+      executor = input.env.executor;
+    } else if (!m.spec) {
+      // No execution record AND no compiled test → Manual if @manual, else genuinely not compiled.
       testResult = testcaseType === 'Manual' ? 'Pending' : 'N/A';
       if (testcaseType !== 'Manual') {
         note = 'Scenario not compiled — re-run `sungen generate --screen ' + input.screen + '`';
       }
-    } else if (!result) {
+    } else {
       // Compiled but no execution record → Pending
       testResult = 'Pending';
-    } else {
-      testResult = statusToTestResult(result.status);
-      executedDate = formatExecutedDate(result.startTime);
-      note = formatNote(result, expectedResults);
-      environment = formatEnv(input.env.baseURL, input.featurePath, result.projectName || input.env.projectName);
-      executor = input.env.executor;
     }
 
     // If we have environment info and the test actually ran, populate env + executor

package/src/exporters/feature-parser.ts

@@ -144,11 +144,17 @@ export function extractTestcaseType(tags: string[]): 'Auto' | 'Manual' {
 
 /**
  * Extract auth role from tags. Returns 'no-auth' if @no-auth, else role name or null.
+ *
+ * Merged tag arrays put feature-level tags before scenario-level ones
+ * (`parseFeatureMetadata` builds `[...featureTags, ...scenarioTags]`), so the
+ * LAST @auth: tag is the most specific — a scenario-level @auth:owner must
+ * override a feature-level @auth:user in the delivery Pre-condition column,
+ * matching the codegen precedence (getEffectiveAuthRole: Scenario > Feature).
  */
 export function extractAuthRole(tags: string[]): string | null {
   if (tags.includes('@no-auth')) return 'no-auth';
-  const authTag = tags.find((t) => t.startsWith('@auth:'));
-  if (authTag) return authTag.replace('@auth:', '');
+  const authTags = tags.filter((t) => t.startsWith('@auth:'));
+  if (authTags.length > 0) return authTags[authTags.length - 1].replace('@auth:', '');
   return null;
 }
 

package/src/exporters/json-exporter.ts

@@ -15,13 +15,15 @@ import {
   splitVpAndName,
 } from './feature-parser';
 import { formatPrecondition, keepActor, stripActor } from './step-formatter';
-import { formatTestData } from './test-data-resolver';
+import { formatTestData, substituteTestDataVars } from './test-data-resolver';
+import { collectSecretValues, formatApiExpected, formatApiRequest, hasApiCalls, redactSecrets } from './api-testcase-formatter';
 import {
   formatExecutedDate,
   statusToTestResult,
 } from './playwright-report-parser';
-import { EnvironmentInfo, PlaywrightResult } from './types';
+import { ApiCatalogEntry, EnvironmentInfo, PlaywrightResult } from './types';
 import { SelectorKeyMap, substituteSelectorKeysInStep } from './selector-key-resolver';
+import { resolveResultVariants } from './result-variants';
 import {
   ScenarioSnapshot,
   ScreenSnapshot,
@@ -52,6 +54,15 @@ export interface BuildScreenSnapshotInput {
    * link" instead of the VI key "Click [VỀ KUDOS] link".
    */
   selectorKeyMap?: SelectorKeyMap;
+  /**
+   * Unit kind. When `'api'`, Steps/Expected are composed from the request
+   * contract (Method/API/Header/Body) and response contract (Status + Response)
+   * exactly like csv-exporter's buildTestCaseRows — so the dashboard UI and its
+   * XLSX export show the same cells as the delivery CSV.
+   */
+  kind?: 'screen' | 'flow' | 'api';
+  /** apis.yaml catalog (keyed by endpoint name) for api-kind units. */
+  apiCatalog?: Record<string, ApiCatalogEntry>;
 }
 
 /**
@@ -62,11 +73,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);
@@ -81,33 +87,70 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
         : text;
     const formatStep = (s: { text: string; bucket: 'given' | 'when' | 'then' }) =>
       localize(s.bucket === 'given' ? keepActor(s.text) : stripActor(s.text));
-    const steps = m.resolvedSteps.map(formatStep).filter(Boolean);
-    const expectedResults = m.resolvedExpected.map(formatStep).filter(Boolean);
+    let steps = m.resolvedSteps.map(formatStep).filter(Boolean);
+    let expectedResults = m.resolvedExpected.map(formatStep).filter(Boolean);
+
+    // API test cases: mirror csv-exporter's request/response rendering so the
+    // dashboard (UI + XLSX export) shows the same Steps / Expected results as
+    // the delivery CSV. The cells are composed with the CSV's exact single-vs-
+    // numbered join, then stored as ONE array entry — the dashboard XLSX
+    // adapter's formatList() (1 entry → raw) reproduces the delivery cell
+    // byte-for-byte, and the UI renders the block with pre-wrap.
+    if (input.kind === 'api' && input.apiCatalog && hasApiCalls(m.feature.tags)) {
+      // Delivery cells substitute {{var}} test-data refs (csv-exporter's localize);
+      // scope that to the API branch so non-API snapshot behavior is untouched.
+      const localizeApi = (text: string): string => substituteTestDataVars(localize(text), input.testData);
+      const formatStepApi = (s: { text: string; bucket: 'given' | 'when' | 'then' }) =>
+        localizeApi(s.bucket === 'given' ? keepActor(s.text) : stripActor(s.text));
+      const joinCell = (lines: string[]): string =>
+        lines.length === 0 ? '' :
+        lines.length === 1 ? lines[0] :
+        lines.map((l, i) => `${i + 1}. ${l}`).join('\n');
+      let stepsCell = joinCell(m.resolvedSteps.map(formatStepApi).filter(Boolean));
+      let expectedCell = joinCell(m.resolvedExpected.map(formatStepApi).filter(Boolean));
+      const apiRequest = formatApiRequest(m.feature.tags, input.apiCatalog, localizeApi);
+      if (apiRequest) stepsCell = stepsCell ? `${stepsCell}\n\n${apiRequest}` : apiRequest;
+      const apiExpected = formatApiExpected(m.resolvedExpected, m.feature.tags, localizeApi);
+      if (apiExpected) expectedCell = apiExpected;
+      // Same value-based redaction backstop as the CSV path.
+      const secrets = collectSecretValues(input.testData);
+      if (secrets.length > 0) {
+        stepsCell = redactSecrets(stepsCell, secrets);
+        expectedCell = redactSecrets(expectedCell, secrets);
+      }
+      steps = stepsCell ? [stepsCell] : [];
+      expectedResults = expectedCell ? [expectedCell] : [];
+    }
     // Dashboard modal uses whitespace-pre-wrap — pass '\n' to render one
     // 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 +169,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/playwright-report-parser.ts

@@ -3,8 +3,35 @@
  */
 
 import * as fs from 'fs';
+import * as path from 'path';
 import { PlaywrightResult } from './types';
 
+/**
+ * Resolve the results.json file for a unit — shared by the delivery CLI and
+ * the dashboard snapshot builder so both surfaces resolve execution status
+ * from the SAME file (they drifted: the dashboard only looked for the
+ * per-feature file and showed every scenario Pending on projects whose
+ * playwright.config writes only the default global test-results/results.json).
+ *
+ * Candidate order (first existing wins):
+ *   1. <genDir>/<featureBaseName>-test-result.<SUNGEN_ENV>.json  (env runs)
+ *   2. <genDir>/<featureBaseName>-test-result.json               (per-feature reporter)
+ *   3. <cwd>/test-results/results.<SUNGEN_ENV>.json
+ *   4. <cwd>/test-results/results.json                           (playwright default)
+ */
+export function resolveResultsPath(cwd: string, genDir: string, featureBaseName: string): string | null {
+  const env = process.env.SUNGEN_ENV;
+  const candidates: string[] = [];
+  if (env) candidates.push(path.join(genDir, `${featureBaseName}-test-result.${env}.json`));
+  candidates.push(path.join(genDir, `${featureBaseName}-test-result.json`));
+  if (env) candidates.push(path.join(cwd, 'test-results', `results.${env}.json`));
+  candidates.push(path.join(cwd, 'test-results', 'results.json'));
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
 /**
  * Shape of the JSON reporter output we care about.
  * See https://playwright.dev/docs/test-reporters#json-reporter

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: '' }];
+}