@sun-asterisk/sungen 3.2.7 → 3.2.8

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/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 };
 }

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/column-cell-assertion.hbs

@@ -1,3 +1,3 @@
-await expect({{> locator}}.getByRole('columnheader', { name: '{{columnName}}' })).toBeVisible();
-const {{columnIndexVar}} = (await page.getByRole('columnheader').allTextContents()).findIndex(h => h.includes('{{columnName}}'));
-await expect(page.getByRole('row').nth({{rowNth}}).getByRole('cell').nth({{columnIndexVar}})).toHaveText('{{dataValue}}');
+await expect({{> locator}}.getByRole('columnheader', { name: '{{columnName}}', includeHidden: true })).toBeVisible();
+const {{columnIndexVar}} = (await page.getByRole('columnheader', { includeHidden: true }).filter({ visible: true }).allTextContents()).findIndex(h => h.includes('{{columnName}}'));
+await expect(page.getByRole('row', { includeHidden: true }).filter({ visible: true }).nth({{rowNth}}).getByRole('cell', { includeHidden: true }).filter({ visible: true }).nth({{columnIndexVar}})).toHaveText('{{dataValue}}');

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

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

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/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-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 } = {},