@sun-asterisk/sungen 3.2.6 → 3.2.8

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/api-testcase-formatter.ts

@@ -82,8 +82,17 @@ export function formatApiRequest(
     const method = String(entry.method ?? '').toUpperCase() || '—';
     const api = entry.path ? resolve(String(entry.path)) : '—';
     const header = formatHeaders(entry, call.args, localize);
-    const bodyStr = formatBody(entry.body, call.args, localize);
-    return [`Method: ${method}`, `API: ${api}`, `Header: ${header}`, `Body: ${bodyStr}`].join('\n');
+    const lines = [`Method: ${method}`, `API: ${api}`, `Header: ${header}`];
+    // A file upload carries its parts in `files:` / `bodyFile:`, NOT `body:` — render them so the
+    // delivery Steps reflect the actual request (without this, fields like `gift_image` vanished from
+    // the export even though the compiled .spec.ts sent them).
+    const filesStr = formatFiles(entry.files, call.args, localize);
+    const bodyFileStr = formatBodyFile(entry.bodyFile, call.args, localize);
+    // Body is scalar fields; a pure file upload may have none → still show `Body: —` for a stable shape.
+    lines.push(`Body: ${formatBody(entry.body, call.args, localize)}`);
+    if (filesStr) lines.push(`Files: ${filesStr}`);
+    if (bodyFileStr) lines.push(`Body file: ${bodyFileStr}`);
+    return lines.join('\n');
   });
 
   if (blocks.length === 1) return blocks[0];
@@ -180,8 +189,14 @@ function formatHeaders(
   const parts = Object.entries(explicit).map(([k, v]) =>
     isSensitiveHeader(k) ? `${k}: ${maskHeaderValue(String(v))}` : `${k}: ${localize(bindParams(String(v), args))}`,
   );
-  if (!hasContentType && entry.body !== undefined && entry.body !== null) {
-    parts.push(`Content-Type: ${contentTypeFor(entry.encoding)}`);
+  // Content-Type the request actually sends (Playwright sets it at runtime): a `files:` block is always
+  // multipart/form-data (even with `encoding` omitted); a `bodyFile:` sends the file's own media type;
+  // otherwise it follows the body encoding. Only shown when the request carries a body/file and the
+  // catalog didn't already declare a Content-Type.
+  if (!hasContentType) {
+    const ct = uploadContentType(entry);
+    if (ct) parts.push(`Content-Type: ${ct}`);
+    else if (entry.body !== undefined && entry.body !== null) parts.push(`Content-Type: ${contentTypeFor(entry.encoding)}`);
   }
   return parts.length > 0 ? parts.join('\n') : '—';
 }
@@ -192,6 +207,14 @@ function contentTypeFor(encoding?: string): string {
   return 'application/json';
 }
 
+/** Content-Type implied by a file upload, or '' when the entry sends no file. */
+function uploadContentType(entry: ApiCatalogEntry): string {
+  if (entry.files && typeof entry.files === 'object' && Object.keys(entry.files).length) return 'multipart/form-data';
+  const bf = normalizeFileSpec(entry.bodyFile);
+  if (bf) return bf.mimeType || 'application/octet-stream';
+  return '';
+}
+
 /**
  * Compose the Body cell, masking credential fields. When the body is a flat object
  * with a sensitive key (password/token/secret/…), each value is rendered per-key so
@@ -217,6 +240,56 @@ function isPlainObject(v: unknown): boolean {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
 
+interface NormalizedFileSpec { path: string; mimeType?: string; filename?: string; name?: string }
+
+/** Normalize a raw file spec (string shorthand or object) → a typed spec, or undefined if invalid. */
+function normalizeFileSpec(raw: unknown): NormalizedFileSpec | undefined {
+  if (typeof raw === 'string') return { path: raw };
+  if (isPlainObject(raw)) {
+    const o = raw as Record<string, unknown>;
+    if (typeof o.path === 'string') {
+      return {
+        path: o.path,
+        mimeType: typeof o.mimeType === 'string' ? o.mimeType : undefined,
+        filename: typeof o.filename === 'string' ? o.filename : undefined,
+        name: typeof o.name === 'string' ? o.name : undefined,
+      };
+    }
+  }
+  return undefined;
+}
+
+/** Render one file part: `field: <path> (<mimeType>)`, with `:param`/`{{var}}` resolved. */
+function renderFilePart(field: string, spec: NormalizedFileSpec, args: Record<string, string>, localize: (t: string) => string): string {
+  const p = localize(bindParams(spec.path, args));
+  return `${spec.name ?? field}: ${p}${spec.mimeType ? ` (${spec.mimeType})` : ''}`;
+}
+
+/**
+ * Render the `files:` block for the Steps cell. A field value may be a single spec, its string
+ * shorthand, or an array (multiple files under one field name) — every part is rendered. Multiple
+ * parts are comma-joined. Returns '' when there is no file field.
+ */
+function formatFiles(files: unknown, args: Record<string, string>, localize: (t: string) => string): string {
+  if (!isPlainObject(files)) return '';
+  const parts: string[] = [];
+  for (const [field, raw] of Object.entries(files as Record<string, unknown>)) {
+    for (const s of Array.isArray(raw) ? raw : [raw]) {
+      const spec = normalizeFileSpec(s);
+      if (spec) parts.push(renderFilePart(field, spec, args, localize));
+    }
+  }
+  return parts.join(', ');
+}
+
+/** Render the `bodyFile:` (raw-binary body) for the Steps cell, or '' when absent. */
+function formatBodyFile(bodyFile: unknown, args: Record<string, string>, localize: (t: string) => string): string {
+  const spec = normalizeFileSpec(bodyFile);
+  if (!spec) return '';
+  const p = localize(bindParams(spec.path, args));
+  return `${p} (${spec.mimeType || 'application/octet-stream'})`;
+}
+
 /**
  * Credential name matcher (substring, not anchored) for both body-field keys and
  * test-data keys — catches variants like confirmPassword / new_password /

package/src/exporters/csv-exporter.ts

@@ -183,7 +183,12 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
       steps,
       expectedResults,
       priority,
-      testcaseType: m.spec ? testcaseType : testcaseType === 'Manual' ? 'Manual' : 'Not compiled',
+      // An execution `result` proves the scenario compiled AND ran — it MUST win over the
+      // `!m.spec` "not compiled" heuristic, exactly as the testResult branch above does. A @cases
+      // scenario compiles to per-row titles with a `— <label>` suffix, so findMatchingSpecTest
+      // (base-name match) often leaves m.spec null even though the row ran; without checking result
+      // here, those already-passed/failed rows were mislabelled "Not compiled".
+      testcaseType: (m.spec || result) ? testcaseType : testcaseType === 'Manual' ? 'Manual' : 'Not compiled',
       testResult,
       executedDate,
       testExecutor: executor,

package/src/exporters/json-exporter.ts

@@ -15,12 +15,13 @@ 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 {
@@ -53,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>;
 }
 
 /**
@@ -77,8 +87,40 @@ 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');

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/types.ts

@@ -177,5 +177,10 @@ export interface ApiCatalogEntry {
    *  Absent/`json` → application/json, `form` → application/x-www-form-urlencoded,
    *  `multipart` → multipart/form-data. */
   encoding?: 'json' | 'form' | 'multipart';
+  /** Multipart file parts (multipart/form-data). A field value may be a single file spec, its string
+   *  shorthand, or an array of specs (multiple files under one field name). Typed loosely — guard before use. */
+  files?: Record<string, unknown>;
+  /** Raw-binary body: the request body IS the file's bytes. Typed loosely — guard before use. */
+  bodyFile?: unknown;
   expect?: { status?: number | string };
 }