@sun-asterisk/sungen 2.6.10 → 2.6.12

package/src/exporters/xlsx-exporter.ts

@@ -12,6 +12,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import ExcelJS from 'exceljs';
+import JSZip from 'jszip';
 import { ScreenSummary, TestCaseRow } from './types';
 import { getPackageVersion } from './package-info';
 import { SUN_LOGO_PNG_BASE64 } from './sun-logo';
@@ -54,7 +55,7 @@ export function renderXlsx(
 
   // -- Column widths matching template_report.xlsx (Sample sheet) --
   ws.columns = [
-    { width: 6.38 },  // A — TC ID
+    { width: 20 },    // A — TC ID (wider to fit long flow IDs like FLOW-KUDO-…)
     { width: 12.5 },  // B — Screen/Function
     { width: 15.38 }, // C — Big item
     { width: 16.25 }, // D — Medium item
@@ -92,28 +93,24 @@ export function renderXlsx(
   ws.mergeCells('A4:F4');
   ws.mergeCells('G4:H4');
 
-  // A1 (logo band, merged A1:C3) — give it bordering + embed the Sun* logo.
+  // A1 (logo band, merged A1:C3) — border + embedded Sun* logo (base64 inline).
   const a1 = ws.getCell('A1');
   a1.alignment = { horizontal: 'center', vertical: 'middle' };
   a1.border = allBordersBlack;
 
-  // Embed Sun* logo using a oneCellAnchor + explicit pixel `ext`, exactly
-  // like the template. tl is offset into the merged band so the logo lands
-  // centred in A1:C3 instead of pinned to the top-left corner.
   try {
     const imageId = wb.addImage({
       buffer: Buffer.from(SUN_LOGO_PNG_BASE64, 'base64') as unknown as ExcelJS.Buffer,
       extension: 'png',
     });
-    // A1:C3 ≈ 240 × 60 px. For a 90×50 logo centred horizontally / vertically:
-    //   left margin = (240 − 90)/2 ≈ 75 px → 9525 EMU/px → 714375 EMU
-    //   top margin  = (60 − 50)/2 ≈ 5 px  → 47625 EMU
-    // ExcelJS's fractional `col`/`row` clamps to a small EMU range, so we
-    // bypass it and write `native*` fields directly (the underlying XML uses
-    // the same field names).
+    // Centre a fixed-size 90×51 logo inside A1:C3 using absolute EMU offsets.
+    // Col widths (A=20, B=12.5, C=15.38) → pixels via Excel's `w*7+5` rule:
+    //   A=145, B=92.5, C=112.66  ⇒  A1:C3 ≈ 350 px wide.
+    // Left padding for a 90-px image = (350−90)/2 ≈ 130 px = 1,237,500 EMU.
+    // 3 default rows × 20 px = 60 px; top padding ≈ 4.5 px ≈ 42,862 EMU.
     ws.addImage(imageId, {
-      tl: { nativeCol: 0, nativeColOff: 714375, nativeRow: 0, nativeRowOff: 47625 } as unknown as ExcelJS.Anchor,
-      ext: { width: 90, height: 50 },
+      tl: { nativeCol: 0, nativeColOff: 1237500, nativeRow: 0, nativeRowOff: 42862 } as unknown as ExcelJS.Anchor,
+      ext: { width: 90, height: 51 },
       editAs: 'oneCell',
     } as unknown as ExcelJS.ImageRange);
   } catch { /* logo is decorative — never block export */ }
@@ -161,8 +158,7 @@ export function renderXlsx(
   g4.alignment = { horizontal: 'right', vertical: 'middle', wrapText: true };
   g4.border = allBordersBlack;
 
-  // -- Row 5: spacer (height 12) --
-  ws.getRow(5).height = 12;
+  // -- Row 5: spacer (height auto-fit). --
 
   // -- Row 6: Summary headers (cols C..H), lavender fill --
   const sumLabels: Record<string, string> = {
@@ -176,7 +172,7 @@ export function renderXlsx(
     c.alignment = { horizontal: 'center', vertical: 'top' };
     c.border = allBordersBlack;
   }
-  ws.getRow(6).height = 12;
+  // 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
@@ -200,7 +196,7 @@ export function renderXlsx(
     c.border = allBordersBlack;
     if (col === 'H') c.numFmt = '#,##0';
   }
-  ws.getRow(7).height = 12;
+  // No explicit height → Excel auto-fits.
 
   // C8 has no value in the template but still needs a border so the band
   // visually closes underneath "Total TCs".
@@ -227,7 +223,7 @@ export function renderXlsx(
     c.border = allBordersBlack;
     c.numFmt = '0%';
   }
-  ws.getRow(8).height = 12;
+  // No explicit height → Excel auto-fits.
 
   // After rows 1-8 are populated, append a blank row 9 spacer.
   while (ws.rowCount < 9) ws.addRow([]);
@@ -353,6 +349,17 @@ export function renderXlsx(
     to: { row: ws.rowCount, column: COL_COUNT },
   };
 
+  // Sheet protection lets the picLocks on the embedded logo take effect
+  // (Excel honours image locks only when the sheet is protected). Empty
+  // password — QA can run Review → Unprotect Sheet if they need to edit.
+  // `objects: false` here is ExcelJS's inverted semantic that writes
+  // `objects="1"` in XML (= objects ARE locked).
+  (ws as unknown as { sheetProtection: object }).sheetProtection = {
+    sheet: true,
+    objects: false,
+    scenarios: false,
+  };
+
   return wb;
 }
 
@@ -368,9 +375,41 @@ export async function writeXlsx(
   const outDir = path.join(cwd, 'qa', 'deliverables');
   if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
   const outPath = path.join(outDir, `${screen}-testcases.xlsx`);
-  await wb.xlsx.writeFile(outPath);
+  const buffer = await wb.xlsx.writeBuffer();
+  const locked = await lockEmbeddedImages(Buffer.from(buffer as ArrayBuffer));
+  fs.writeFileSync(outPath, locked);
   return outPath;
 }
 
+/**
+ * Post-process the workbook buffer: extend `<a:picLocks>` on every drawing
+ * with `noMove`, `noResize`, `noSelect`. Combined with the sheet protection
+ * above, the embedded logo can't be dragged, resized, or selected via the UI.
+ */
+export async function lockEmbeddedImages(buffer: Buffer): Promise<Buffer> {
+  const zip = await JSZip.loadAsync(buffer);
+  const drawingFiles = Object.keys(zip.files).filter(
+    (name) => /^xl\/drawings\/drawing\d+\.xml$/.test(name)
+  );
+  for (const name of drawingFiles) {
+    const file = zip.file(name);
+    if (!file) continue;
+    const xml = await file.async('string');
+    const patched = xml.replace(
+      /<a:picLocks([^/]*)\/>/g,
+      (_match, attrs: string) => {
+        const has = (k: string) => new RegExp(`\\b${k}=`).test(attrs);
+        const additions = ['noMove', 'noResize', 'noSelect']
+          .filter((k) => !has(k))
+          .map((k) => ` ${k}="1"`)
+          .join('');
+        return `<a:picLocks${attrs}${additions}/>`;
+      }
+    );
+    zip.file(name, patched);
+  }
+  return zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+}
+
 void applyBorder;
 void ({} as AnyRow);

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

@@ -4,6 +4,7 @@ import yaml from 'yaml';
 import { readYaml, readYamlIfExists } from '../../../utils/yaml-io';
 
 import { SelectorType } from '../../../utils/selector-types';
+import { DataResolver } from './data-resolver';
 
 // Structured selector format v2
 interface SelectorEntry {
@@ -414,6 +415,20 @@ export class SelectorResolver {
     return this.resolveNaturalLanguage(selectorRef, this.featureName);
   }
 
+  /**
+   * Replace {{variable}} references in selector values with runtime data markers.
+   * This enables i18n: selectors can reference locale-dependent text from test-data.
+   *
+   * "{{lbl_submit}}" → "__SUNGEN_TD_lbl_submit__"
+   * "Hello {{name}}" → "Hello __SUNGEN_TD_name__"
+   * "No variables"   → "No variables" (unchanged)
+   */
+  private static resolveTemplateVars(value: string): string {
+    return value.replace(/\{\{([^}]+)\}\}/g, (_, varName) => {
+      return DataResolver.encodeMarker(varName.trim());
+    });
+  }
+
   /**
    * Resolve from new structured entry format
    */
@@ -422,9 +437,11 @@ export class SelectorResolver {
     const locator = entry.locator || '';
     const type = entry.type || 'placeholder';
     // Check if value exists in entry (even if empty string), use it; otherwise use originalLabel
-    const value = entry.value !== undefined && entry.value !== null ? entry.value : 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 name = entry.name !== undefined && entry.name !== null ? entry.name : originalLabel;
+    const rawName = entry.name !== undefined && entry.name !== null ? entry.name : originalLabel;
+    const value = SelectorResolver.resolveTemplateVars(rawValue);
+    const name = SelectorResolver.resolveTemplateVars(rawName);
     const nth = entry.nth !== undefined && entry.nth !== null ? entry.nth : undefined;
     const exact = entry.exact === true || entry.match === 'exact';
     const inputMethod = entry.inputMethod;

package/src/orchestrator/project-initializer.ts

@@ -147,7 +147,6 @@ export class ProjectInitializer {
     const gitignorePath = path.join(this.cwd, '.gitignore');
     const sungenEntries = [
       '# Sungen generated files',
-      'specs/generated/',
       'specs/.auth/',
       'test-results/',
       'playwright-report/',
@@ -162,7 +161,7 @@ export class ProjectInitializer {
     } else {
       // Append Sungen entries if not already present
       let content = fs.readFileSync(gitignorePath, 'utf-8');
-      const needsUpdate = !content.includes('specs/generated/');
+      const needsUpdate = !content.includes('specs/.auth/');
       
       if (needsUpdate) {
         content += '\n' + sungenEntries.join('\n') + '\n';
@@ -450,8 +449,9 @@ export class ProjectInitializer {
     console.log(`📦 Installing ${missingDeps.join(', ')}...\n`);
     execSync(`npm install -D ${missingDeps.join(' ')}`, execOpts);
 
-    console.log('\n🎭 Installing Playwright browsers...\n');
-    execSync('npx playwright install', execOpts);
+    console.log('\n🎭 Installing Chromium (default browser)...\n');
+    execSync('npx playwright install --with-deps chromium', execOpts);
+    console.log('\n💡 To install other browsers: npm run install:browsers -- firefox webkit\n');
   }
 
   /**
@@ -477,7 +477,7 @@ export class ProjectInitializer {
       'test:ui': 'playwright test specs/generated/ --ui',
       'report': 'playwright show-report',
       'generate': 'sungen generate --all',
-      'install:browsers': 'npx playwright install chromium',
+      'install:browsers': 'npx playwright install',
     };
 
     let added = 0;

package/src/orchestrator/templates/ai-instructions/claude-config.md

@@ -82,6 +82,8 @@ qa/deliverables/<name>-testcases.xlsx  # Styled workbook for client hand-off
 
 **Environment overrides**: `SUNGEN_ENV=staging npx playwright test` merges `<screen>.staging.yaml` on top of `<screen>.yaml`. Create `<screen>.<env>.yaml` for environment-specific values (different credentials, URLs, test users).
 
+**i18n support**: for multilingual sites, use `{{variable}}` in selector `name`/`value` fields to reference locale-dependent text from test-data. Create locale overlay files (e.g., `<screen>.vi.yaml`, `<screen>.staging-ja.yaml`) and run with `SUNGEN_ENV=vi`. One feature file + one selector file works across all locales. See `sungen-selector-keys` skill for details.
+
 ## CLI Commands
 
 ```bash

package/src/orchestrator/templates/ai-instructions/claude-skill-selector-fix.md

@@ -61,6 +61,7 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
    - Selector priority: follow the table in **Diagnosis & Fix § Step 3** (`testid` > `role`+name > `placeholder` > `label` > `locator` > `text`).
    - Copy names **character-for-character** from the snapshot. Never infer from the Gherkin label.
    - If an element is auto-inferable per `sungen-selector-keys` § Auto-Infer, **omit it** from YAML — keep the file minimal.
+   - **i18n sites**: if the site supports multiple languages, use `{{variable}}` in `name`/`value` fields instead of hardcoded text. Add corresponding `lbl_*` keys to `test-data.yaml` + locale overlay files (see `sungen-selector-keys` § i18n).
 7. **Substring ambiguity check**: for each `role` + `name` selector, check if any other element in the snapshot has a name that **contains** this name as a substring (e.g., `"Đăng ký"` vs `"Đăng ký bằng Google"`). If yes → add `exact: true` to prevent strict mode violation at runtime.
 8. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
 9. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.

package/src/orchestrator/templates/ai-instructions/claude-skill-selector-keys.md

@@ -115,6 +115,44 @@ gửi lời cảm ơn--3:
   name: 'Gửi lời cảm ơn'
 ```
 
+## i18n: Template Variables in Selectors
+
+For multilingual sites without `data-testid`, use `{{variable}}` in `name` or `value` fields to reference locale-dependent text from `test-data.yaml`.
+
+```yaml
+# selectors — one file for all locales
+submit:
+  type: role
+  value: button
+  name: "{{lbl_submit}}"
+
+search:
+  type: placeholder
+  value: "{{lbl_search}}"
+
+logo:
+  type: testid
+  value: app-logo            # testid is locale-independent — no variable needed
+```
+
+```yaml
+# test-data/login.yaml (base — English)
+lbl_submit: "Sign in"
+lbl_search: "Search..."
+
+# test-data/login.vi.yaml (Vietnamese)
+lbl_submit: "Đăng nhập"
+lbl_search: "Tìm kiếm..."
+```
+
+Run: `SUNGEN_ENV=vi npx playwright test`
+
+**Rules:**
+1. Prefix i18n keys with `lbl_`, `msg_`, `txt_` to separate from test data
+2. Prefer `data-testid` — only use `{{variable}}` when no stable selector exists
+3. Feature file stays identical across locales
+4. Requires runtime data mode (default, not `--inline-data`)
+
 ## Lookup Priority
 
 Resolver searches in this order:

package/src/orchestrator/templates/ai-instructions/claude-skill-tc-generation.md

@@ -352,6 +352,8 @@ Feature: <Screen> Screen
 
 **Environment-specific data**: create `<screen>.<env>.yaml` alongside the base file with only the keys that change. Users run `SUNGEN_ENV=staging npx playwright test` to merge overrides.
 
+**i18n / multilingual**: use the same `SUNGEN_ENV` overlay for locale variants — e.g., `login.vi.yaml`, `login.staging-ja.yaml`. Include `lbl_*` / `msg_*` keys for selector `{{variable}}` references (see `sungen-selector-keys` § i18n). One feature file + one selector file works across all locales.
+
 ## Flow Test Generation
 
 When generating tests for a **flow** (`qa/flows/<name>/`), adapt the strategy:

package/src/orchestrator/templates/ai-instructions/copilot-config.md

@@ -82,6 +82,8 @@ qa/deliverables/<name>-testcases.xlsx  # Styled workbook for client hand-off
 
 **Environment overrides**: `SUNGEN_ENV=staging npx playwright test` merges `<screen>.staging.yaml` on top of `<screen>.yaml`. Create `<screen>.<env>.yaml` for environment-specific values (different credentials, URLs, test users).
 
+**i18n support**: for multilingual sites, use `{{variable}}` in selector `name`/`value` fields to reference locale-dependent text from test-data. Create locale overlay files (e.g., `<screen>.vi.yaml`, `<screen>.staging-ja.yaml`) and run with `SUNGEN_ENV=vi`. One feature file + one selector file works across all locales. See `sungen-selector-keys` skill for details.
+
 ## CLI Commands
 
 ```bash

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-selector-fix.md

@@ -61,6 +61,7 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
    - Selector priority: follow the table in **Diagnosis & Fix § Step 3** (`testid` > `role`+name > `placeholder` > `label` > `locator` > `text`).
    - Copy names **character-for-character** from the snapshot. Never infer from the Gherkin label.
    - If an element is auto-inferable per `sungen-selector-keys` § Auto-Infer, **omit it** from YAML — keep the file minimal.
+   - **i18n sites**: if the site supports multiple languages, use `{{variable}}` in `name`/`value` fields instead of hardcoded text. Add corresponding `lbl_*` keys to `test-data.yaml` + locale overlay files (see `sungen-selector-keys` § i18n).
 7. **Substring ambiguity check**: for each `role` + `name` selector, check if any other element in the snapshot has a name that **contains** this name as a substring (e.g., `"Đăng ký"` vs `"Đăng ký bằng Google"`). If yes → add `exact: true` to prevent strict mode violation at runtime.
 8. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
 9. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-selector-keys.md

@@ -115,6 +115,44 @@ gửi lời cảm ơn--3:
   name: 'Gửi lời cảm ơn'
 ```
 
+## i18n: Template Variables in Selectors
+
+For multilingual sites without `data-testid`, use `{{variable}}` in `name` or `value` fields to reference locale-dependent text from `test-data.yaml`.
+
+```yaml
+# selectors — one file for all locales
+submit:
+  type: role
+  value: button
+  name: "{{lbl_submit}}"
+
+search:
+  type: placeholder
+  value: "{{lbl_search}}"
+
+logo:
+  type: testid
+  value: app-logo            # testid is locale-independent — no variable needed
+```
+
+```yaml
+# test-data/login.yaml (base — English)
+lbl_submit: "Sign in"
+lbl_search: "Search..."
+
+# test-data/login.vi.yaml (Vietnamese)
+lbl_submit: "Đăng nhập"
+lbl_search: "Tìm kiếm..."
+```
+
+Run: `SUNGEN_ENV=vi npx playwright test`
+
+**Rules:**
+1. Prefix i18n keys with `lbl_`, `msg_`, `txt_` to separate from test data
+2. Prefer `data-testid` — only use `{{variable}}` when no stable selector exists
+3. Feature file stays identical across locales
+4. Requires runtime data mode (default, not `--inline-data`)
+
 ## Lookup Priority
 
 Resolver searches in this order:

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-tc-generation.md

@@ -352,6 +352,8 @@ Feature: <Screen> Screen
 
 **Environment-specific data**: create `<screen>.<env>.yaml` alongside the base file with only the keys that change. Users run `SUNGEN_ENV=staging npx playwright test` to merge overrides.
 
+**i18n / multilingual**: use the same `SUNGEN_ENV` overlay for locale variants — e.g., `login.vi.yaml`, `login.staging-ja.yaml`. Include `lbl_*` / `msg_*` keys for selector `{{variable}}` references (see `sungen-selector-keys` § i18n). One feature file + one selector file works across all locales.
+
 ## Flow Test Generation
 
 When generating tests for a **flow** (`qa/flows/<name>/`), adapt the strategy: