@sun-asterisk/sungen 3.2.7 → 3.2.9

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-match-data.hbs

@@ -1,13 +1,13 @@
 {{~#if isGiven~}}
 {
-  const rows = {{> locator}}.locator('tbody').getByRole('row');
+  const rows = {{> locator}}.locator('tbody').getByRole('row', { includeHidden: true }).filter({ visible: true });
 {{#each assertions}}
   {{this}}
 {{/each~}}
 }
 {{~else~}}
 {
-  const rows = {{> locator}}.locator('tbody').getByRole('row');
+  const rows = {{> locator}}.locator('tbody').getByRole('row', { includeHidden: true }).filter({ visible: true });
 {{#each assertions}}
   {{this}}
 {{/each~}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-row-count.hbs

@@ -1 +1 @@
-await expect({{> locator}}.locator('tbody').getByRole('row')).toHaveCount({{expectedCount}});
+await expect({{> locator}}.locator('tbody').getByRole('row', { includeHidden: true }).filter({ visible: true })).toHaveCount({{expectedCount}});

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-row-exists.hbs

@@ -1,7 +1,7 @@
 {{~#if isGiven}}
-const tableRow = {{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' });
+const tableRow = {{> locator}}.getByRole('row', { includeHidden: true }).filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true });
 await tableRow.waitFor();
 {{~else}}
-const tableRow = {{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' });
+const tableRow = {{> locator}}.getByRole('row', { includeHidden: true }).filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true });
 await expect(tableRow).toBeVisible();
 {{~/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-row-not-exists.hbs

@@ -1,5 +1,5 @@
 {{~#if isGiven}}
-await {{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' }).waitFor({ state: 'hidden' });
+await {{> locator}}.getByRole('row', { includeHidden: true }).filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true }).waitFor({ state: 'hidden' });
 {{~else}}
-await expect({{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' })).toHaveCount(0);
+await expect({{> locator}}.getByRole('row', { includeHidden: true }).filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true })).toHaveCount(0);
 {{~/if}}

package/src/generators/test-generator/step-mapper.ts

@@ -229,8 +229,12 @@ export class StepMapper {
    * Generate column assertion scoped to the current row.
    * Uses columns config for exact cell targeting (nth), or filter fallback.
    *
-   * With columns:  await expect(tableRow.getByRole('cell').nth(index)).toHaveText('value');
-   * Without:       await expect(tableRow.getByRole('cell').filter({ hasText: 'value' })).toBeVisible();
+   * With columns:  await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ visible: true }).nth(index)).toHaveText('value');
+   * Without:       await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ hasText: 'value' }).filter({ visible: true })).toBeVisible();
+   *
+   * includeHidden + visible filter: when a modal (e.g. Radix Dialog) is open the
+   * background gets aria-hidden="true", which empties plain getByRole() even though
+   * the cells are still rendered — measure what the user SEES, not the a11y tree.
    */
   private generateRowScopedColumnAssertion(step: ParsedStep): MappedStep {
     const columnRef = step.selectorRef || '';
@@ -259,16 +263,16 @@ export class StepMapper {
     if (columnIndex !== undefined) {
       // Exact cell: nth(index) + toHaveText
       if (isGiven) {
-        code = `await expect(tableRow.getByRole('cell').nth(${columnIndex})).toHaveText('${escapedValue}');`;
+        code = `await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ visible: true }).nth(${columnIndex})).toHaveText('${escapedValue}');`;
       } else {
-        code = `await expect(tableRow.getByRole('cell').nth(${columnIndex})).toHaveText('${escapedValue}');`;
+        code = `await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ visible: true }).nth(${columnIndex})).toHaveText('${escapedValue}');`;
       }
     } else {
       // Fallback: filter by text
       if (isGiven) {
-        code = `await tableRow.getByRole('cell').filter({ hasText: '${escapedValue}' }).waitFor();`;
+        code = `await tableRow.getByRole('cell', { includeHidden: true }).filter({ hasText: '${escapedValue}' }).filter({ visible: true }).waitFor();`;
       } else {
-        code = `await expect(tableRow.getByRole('cell').filter({ hasText: '${escapedValue}' })).toBeVisible();`;
+        code = `await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ hasText: '${escapedValue}' }).filter({ visible: true })).toBeVisible();`;
       }
     }
 

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -149,7 +149,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 
 {{#cap parallel-subagents}}
 4. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format. **Viewpoint loading discipline:** `sungen-viewpoint` is a **router** — from the page-type (form / list / detail / auth / dashboard …) read **only the matching group file(s)** (e.g. a login screen → group-e-identity; a product list → group-c-data-explore), never all five groups. This keeps the generation context lean. **For flows**, use the "Flow Test Generation" section in the skill. When requirements exist, use the "Requirements-Driven Generation" strategy. **For Tier 1**, apply the **Lightweight Guard** — verify required fields, validation rules, business rules, security checks, and key state transitions all have TCs after generation. **For Tier 2+**, **MUST** apply the full **Mapping Contract** — walk every `spec.md` section top-to-bottom and produce the indicated TCs per Table 1; handle `test-viewpoint.md` per Table 2. Do not silently skip sections.
-5. Generate `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation`. **Partition the work into shards and generate them in parallel** when there are ≥2.
+5. Generate `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation`. **Partition the work into shards and generate them in parallel** when there are ≥2. **If a scenario needs `@query` DB verification**, check the datasource `engine` first — unsupported engine → follow `sungen-gherkin-syntax` § "Unsupported DB engine — fallback" instead of authoring `@query` steps.
 
    **5a. Decide the shards.** A shard is one **coverage unit** sized for parallelism — NOT the 5 coarse viewpoint-router groups (a screen loads only 1–2 of those). Use **either**:
    - one **viewpoint theme** per shard — a `VP-` prefix from the viewpoint overview (`VP-SEC`, `VP-ERROR-EMPTY-STATE`, `VP-CAROUSEL`, …) — preferred when the viewpoint overview is rich (test-2/home had 47 items across many themes); **or**
@@ -192,7 +192,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 {{/cap}}
 {{^cap parallel-subagents}}
 4. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format. **For flows**, use the "Flow Test Generation" section in the skill. When requirements exist, use the "Requirements-Driven Generation" strategy. **For Tier 1**, apply the **Lightweight Guard** — verify required fields, validation rules, business rules, security checks, and key state transitions all have TCs after generation. **For Tier 2+**, **MUST** apply the full **Mapping Contract** — walk every `spec.md` section top-to-bottom and produce the indicated TCs per Table 1; handle `test-viewpoint.md` per Table 2. Do not silently skip sections. Present sections as a numbered list and let user pick.
-5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills. Generate **group-by-group** (one viewpoint group at a time, tier-by-tier `Write`/`Edit` batches) to stay under the output-token cap. **For flows**: use `[Screen:Element]` namespace format, namespace test-data by phase, add `@flow` tag.
+5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills. Generate **group-by-group** (one viewpoint group at a time, tier-by-tier `Write`/`Edit` batches) to stay under the output-token cap. **For flows**: use `[Screen:Element]` namespace format, namespace test-data by phase, add `@flow` tag. **If a scenario needs `@query` DB verification**, check the datasource `engine` first — unsupported engine → follow `sungen-gherkin-syntax` § "Unsupported DB engine — fallback" instead of authoring `@query` steps.
    > **No parallel fan-out here.** Copilot has no sub-agents, so generation is sequential (the Claude Code variant fans out one `sungen-generator` per viewpoint group and merges). Same output, no speedup.
 5.4. **Depth self-check (deterministic — BEFORE the audit).** Run `sungen depth-lint --screen ${input:name}`. It splits every shallow business-critical scenario into **DEEPEN IN PLACE** (add a real value assertion — the printed `template` is a theme-keyed hint, apply judgment to the actual claim; never fake one onto a visibility/behavior scenario) and **CROSS-SCREEN** (route to a flow / tag `@manual:Mx` + reason — removes it from the depth denominator honestly). Act on both, re-run until `deepen` is empty (or only honest over-counts remain), THEN gate. Lifts first-pass `businessDepth` mechanically instead of via 2–3 repair rounds.
 5.5. **Quality gate & repair (harness — always run).** Per `sungen-harness-audit`: run `sungen audit --screen ${input:name}` (structural), THEN do an **independent semantic review inline** using the `sungen-reviewer` criteria (does each scenario's steps PROVE its title/viewpoint? observable Thens? business-critical assertion depth?). Merge both sets of issues; if gate FAILs / findings exist, repair (budget 3) and re-audit — GATE missing theme → generate it (cross-screen → **automate it in the flow** via `/sungen:add-flow`, NOT a full `@manual` screen duplicate — `sungen audit` flags an automatable `@manual` as `MANUAL-AUTOMATABLE`; reserve `@manual:Mx` for true judgment/missing-capability); DEPTH → add data assertions; BALANCE → add business-core first; TRACE → align VP ids. Never fake a pass.

package/src/orchestrator/templates/ai-src/commands/run-test.md

@@ -126,7 +126,7 @@ If the unit is **api-first**, skip every selector/capture phase (an API test has
 
 ## Pre-run (phased — per `sungen-selector-fix` skill)
 
-1. Verify `<base>/<name>/` has `.feature` + `test-data.yaml`.
+1. Verify `<base>/<name>/` has `.feature` + `test-data.yaml`. **If the feature has `@query` steps**, check the resolved datasource `engine` in `qa/datasources.yaml` — unsupported engine → follow the `sungen-gherkin-syntax` skill § "Unsupported DB engine — fallback" before compiling (do not attempt a direct connect).
 2. **Phase 0 — Selector Pre-gen**: if `selectors.yaml` is missing/empty or doesn't cover the feature file's `[Reference]`s, apply the following decision tree before running Phase 0 from `sungen-selector-fix`:
 
    ```

package/src/orchestrator/templates/ai-src/skills/sungen-api-design/SKILL.md

@@ -72,6 +72,14 @@ A flow (`create → login → delete`) is a **Functional integration** test, **n
 ## File upload (real files)
 `body:` carries only scalar fields — to send a **real file**, declare it in the catalog entry; the runtime reads the fixture from disk. Two forms, by how the server accepts the file:
 - **`files:`** → `multipart/form-data`, the file is a form part: `files: { file: { path: ":avatar", mimeType: image/png } }` (+ optional text `body:` fields alongside). Shorthand `files: { file: ":avatar" }`.
+  - **Multiple files under ONE field name** → make the field's value an **array** (each element a spec or shorthand string):
+    ```yaml
+    files:
+      gift_image:
+        - ":gift_image_1"    # test-data: gift_image_1 → fixtures/a.png
+        - ":gift_image_2"    # test-data: gift_image_2 → fixtures/b.png
+    ```
+    Each element binds its own `:param` from test-data. Use this for endpoints that accept a list of files under the same field — a single object value can only hold one file. **Automate multi-file uploads with `@api`; don't defer to `@manual`.** (File uploads use Playwright's `FormData` multipart, which requires **`@playwright/test` ≥ 1.44** — the version sungen installs by default; only projects pinned to an older Playwright need to upgrade.)
 - **`bodyFile:`** → raw binary body (the whole body IS the file's bytes, e.g. `application/octet-stream`): `bodyFile: { path: ":image", mimeType: application/octet-stream }`.
 
 Fixture path resolves cwd-relative/absolute first, else `qa/fixtures/<path>` (drop sample files there, reference by name from `test-data`). An empty resolved file param omits the part → use for missing-file `@cases` error rows. `files:`/`bodyFile:` are mutually exclusive. **Automate the upload success case with `@api`** — don't defer it to `@manual`.

package/src/orchestrator/templates/ai-src/skills/sungen-error-mapping/SKILL.md

@@ -91,7 +91,7 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | toHaveValue mismatch | Expected value differs from actual | Fix value in test-data |
 | toContainText mismatch | Partial text not found | Fix expected partial text in test-data |
 | toBeVisible timeout | Element exists but hidden, or name wrong | Check: is element conditionally visible? Wrong name? Inside dialog? |
-| toHaveCount mismatch | Row count differs | Fix expected count in test-data. Verify: is table loaded? Filtered? |
+| toHaveCount mismatch | Row count differs | Fix expected count in test-data. Verify: is table loaded? Filtered? If `Received: 0` while a dialog is open → aria-hidden trap, see **Table-Specific Errors** |
 
 ### Assertion type rule
 
@@ -111,6 +111,7 @@ If `toHaveText` fails on an input → the Gherkin step has the wrong target type
 | `tableRow is not defined` | Column assertion without preceding row scope step | The Gherkin is missing a row-scope step — this is a **QA authoring gap → report it, let it FAIL**. Do NOT add the step during run-test (the Gherkin is frozen). |
 | `toHaveText` on cell fails (with columns) | Wrong column index in `columns` config | Re-count columns in snapshot (0-indexed). Fix `index` in selectors.yaml |
 | `toBeVisible` on cell fails (no columns) | `filter({ hasText })` didn't match | Check exact cell text in snapshot. Fix value in test-data |
+| Row/cell count reads 0 while a dialog is open, rows visibly present behind it | **aria-hidden trap**: the modal (Radix/MUI/HeadlessUI…) sets `aria-hidden="true"` on the background; plain `getByRole('row'/'cell')` reads the a11y tree, which is empty behind a modal. Twin symptom: count-0 assertions (`table is empty`, `row not exists`) false-PASS under the same condition | Re-run `sungen generate` — table locators from sungen ≥3.2.8 emit `getByRole(…, { includeHidden: true }).filter({ visible: true })` and are immune. Do NOT edit the expected count or weaken the assertion — the rows exist; the old locator measured the wrong tree |
 | Row filter matches 0 rows | Filter text doesn't match any row content | Re-snapshot → find actual row text. Fix filter value in test-data |
 | Row filter matches multiple rows | Filter text is too generic (matches multiple rows) | Use more specific filter text (unique identifier like email, ID) |
 | Table not found | Wrong table name or table not rendered | Re-snapshot → copy exact table accessible name |
@@ -153,6 +154,16 @@ If `toHaveText` fails on an input → the Gherkin step has the wrong target type
 
 ---
 
+## API Request Errors (`@api` / catalog)
+
+| Error | Diagnosis | Fix |
+|---|---|---|
+| `400 "Unexpected field"` on a file upload | Endpoint accepts **multiple files under one field**, but the catalog declared a single file (one part sent) | In `apis.yaml`, make that `files:` field an **array** — one `:param` per file: `files: { gift_image: [":gift_image_1", ":gift_image_2"] }`. Add matching `test-data` paths. This is a real automatable case — do NOT defer to `@manual`. |
+| `415 Unsupported Media Type` on upload | Sent multipart where the endpoint wants a raw binary body (or vice-versa) | Use `bodyFile:` (raw binary body) instead of `files:` (multipart part), or the reverse — they are mutually exclusive. |
+| `fixture "…" not found` | The referenced file isn't on disk | Drop the sample file under `qa/fixtures/` and reference it by name from `test-data`. |
+
+---
+
 ## Performance & Infrastructure Errors → Fix in `specs/base.ts`
 
 All generated `.spec.ts` import from `specs/base.ts` — shared context caching, navigation, overlay cleanup. AI **can and should** tune `base.ts` to match the project.

package/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -118,6 +118,34 @@ Scenario: ...
 
 Path access on a bound result: `{{q.count}}`/`{{q.length}}`, `{{q.first.col}}`, `{{q.last.col}}`, `{{q[2].col}}`, `{{q.col}}` (= first row's col). `expect A is B` also supports `is at least` / `is at most` / `is not`. Tier-2 declarative (trivial inline, no catalog): `User see [<table>] row where [<col>] is {{v}} [has [<col2>] = "x"]`, `… no row where …`, `… count is {{n}}`. Full grammar + catalog/datasource/secret rules → **Advanced → Database** doc. Only emit DB steps when the project has a `database/` catalog / `datasources.yaml`.
 
+### Unsupported DB engine — fallback (ask, don't improvise)
+
+Direct SQL verification (`@query`, the Data Driver) only supports these engines: **`{postgres, sqlite, mysql}`**. When a datasource's `engine` (or the DB the user describes) is **outside this set** — e.g. Cosmos NoSQL, MongoDB, Cassandra, DynamoDB:
+
+1. **Do not** attempt a direct connect. **Do not** improvise a verification method.
+2. Present a fixed `AskUserQuestion` with exactly these 3 branches (always these, no others invented):
+   - **@api** — verify state via the project's internal API (route to the API driver).
+   - **@manual** — emit a `@manual` step + manual-check guidance (e.g. Cosmos Data Explorer, `az cosmosdb`, the vendor CLI).
+   - **Proxy / read-replica SQL** — if the user can supply a SQL-compatible endpoint (including Azure Cosmos DB **for PostgreSQL** / Citus), treat it as `engine: postgres` (or `mysql`) and use the normal Data Driver path above.
+3. **Recommend, don't decide.** Check the project for signals and put the best-fit branch **first**, tagged **"(Recommended)"** with a one-line reason:
+   - a project API driver / `qa/api/` catalog / `PEERCONNE_URL`-style internal API exists → **@api** first;
+   - else the user hints at a SQL-compatible replica/proxy → **proxy-SQL** first;
+   - else → **@manual** first.
+   The other two branches plus an **"Other"** option (user describes their own approach) stay available.
+4. **The user always overrides** — they may pick any branch or "Other" regardless of the recommendation.
+5. **Never auto-run** a branch and never silently pick one on the user's behalf — the question must always be asked.
+
+Example:
+```
+AskUserQuestion:
+  question: "This datasource's engine (cosmos-nosql) isn't in {postgres, sqlite, mysql} — direct SQL connect isn't supported. How should DB state be verified?"
+  options:
+    - "@api — verify via the project's internal API (Recommended: qa/api/ catalog found)"
+    - "@manual — emit a @manual step + Cosmos Data Explorer / az cosmosdb check"
+    - "Proxy / read-replica SQL — supply a SQL-compatible endpoint (e.g. Cosmos DB for PostgreSQL) → engine: postgres"
+    - "Other — describe your own verification approach"
+```
+
 ### API response assertions (optional API Driver)
 
 An `@api:<name>` call binds the response to `{{name}}` = `{ status, ok, body, headers }` (+ `ok_count`/`status_counts` under `@concurrent`). Assert with the same `expect A is B` grammar + path access:

package/src/orchestrator/templates/ai-src/skills/sungen-selector-fix/SKILL.md

@@ -282,9 +282,12 @@ Report results. Do NOT enter another fix loop here.
 | `toHaveText` / `toHaveValue` mismatch | Wrong expected data | `test-data.yaml` |
 | `page.goto` error | Wrong URL | page selector in `selectors.yaml` |
 | `frame` error | Element inside iframe | add `frame` field |
+| `role` selector resolves to 0 elements **while a dialog is open**, element visibly rendered behind it | aria-hidden trap — the modal sets `aria-hidden="true"` on the background; role locators read the a11y tree | see aria-hidden note below — NOT a name mismatch, don't churn the selector name |
 
 **Group by root cause** — if 5 tests fail because `[Submit]` button has a different name, that's 1 fix, not 5.
 
+> **aria-hidden trap** (element exists in the screenshot, locator says 0, a modal is open): compiled TABLE steps are immune from sungen ≥3.2.8 (`includeHidden` + `visible` filter) — if the failing generated code lacks that, re-run `sungen generate` first. For a **user-defined `role` selector** asserted while a dialog is open, the selector name is NOT the problem: prefer restructuring the scenario to assert after the dialog closes; if asserting behind the modal is genuinely intended, switch that selector to `testid` or an allowed `locator` CSS (both DOM-based, immune to aria-hidden). Never "fix" it by renaming the role.
+
 **Check `test-results/` first** — Playwright captures failure screenshots automatically. Use these to diagnose before any MCP exploration.
 
 ### Step 2: Targeted MCP Exploration

package/src/orchestrator/templates/specs-api.ts

@@ -80,6 +80,46 @@ export function resolveFixture(p: string, label: string): string {
   throw new Error(`API Driver: ${label} — fixture "${p}" not found (looked in ${direct} and qa/fixtures/${p}).`);
 }
 
+/**
+ * Build the multipart FormData body for a file-upload request. A field's value may be a single spec
+ * OR an array of specs — an array sends MULTIPLE files under the SAME field name, which a plain object
+ * cannot express (a repeated key would overwrite). FormData.append keeps every part, so the request
+ * carries all files. Text `body` values ride along as form fields. An empty resolved path omits that
+ * part (the missing-file / wrong-type error row). Exported for unit test (assert form.getAll entries).
+ *
+ * Blob (not File): the global File constructor only exists on Node ≥20 while this package supports
+ * Node ≥18; Blob is available on 18+. FormData wraps Blob + filename into a File part internally, so
+ * the wire result is identical.
+ */
+export function buildMultipart(
+  files: Record<string, FileSpec | FileSpec[]>,
+  body: unknown,
+  params: Record<string, any>,
+  label: string,
+): FormData {
+  const form = new FormData();
+  // Append file parts first. A field's value may be a single spec or an array (multiple files under
+  // one name); FormData.append keeps every part where a plain object would overwrite on a repeated key.
+  for (const [field, raw] of Object.entries(files)) {
+    for (const s of Array.isArray(raw) ? raw : [raw]) {
+      const spec = typeof s === 'string' ? { path: s } : s;
+      const fpath = substituteRaw(String(spec.path), params);
+      if (!fpath) continue; // empty param → omit the part (a missing-file / wrong-type error row)
+      const resolved = resolveFixture(fpath, label);
+      const filename = spec.filename ?? path.basename(resolved);
+      const blob = new Blob([fs.readFileSync(resolved)], { type: spec.mimeType ?? inferMime(filename) });
+      form.append(spec.name ?? field, blob, filename);
+    }
+  }
+  // Text body fields ride along — but skip any name already added as a file part, so a catalog that
+  // declares the same key in both body: and files: sends ONE part (the file wins), matching the prior
+  // plain-object behaviour rather than emitting a duplicate field a strict server would reject.
+  if (body && typeof body === 'object')
+    for (const [k, v] of Object.entries(body as Record<string, unknown>))
+      if (!form.has(k)) form.append(k, typeof v === 'string' ? v : JSON.stringify(v));
+  return form;
+}
+
 /**
  * Join a datasource base URL with a catalog path. Concatenate rather than rely on Playwright's
  * baseURL resolution: an absolute path (`/user/1`) resolves against the base ORIGIN and would drop
@@ -113,7 +153,7 @@ class ApiClient {
    */
   async call(
     label: string,
-    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; files?: Record<string, FileSpec>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string },
+    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string },
     params: Record<string, any> = {},
     opts: { storageState?: string } = {},
   ): Promise<{ status: number; ok: boolean; body: any; headers: Record<string, string> }> {
@@ -150,21 +190,10 @@ class ApiClient {
         headers['content-type'] = spec.mimeType ?? 'application/octet-stream';
       }
     } else if (req.files && Object.keys(req.files).length) {
-      const mp: Record<string, any> = {};
-      if (body && typeof body === 'object')
-        for (const [k, v] of Object.entries(body as Record<string, unknown>)) mp[k] = typeof v === 'string' ? v : JSON.stringify(v);
-      for (const [field, raw] of Object.entries(req.files)) {
-        const spec = typeof raw === 'string' ? { path: raw } : raw;
-        const fpath = substituteRaw(String(spec.path), params);
-        if (!fpath) continue; // empty param → omit the part (a missing-file / wrong-type error row)
-        const resolved = resolveFixture(fpath, label);
-        const filename = spec.filename ?? path.basename(resolved);
-        mp[spec.name ?? field] = { name: filename, mimeType: spec.mimeType ?? inferMime(filename), buffer: fs.readFileSync(resolved) };
-      }
       // Playwright generates the multipart/form-data Content-Type (with boundary); drop any datasource
       // default Content-Type so it doesn't conflict with / duplicate the generated one.
       deleteHeader(headers, 'content-type');
-      bodyOpt.multipart = mp;
+      bodyOpt.multipart = buildMultipart(req.files, body, params, label);
     } else if (body !== undefined) {
       const enc = req.encoding ?? 'json';
       if (enc === 'form') bodyOpt.form = body;
@@ -201,7 +230,7 @@ class ApiClient {
    */
   async callN(
     label: string,
-    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; files?: Record<string, FileSpec>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string },
+    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string },
     params: Record<string, any> = {},
     n = 1,
     opts: { storageState?: string } = {},

package/src/orchestrator/templates/specs-db.ts

@@ -6,7 +6,7 @@
  * table/column identifiers are validated against a strict allowlist pattern (identifiers
  * can't be bound as parameters). Secrets come from .env.qa / process.env, never inline.
  *
- * Engines: PostgreSQL (`pg`) and SQLite (`better-sqlite3`), lazy-loaded on first use.
+ * Engines: PostgreSQL (`pg`), MySQL (`mysql2`), and SQLite (`better-sqlite3`), lazy-loaded on first use.
  * Config: a `datasources.yaml` at the project root (or qa/), with ${VAR} resolved from env.
  *
  * DO NOT EDIT — regenerated by `sungen generate`.
@@ -21,6 +21,10 @@ const ident = (s: string): string => {
   return s;
 };
 
+// Single source of truth for the "not supported" error message below and for the mysql/sqlite
+// placeholder rewrite condition (`rewritePlaceholders`) — keep engine names in sync with `DataSourceConfig.engine`.
+const SUPPORTED_ENGINES = ['postgres', 'sqlite', 'mysql'] as const;
+
 interface SshConfig {
   host: string;              // jump host reachable from the runner
   port?: number;             // default 22
@@ -37,8 +41,8 @@ interface DataSourceConfig {
   readonly?: boolean;
   statement_timeout_ms?: number;
   max_rows?: number;
-  // Cách B (fallback): tunnel the DB SOCKET through an SSH bastion. DB-only — the browser/E2E
-  // still run on the runner; only PG traffic crosses. See docs/spec/sungen_data_driver_ssh_tunnel_spec.md.
+  // Fallback path: tunnel the DB SOCKET through an SSH bastion. DB-only — the browser/E2E
+  // still run on the runner; only DB traffic crosses. See docs/spec/sungen_data_driver_ssh_tunnel_spec.md.
   ssh?: SshConfig;
 }
 
@@ -120,12 +124,38 @@ function loadConfig(): Record<string, DataSourceConfig> {
   return doc.datasources;
 }
 
+/**
+ * `build()` always emits PG-style `$1..$n` placeholders; mysql2/better-sqlite3 both bind with `?`.
+ * Only real placeholders are rewritten — a `$1` sitting inside a single-quoted string literal (e.g.
+ * a catalog query `WHERE label = '$1 off'`) is left untouched. SQL escapes an inner quote by doubling
+ * it (`''`), which the simple in-string toggle handles (an even number of quotes returns to the same state).
+ */
+export function rewritePlaceholders(engine: string, sql: string): string {
+  if (engine !== 'sqlite' && engine !== 'mysql') return sql;
+  let out = '';
+  let inStr = false;
+  for (let i = 0; i < sql.length; i++) {
+    const c = sql[i];
+    if (c === "'") { inStr = !inStr; out += c; continue; }
+    if (!inStr && c === '$' && sql[i + 1] >= '0' && sql[i + 1] <= '9') {
+      let j = i + 1;
+      while (j < sql.length && sql[j] >= '0' && sql[j] <= '9') j++;
+      out += '?';
+      i = j - 1;
+      continue;
+    }
+    out += c;
+  }
+  return out;
+}
+
 type Engine = { query(sql: string, params: any[]): Promise<any[]>; };
 
 class DataSource {
   private configs: Record<string, DataSourceConfig> | null = null;
   private engines = new Map<string, Engine>();
   private tunnels: Array<{ close: () => void }> = [];
+  private mysqlPools: Array<{ end: () => Promise<void> }> = [];
 
   private cfg(name?: string): { key: string; conf: DataSourceConfig } {
     if (!this.configs) this.configs = loadConfig();
@@ -142,7 +172,7 @@ class DataSource {
     let engine: Engine;
     if (conf.engine === 'postgres') {
       let connectionString = conf.url;
-      if (conf.ssh) {                                   // Cách B: tunnel the DB socket through a bastion
+      if (conf.ssh) {                                   // Fallback path: tunnel the DB socket through a bastion
         const u = new URL(conf.url);
         const t = await openSshTunnel(conf.ssh, u.hostname, Number(u.port || 5432));
         this.tunnels.push(t);
@@ -152,20 +182,59 @@ class DataSource {
       const { Pool } = require('pg');
       const pool = new Pool({ connectionString, max: 2, statement_timeout: conf.statement_timeout_ms ?? 4000 });
       engine = { query: async (sql, params) => (await pool.query(sql, params)).rows };
+    } else if (conf.engine === 'mysql') {
+      let connectionString = conf.url;
+      if (conf.ssh) {                                   // Fallback path: tunnel the DB socket through a bastion
+        const u = new URL(conf.url);
+        const t = await openSshTunnel(conf.ssh, u.hostname, Number(u.port || 3306));
+        this.tunnels.push(t);
+        u.hostname = t.host; u.port = String(t.port);   // rewrite host:port → 127.0.0.1:<tunnel> (keep user/pass/db/query)
+        connectionString = u.toString();
+      }
+      const mysql = require('mysql2/promise');
+      const pool = mysql.createPool({ uri: connectionString, connectionLimit: 2 });
+      this.mysqlPools.push(pool);
+      // mysql2 ignores the mysqljs per-query `timeout` field, and destroying the connection does
+      // not interrupt an in-flight query — so bound the wait client-side by racing the query
+      // against a timer. On overrun we reject and destroy the connection (removes it from the pool
+      // rather than releasing a still-busy socket); on success we release it back.
+      const timeoutMs = conf.statement_timeout_ms ?? 4000;
+      engine = {
+        query: async (sql, params) => {
+          const conn = await pool.getConnection();
+          const qp = conn.query(sql, params);
+          qp.catch(() => { /* swallow the post-timeout rejection from the abandoned query */ });
+          let timer: NodeJS.Timeout | undefined;
+          let timedOut = false;
+          const guard = new Promise<never>((_, reject) => {
+            timer = setTimeout(() => { timedOut = true; reject(new Error(`Data Driver: mysql query exceeded ${timeoutMs}ms — aborted.`)); }, timeoutMs);
+          });
+          try {
+            const [rows] = await Promise.race([qp, guard]);
+            return rows as any[];
+          } finally {
+            clearTimeout(timer);
+            if (timedOut) { try { conn.destroy(); } catch { /* best-effort */ } }
+            else { try { conn.release(); } catch { /* already gone */ } }
+          }
+        },
+      };
     } else if (conf.engine === 'sqlite') {
       if (conf.ssh) console.warn(`Data Driver: datasource "${key}" sets ssh: but engine is sqlite (file-based) — ssh ignored.`);
       const Database = require('better-sqlite3');
       const db = new Database(conf.url.replace(/^sqlite:/, ''), { readonly: conf.readonly !== false });
       engine = { query: async (sql, params) => db.prepare(sql).all(...params) };
     } else {
-      throw new Error(`Data Driver: engine "${conf.engine}" not supported yet (postgres | sqlite).`);
+      throw new Error(`Data Driver: engine "${conf.engine}" not supported (supported: ${SUPPORTED_ENGINES.join(' | ')}). For non-SQL stores (Cosmos NoSQL, Mongo…) verify via @api or @manual.`);
     }
     this.engines.set(key, engine);
     return { engine, conf };
   }
 
-  /** Close any open SSH tunnels (optional explicit teardown; tunnels are unref'd so the process exits regardless). */
+  /** Close open MySQL pools + SSH tunnels (optional explicit teardown; tunnels are unref'd so the process exits regardless). */
   close(): void {
+    for (const p of this.mysqlPools) { try { void p.end(); } catch { /* best-effort */ } }
+    this.mysqlPools = [];
     for (const t of this.tunnels) t.close();
     this.tunnels = [];
   }
@@ -211,9 +280,9 @@ class DataSource {
     expect(n, `Expected ${count} row(s) in "${table}"${cols.length ? ' where ' + desc(filter) : ''} — found ${n}`).toBe(Number(count));
   }
 
-  /** Rewrites $1/$2 placeholders to `?` for SQLite. */
+  /** Rewrites $1/$2 placeholders to `?` for engines that don't support PG-style positional params. */
   private sqlFor(conf: DataSourceConfig, sql: string): string {
-    return conf.engine === 'sqlite' ? sql.replace(/\$\d+/g, '?') : sql;
+    return rewritePlaceholders(conf.engine, sql);
   }
 
   // --- Named queries (catalog-backed; SQL is resolved + embedded at compile time) -----------