@sun-asterisk/sungen 2.4.5 → 2.4.6

package/src/exporters/scenario-merger.ts

@@ -0,0 +1,63 @@
+/**
+ * Cross-validate .feature scenarios against compiled .spec.ts tests.
+ * Produces a merged view for CSV row assembly.
+ *
+ * Priority of truth:
+ *   - .spec.ts (resolved Playwright calls) is the source of truth for Steps/Expected
+ *   - .feature (tags, VP ID, referenced vars) is source for metadata
+ *   - Scenarios in .feature but NOT in .spec.ts → marked "Not compiled"
+ */
+
+import { FeatureMetadata, ScenarioMetadata, SpecFileData, SpecTest } from './types';
+import { isStepsBaseScenario, isSampleScaffoldScenario } from './feature-parser';
+
+export interface MergedScenario {
+  /** Scenario metadata from .feature */
+  feature: ScenarioMetadata;
+
+  /** Matched compiled test from .spec.ts, or null if not compiled. */
+  spec: SpecTest | null;
+}
+
+/**
+ * Merge features and spec data, excluding base @steps and scaffold scenarios.
+ */
+export function mergeFeatureAndSpec(
+  feature: FeatureMetadata,
+  spec: SpecFileData
+): MergedScenario[] {
+  const result: MergedScenario[] = [];
+
+  for (const scenario of feature.scenarios) {
+    if (isStepsBaseScenario(scenario)) continue;       // skip @steps base scenarios
+    if (isSampleScaffoldScenario(scenario)) continue;  // skip default sample
+
+    const specTest = findMatchingSpecTest(scenario, spec.tests);
+    result.push({
+      feature: scenario,
+      spec: specTest,
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Find the spec test that corresponds to a given feature scenario.
+ * Match by scenario title (exact match on the scenario name).
+ */
+function findMatchingSpecTest(scenario: ScenarioMetadata, tests: SpecTest[]): SpecTest | null {
+  // Exact title match
+  const exact = tests.find((t) => t.scenarioName === scenario.name);
+  if (exact) return exact;
+
+  // Fallback: match by VP-ID prefix (ignore trailing text differences)
+  const vpMatch = scenario.name.match(/^(VP-[A-Z]+-\d+[a-zA-Z]?)/);
+  if (vpMatch) {
+    const vpId = vpMatch[1];
+    const byVp = tests.find((t) => t.vpId === vpId);
+    if (byVp) return byVp;
+  }
+
+  return null;
+}

package/src/exporters/spec-parser.ts

@@ -0,0 +1,247 @@
+/**
+ * Parse compiled .spec.ts files to extract resolved test structure.
+ * Uses regex parsing (not TS AST) since files are auto-generated with stable format.
+ */
+
+import * as fs from 'fs';
+import { SpecTest, SpecFileData } from './types';
+
+/**
+ * Extract the inner body of a test('title', async (...) => { BODY }) block.
+ * Returns null if no match.
+ */
+function extractTestBlock(content: string, startIdx: number): {
+  title: string;
+  body: string;
+  endIdx: number;
+} | null {
+  // Match test('title', async ({ page }) => {
+  const testRegex = /test\s*\(\s*['"]([^'"]+)['"]\s*,\s*async\s*\([^)]*\)\s*=>\s*\{/g;
+  testRegex.lastIndex = startIdx;
+  const match = testRegex.exec(content);
+  if (!match) return null;
+
+  const title = match[1];
+  const bodyStart = match.index + match[0].length;
+
+  // Find matching closing brace (accounting for nested braces)
+  let depth = 1;
+  let i = bodyStart;
+  while (i < content.length && depth > 0) {
+    const ch = content[i];
+    if (ch === '{') depth++;
+    else if (ch === '}') depth--;
+    if (depth === 0) break;
+    i++;
+  }
+  if (depth !== 0) return null;
+
+  const body = content.substring(bodyStart, i);
+  // The closing `)` of the arrow function call comes after the `}`, e.g., `});` — skip it
+  const endIdx = content.indexOf(';', i) + 1;
+  return { title, body, endIdx };
+}
+
+/**
+ * Find describe('name', ...) blocks and return their names + body ranges.
+ */
+function extractDescribeBlocks(content: string): Array<{ name: string; bodyStart: number; bodyEnd: number }> {
+  const result: Array<{ name: string; bodyStart: number; bodyEnd: number }> = [];
+  const regex = /test\.describe\s*\(\s*['"]([^'"]+)['"]\s*,\s*\(\s*\)\s*=>\s*\{/g;
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(content)) !== null) {
+    const name = match[1];
+    const bodyStart = match.index + match[0].length;
+    let depth = 1;
+    let i = bodyStart;
+    while (i < content.length && depth > 0) {
+      const ch = content[i];
+      if (ch === '{') depth++;
+      else if (ch === '}') depth--;
+      if (depth === 0) break;
+      i++;
+    }
+    result.push({ name, bodyStart, bodyEnd: i });
+  }
+  return result;
+}
+
+/**
+ * A "block" in a test body: one leading // comment followed by 1+ await statements.
+ */
+interface CodeBlock {
+  comment: string;
+  code: string[];     // each string is one logical line (may contain the await keyword)
+}
+
+/**
+ * Tokenize test body into code blocks.
+ * Each block = one or more `// <comment>` lines, followed by `await ...` lines until the next comment.
+ */
+function tokenizeBody(body: string): CodeBlock[] {
+  const lines = body.split('\n').map((l) => l.trim()).filter((l) => l.length > 0);
+  const blocks: CodeBlock[] = [];
+  let currentComment = '';
+  let currentCode: string[] = [];
+
+  const flush = () => {
+    if (currentComment || currentCode.length > 0) {
+      blocks.push({ comment: currentComment, code: [...currentCode] });
+    }
+    currentComment = '';
+    currentCode = [];
+  };
+
+  for (const line of lines) {
+    if (line.startsWith('//')) {
+      // A new comment boundary — flush the previous block first if it has code
+      if (currentCode.length > 0) flush();
+      currentComment = line.replace(/^\/\/\s*/, '').trim();
+    } else if (line.startsWith('await ') || line.startsWith('await\t')) {
+      currentCode.push(line);
+    } else if (line.endsWith(';') || line.endsWith('{') || line.endsWith('}')) {
+      // Continuation of an await (multi-line code) OR block-structure like `{ ... }`
+      if (currentCode.length > 0) {
+        currentCode[currentCode.length - 1] += ' ' + line;
+      }
+    }
+  }
+  flush();
+  return blocks;
+}
+
+/**
+ * Classify a CodeBlock into precondition / step / expectation.
+ *
+ * Rules:
+ * - Starts with page.goto or is from @steps setup → precondition
+ * - Contains `expect(` → expectation
+ * - Otherwise → step (action)
+ *
+ * Additional heuristic: if the comment matches "Open <screen> page" or similar
+ * setup verbs, treat as precondition even if not first.
+ */
+function classifyBlock(block: CodeBlock): 'precondition' | 'step' | 'expectation' {
+  const codeJoined = block.code.join(' ');
+  if (codeJoined.includes('expect(')) return 'expectation';
+  if (codeJoined.includes('page.goto(')) return 'precondition';
+  return 'step';
+}
+
+/**
+ * Try to extract VP ID (e.g., VP-UI-001) from the start of a scenario title.
+ */
+function extractVpId(title: string): string | undefined {
+  const match = title.match(/^(VP-[A-Z]+-\d+[a-zA-Z]?)\b/);
+  return match ? match[1] : undefined;
+}
+
+/**
+ * Parse a compiled .spec.ts file.
+ *
+ * Structure:
+ *   test.describe('<Feature Name>', () => {
+ *     test.describe('<auth role>', () => {          // optional nesting
+ *       test.use({ storageState: '...' });
+ *       test('<title>', async ({ page }) => { ... });
+ *       ...
+ *     });
+ *     test('<title>', async ({ page }) => { ... });  // no-auth cases at top level
+ *   });
+ */
+export function parseSpecFile(specFilePath: string): SpecFileData {
+  if (!fs.existsSync(specFilePath)) {
+    return { tests: [] };
+  }
+
+  const content = fs.readFileSync(specFilePath, 'utf-8');
+  const tests: SpecTest[] = [];
+
+  const describes = extractDescribeBlocks(content);
+  if (describes.length === 0) return { tests: [] };
+
+  // First describe is the feature-level one
+  const featureDescribe = describes[0];
+  const featureName = featureDescribe.name;
+
+  // Nested auth describes live inside the feature describe range
+  const nestedAuthDescribes = describes.filter(
+    (d) => d !== featureDescribe && d.bodyStart > featureDescribe.bodyStart && d.bodyEnd < featureDescribe.bodyEnd
+  );
+
+  // Collect tests inside each nested auth describe
+  const processedRanges: Array<[number, number]> = [];
+  for (const authDesc of nestedAuthDescribes) {
+    const innerBody = content.substring(authDesc.bodyStart, authDesc.bodyEnd);
+    const innerTests = collectTestsFromBody(innerBody, featureName, authDesc.name);
+    tests.push(...innerTests);
+    processedRanges.push([authDesc.bodyStart, authDesc.bodyEnd]);
+  }
+
+  // Collect tests at the feature level that are NOT inside any nested auth describe
+  // i.e., top-level tests (no auth / @no-auth scenarios)
+  let cursor = featureDescribe.bodyStart;
+  const featureBodyEnd = featureDescribe.bodyEnd;
+
+  while (cursor < featureBodyEnd) {
+    // Skip any nested describe range
+    const nextSkip = processedRanges.find(([s, e]) => s > cursor && s < featureBodyEnd && e > cursor);
+    const searchEnd = nextSkip ? nextSkip[0] : featureBodyEnd;
+
+    const slice = content.substring(cursor, searchEnd);
+    const sliceTests = collectTestsFromBody(slice, featureName, undefined);
+    tests.push(...sliceTests);
+
+    cursor = nextSkip ? nextSkip[1] : featureBodyEnd;
+  }
+
+  return { tests };
+}
+
+function collectTestsFromBody(body: string, describeName: string, authRole?: string): SpecTest[] {
+  const tests: SpecTest[] = [];
+  let cursor = 0;
+  while (cursor < body.length) {
+    const block = extractTestBlock(body, cursor);
+    if (!block) break;
+
+    const codeBlocks = tokenizeBody(block.body);
+    const precondition: string[] = [];
+    const steps: string[] = [];
+    const expectations: string[] = [];
+
+    for (const cb of codeBlocks) {
+      const category = classifyBlock(cb);
+      const line = cb.comment || cb.code.join(' ');
+      if (category === 'precondition') precondition.push(line);
+      else if (category === 'step') steps.push(line);
+      else expectations.push(line);
+    }
+
+    tests.push({
+      describeName,
+      authRole,
+      testTitle: buildFullTestTitle(describeName, authRole, block.title),
+      scenarioName: block.title,
+      vpId: extractVpId(block.title),
+      precondition,
+      steps,
+      expectations,
+    });
+
+    cursor = block.endIdx;
+  }
+  return tests;
+}
+
+/**
+ * Build full test title matching Playwright report format:
+ *   "<Feature Name> > <auth role> > <scenario title>"
+ * Playwright separator is " > " in CLI output, but internally it uses title arrays.
+ */
+function buildFullTestTitle(featureName: string, authRole: string | undefined, scenarioTitle: string): string {
+  if (authRole) {
+    return `${featureName} > ${authRole} > ${scenarioTitle}`;
+  }
+  return `${featureName} > ${scenarioTitle}`;
+}

package/src/exporters/step-formatter.ts

@@ -0,0 +1,80 @@
+/**
+ * Convert raw Gherkin step text OR generated .spec.ts comment lines into
+ * concise, numbered natural language for the CSV Steps/Expected columns.
+ *
+ * Deterministic — no AI calls.
+ */
+
+/**
+ * Format a list of raw step lines for the Steps / Expected Results columns.
+ *
+ * - 0 lines → empty string
+ * - 1 line  → the line verbatim (no "1. " prefix — avoids Google Sheets clutter)
+ * - ≥ 2     → each line on its own row, "1. ", "2. ", … prefixes, newline-joined
+ *             so spreadsheet cells auto-wrap one step per visual line.
+ */
+export function formatNumberedSteps(lines: string[]): string {
+  const cleaned = lines.map(cleanStepLine).filter((l) => l.length > 0);
+  if (cleaned.length === 0) return '';
+  if (cleaned.length === 1) return cleaned[0];
+  return cleaned.map((line, idx) => `${idx + 1}. ${line}`).join('\n');
+}
+
+/**
+ * Clean a raw step line (either Gherkin text or .spec.ts comment).
+ *
+ * Handles patterns like:
+ *   "User click [login] button"              → "Click 'login' button"
+ *   "User fill [Email] field with {{email}}" → "Fill 'Email' field with {{email}}"
+ *   "Click Signature 2025 Creator"           → "Click 'Signature 2025 Creator'"
+ *   "Assert title error has text err_xxx"    → "Title error has text err_xxx"
+ *   "Open awards page"                       → "Open awards page"
+ */
+export function cleanStepLine(raw: string): string {
+  let s = raw.trim();
+
+  // Strip leading "User " actor
+  s = s.replace(/^User\s+/i, '');
+
+  // Strip Gherkin-style element decoration "[Ref] type" → "'Ref' type"
+  // e.g., "click [Login] button" → "click 'Login' button"
+  s = s.replace(/\[([^\]]+)\]/g, "'$1'");
+
+  // Collapse multiple spaces
+  s = s.replace(/\s+/g, ' ');
+
+  // For .spec.ts comments that start with "Assert ..." keep as-is (they read naturally)
+  // For action comments like "Click X", "Fill X with Y" keep as-is.
+
+  // Capitalize first letter
+  if (s.length > 0) s = s.charAt(0).toUpperCase() + s.slice(1);
+
+  return s;
+}
+
+/**
+ * Natural language for Given → Pre-condition.
+ * Combines auth info + Given steps into a single sentence.
+ */
+export function formatPrecondition(
+  authRole: string | null,
+  givenLines: string[]
+): string {
+  const parts: string[] = [];
+
+  // Auth prefix
+  if (authRole === 'no-auth') {
+    parts.push('Not authenticated.');
+  } else if (authRole) {
+    parts.push(`Logged in as ${authRole}.`);
+  }
+
+  // Given lines (clean + period-separated)
+  for (const line of givenLines) {
+    const cleaned = cleanStepLine(line);
+    if (!cleaned) continue;
+    parts.push(cleaned.endsWith('.') ? cleaned : cleaned + '.');
+  }
+
+  return parts.join(' ').trim();
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Resolve test-data.yaml variables for the CSV Test Data column.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+
+/**
+ * Load test-data.yaml into a flat key→value map.
+ * Returns empty map if file missing.
+ */
+export function loadTestData(testDataFilePath: string): Record<string, string> {
+  if (!fs.existsSync(testDataFilePath)) return {};
+  const content = fs.readFileSync(testDataFilePath, 'utf-8');
+  const parsed = parseYaml(content);
+  if (!parsed || typeof parsed !== 'object') return {};
+
+  // Flatten shallow object to string values
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+    if (value === null || value === undefined) continue;
+    if (typeof value === 'object') continue; // skip nested structures
+    result[key] = String(value);
+  }
+  return result;
+}
+
+/**
+ * Format a list of variable references into a "key: value; key2: value2" string
+ * suitable for the CSV Test Data column.
+ *
+ * Long values (>80 chars) are truncated with "…".
+ */
+export function formatTestData(
+  referencedVars: string[],
+  testData: Record<string, string>
+): string {
+  if (referencedVars.length === 0) return '';
+  const pairs: string[] = [];
+  for (const key of referencedVars) {
+    const value = testData[key];
+    if (value === undefined) continue;
+    pairs.push(`${key}: ${truncate(value, 80)}`);
+  }
+  return pairs.join('; ');
+}
+
+function truncate(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return s.substring(0, max - 1) + '…';
+}
+
+/**
+ * Resolve the test-data file path for a given screen.
+ */
+export function resolveTestDataPath(cwd: string, screen: string): string {
+  return path.join(cwd, 'qa', 'screens', screen, 'test-data', `${screen}.yaml`);
+}

package/src/exporters/types.ts

@@ -0,0 +1,112 @@
+/**
+ * Shared types for the delivery exporter.
+ */
+
+/**
+ * Test case row in the final CSV output.
+ */
+export interface TestCaseRow {
+  tcId: string;              // e.g. KUDOS-UI-001
+  category1: string;         // Scenario name (human part)
+  category2: string;         // "Accessing" | "GUI" | "Function"
+  category3: string;         // Feature name (e.g. "Create Kudo Modal")
+  category4: string;         // Screen name (e.g. "kudos")
+  precondition: string;      // Natural language Given + auth
+  testData: string;          // semicolon-separated key: value
+  steps: string;             // numbered steps
+  expectedResults: string;   // numbered expected results
+  priority: string;          // Critical | High | Normal | Low
+  testcaseType: string;      // Auto | Manual | Not compiled
+  testResult: string;        // Passed | Failed | Pending | N/A
+  executedDate: string;      // dd/mm/yyyy
+  testExecutor: string;      // git user.name
+  testEnvironment: string;   // baseURL + project
+  note: string;              // error + trace for failed
+}
+
+/**
+ * Summary stats per screen.
+ */
+export interface ScreenSummary {
+  screen: string;
+  total: number;
+  passed: number;
+  failed: number;
+  pending: number;
+  na: number;
+  notCompiled: number;
+  outputFile: string;
+}
+
+/**
+ * Pre-flight check result for a single screen.
+ */
+export interface PreflightCheck {
+  screen: string;
+  featureOk: boolean;
+  testDataOk: boolean;
+  selectorsOk: boolean;
+  specOk: boolean;
+  resultsOk: boolean;
+  missing: string[];         // Human-readable list of missing items
+  suggestions: string[];     // Suggested commands to run
+}
+
+/**
+ * Metadata extracted from a .feature file.
+ */
+export interface FeatureMetadata {
+  featureName: string;                    // e.g., "Create Kudo Modal"
+  featurePath?: string;                   // e.g., "/kudos"
+  featureTags: string[];                  // Feature-level tags
+  scenarios: ScenarioMetadata[];
+}
+
+export interface ScenarioMetadata {
+  name: string;                           // Full scenario name (with VP prefix)
+  tags: string[];                         // Scenario-level tags (merged with feature tags)
+  stepsName?: string;                     // @steps:<name>
+  extendsName?: string;                   // @extend:<name>
+  referencedVars: string[];               // Variables {{var}} used in this scenario
+  rawGivenSteps: string[];                // Raw Given/And-after-Given step text
+  rawWhenSteps: string[];                 // Raw When/And-after-When step text
+  rawThenSteps: string[];                 // Raw Then/And-after-Then step text
+}
+
+/**
+ * Structure extracted from a compiled .spec.ts test block.
+ */
+export interface SpecTest {
+  describeName: string;                   // test.describe title
+  authRole?: string;                      // nested describe for auth (e.g., "user")
+  testTitle: string;                      // Full Playwright test title (matches results.json)
+  scenarioName: string;                   // Scenario name without VP prefix stripped
+  vpId?: string;                          // Extracted VP-XX-NNN if present
+  precondition: string[];                 // Lines before first // [VP-...] marker
+  steps: string[];                        // Lines between marker and first expect()
+  expectations: string[];                 // Lines with expect() calls
+}
+
+export interface SpecFileData {
+  tests: SpecTest[];
+}
+
+/**
+ * Result from results.json per test.
+ */
+export interface PlaywrightResult {
+  testTitle: string;
+  status: 'passed' | 'failed' | 'skipped' | 'timedOut' | 'interrupted' | 'unknown';
+  startTime?: string;
+  error?: string;
+  tracePath?: string;
+}
+
+/**
+ * Environment metadata.
+ */
+export interface EnvironmentInfo {
+  baseURL: string;
+  projectName: string;
+  executor: string;
+}