@skyramp/testbot-core 0.13.0-v3.179 → 0.13.0-v3.181

package/assets/skyramp-api/gen.cjs

@@ -0,0 +1,247 @@
+/**
+ * Skyramp backend API helper (testbot exp/skyramp-api). Generates a Skyramp contract, integration or fuzz test through
+ * the Skyramp MCP package's own generation path (ContractTestService / IntegrationTestService / FuzzTestService, the
+ * classes behind its generation tools, called directly: no MCP server, no protocol), so the options are built and the
+ * workspace's auth, TLS and query params resolved exactly as the MCP tools do.
+ *
+ *   const api = require(process.env.SKYRAMP_API);
+ *   // one request: a contract test
+ *   const { test } = await api.generate({ kind: "contract", baseUrl: "http://localhost:8000", endpoint: "/api/v1/products",
+ *     method: "POST", requestData: { name: "Lamp", price: 10 }, responseData: { id: 7, name: "Lamp", price: 10 },
+ *     statusCode: 201, language: "python", framework: "pytest", outputDir: "tests/api", output: "test_products.py" });
+ *   // several requests: a trace built from the steps, then an integration test from it
+ *   const trace = await api.trace([
+ *     { method: "POST", path: "/api/v1/products", request: { name: "Lamp" }, status: 201, response: { id: 7, name: "Lamp" } },
+ *     { method: "GET", path: "/api/v1/products/{{1.id}}", status: 200, response: { id: 7, name: "Lamp" } },
+ *   ], { baseUrl: "http://localhost:8000", authHeader: "Authorization", authScheme: "Bearer" });
+ *   await api.generate({ kind: "integration", trace, language: "python", framework: "pytest", outputDir: "tests/api", output: "test_product_flow.py" });
+ *
+ * `{{N.field}}` in a step's path, query or request is the value of `field` (dotted) in step N's response (1-based). The
+ * trace then carries the real value, and the generator chains it: the test reads it from that step's response.
+ * `schema` (a spec path or URL) may stand in for requestData/responseData in a contract or fuzz test.
+ *
+ * Generation needs the Skyramp licence; the generated tests do not. The licence reaches only the generation call:
+ * SKYRAMP_API_LICENSE_FILE (a path) or SKYRAMP_API_TOKEN_FILE (a file holding a run token) go into this process's env
+ * for the call and come out after it. Each generated test is copied, as generated, to SKYRAMP_API_DRAFTS and logged to
+ * SKYRAMP_API_LOG: that copy is what the finished test is compared with.
+ */
+"use strict";
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+const { pathToFileURL } = require("url");
+
+const SERVICES = {
+  contract: ["tools/generate-tests/generateContractRestTool.js", "ContractTestService"],
+  integration: ["tools/generate-tests/generateIntegrationRestTool.js", "IntegrationTestService"],
+  fuzz: ["tools/generate-tests/generateFuzzRestTool.js", "FuzzTestService"],
+};
+
+const mcpModule = (rel) => {
+  const root = process.env.SKYRAMP_API_MCP;
+  if (!root) throw new Error("SKYRAMP_API_MCP is not set: the Skyramp MCP package was not found");
+  return import(pathToFileURL(path.join(root, "build", rel)).href);
+};
+
+const roots = () => [process.env.SKYRAMP_API_SDK, ...(process.env.NODE_PATH || "").split(path.delimiter)].filter(Boolean);
+/** A client of the SDK the session resolved (SKYRAMP_API_SDK first), else undefined and the MCP package's own is used. */
+const sdkClient = () => {
+  for (const d of roots()) {
+    try {
+      return new (require(require.resolve("@skyramp/skyramp", { paths: [d] })).SkyrampClient)();
+    } catch { /* next */ }
+  }
+  return undefined;
+};
+
+/** The value at a dotted path of a parsed JSON value, or undefined. */
+const at = (value, dotted) => dotted.split(".").reduce((v, k) => (v == null ? undefined : v[k]), value);
+
+const REF = /\{\{\s*(\d+)\.([\w.-]+)\s*\}\}/g;
+/**
+ * `value` with each `{{N.field}}` replaced by that field of step N's response. A string that is one reference keeps
+ * the referenced value's type (an id stays a number in a request body); one inside other text becomes text.
+ */
+function resolveRefs(value, responses) {
+  const lookup = (n, field) => {
+    const r = responses[Number(n) - 1];
+    const v = r === undefined ? undefined : at(r, field);
+    if (v === undefined) throw new Error(`{{${n}.${field}}}: step ${n} has no response field ${field}`);
+    return v;
+  };
+  if (typeof value === "string") {
+    const whole = value.match(/^\{\{\s*(\d+)\.([\w.-]+)\s*\}\}$/);
+    if (whole) return lookup(whole[1], whole[2]);
+    return value.replace(REF, (_, n, field) => String(lookup(n, field)));
+  }
+  if (Array.isArray(value)) return value.map((v) => resolveRefs(v, responses));
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolveRefs(v, responses)]));
+  return value;
+}
+
+const asJson = (v) => (v === undefined ? undefined : typeof v === "string" ? v : JSON.stringify(v));
+const parsed = (v) => {
+  if (typeof v !== "string") return v;
+  try { return JSON.parse(v); } catch { return v; }
+};
+
+/**
+ * The trace requests for the plan's steps, in order. Pure: `toEntry` makes one trace request from one step's
+ * parameters (in `trace`, the MCP package's ScenarioGenerationService.generateTraceRequestFromInput). Each step has a
+ * method and a path, and optionally request (body), query (object), status and response (body).
+ */
+function traceEntries(steps, opts, toEntry) {
+  if (!Array.isArray(steps) || steps.length === 0) throw new Error("a trace needs at least one step");
+  if (!opts || !opts.baseUrl) throw new Error("a trace needs the app's baseUrl");
+  const host = new URL(opts.baseUrl).hostname;
+  const responses = [];
+  return steps.map((s, i) => {
+    if (!s || !s.method || !s.path) throw new Error(`step ${i + 1} needs a method and a path`);
+    const stepPath = resolveRefs(String(s.path), responses);
+    const request = resolveRefs(s.request, responses);
+    const query = resolveRefs(s.query, responses);
+    responses.push(parsed(s.response));
+    const entry = toEntry({
+      scenarioName: opts.name || "testbot-plan",
+      destination: host,
+      baseURL: opts.baseUrl,
+      method: String(s.method).toUpperCase(),
+      path: stepPath,
+      requestBody: asJson(request),
+      queryParams: asJson(query),
+      responseBody: asJson(s.response),
+      statusCode: s.status === undefined ? undefined : Number(s.status),
+      authHeader: opts.authHeader,
+      authScheme: opts.authScheme,
+    });
+    if (!entry) throw new Error(`step ${i + 1} (${s.method} ${s.path}) could not be made a trace request`);
+    return entry;
+  });
+}
+
+const draftsDir = () => process.env.SKYRAMP_API_DRAFTS || path.join(os.tmpdir(), "skyramp-api-drafts");
+
+/** Write the trace for `steps` to a file (opts.file, else beside the drafts) and return its path. */
+async function trace(steps, opts = {}) {
+  const { ScenarioGenerationService } = await mcpModule("services/ScenarioGenerationService.js");
+  const service = new ScenarioGenerationService();
+  const entries = traceEntries(steps, opts, (p) => service.generateTraceRequestFromInput(p));
+  const file = path.resolve(opts.file || path.join(draftsDir(), `trace-${Date.now()}.json`));
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(entries, null, 2));
+  return file;
+}
+
+let generating = Promise.resolve();
+
+/**
+ * Run `fn` with the licence in this process's env, and restore the env after it. Calls run one at a time: with
+ * `Promise.all(cases.map(api.generate))`, one call's restore would otherwise take the token from another mid-call.
+ */
+function withLicence(fn) {
+  const run = async () => {
+    const saved = { LICENSE_FILE: process.env.LICENSE_FILE, SKYRAMP_RUN_TOKEN: process.env.SKYRAMP_RUN_TOKEN, CI: process.env.CI };
+    const tokenFile = process.env.SKYRAMP_API_TOKEN_FILE;
+    const licence = process.env.SKYRAMP_API_LICENSE_FILE;
+    if (tokenFile) process.env.SKYRAMP_RUN_TOKEN = fs.readFileSync(tokenFile, "utf-8").trim();
+    else if (licence) process.env.LICENSE_FILE = licence;
+    if (tokenFile || licence) process.env.CI = "true";
+    try {
+      return await fn();
+    } finally {
+      for (const [k, v] of Object.entries(saved)) {
+        if (v === undefined) delete process.env[k];
+        else process.env[k] = v;
+      }
+    }
+  };
+  const next = generating.then(run, run);
+  generating = next.catch(() => {});
+  return next;
+}
+
+/** Is this output name one Skyramp's generator writes as asked: anything but a TS/JS Playwright test, or one named *.{spec,test}.*? */
+function playwrightName(opts) {
+  const node = /^(typescript|javascript)$/i.test(String(opts.language || "")) && (!opts.framework || /playwright/i.test(opts.framework));
+  return !node || /\.(spec|test)\.[cm]?[jt]s$/.test(opts.output) || !/\.[cm]?[jt]s$/.test(opts.output);
+}
+
+/** Did an earlier generation of this run write `file` (the log names it)? Only such a file may be generated over. */
+function helperWrote(file) {
+  const at = process.env.SKYRAMP_API_LOG;
+  if (!at || !fs.existsSync(at)) return false;
+  return fs.readFileSync(at, "utf-8").split("\n").some((line) => {
+    try { return path.resolve(JSON.parse(line).test || "") === file; } catch { return false; }
+  });
+}
+
+const log = (record) => {
+  if (process.env.SKYRAMP_API_LOG) fs.appendFileSync(process.env.SKYRAMP_API_LOG, JSON.stringify({ at: new Date().toISOString(), ...record }) + "\n");
+};
+
+/**
+ * Generate one test and return { test, draft }: the file written in outputDir, and its copy as generated. Throws
+ * with the generator's message when generation fails.
+ */
+async function generate(opts) {
+  const spec = SERVICES[opts && opts.kind];
+  if (!spec) throw new Error(`kind must be one of ${Object.keys(SERVICES).join(", ")}`);
+  if (!opts.outputDir || !opts.output) throw new Error("outputDir and output are required");
+  if (!opts.trace && !(opts.baseUrl && opts.endpoint)) throw new Error("give baseUrl and endpoint, or (integration) a trace");
+  const outputDir = path.resolve(opts.outputDir);
+  const target = path.join(outputDir, opts.output);
+  // Skyramp's generator takes a Playwright test only as *.{spec,test}.{ts,js}; a name the target's runner wants
+  // otherwise (the Testbot package's *.e2e.ts) is generated under an accepted one, then renamed to it.
+  const asGenerated = playwrightName(opts) ? opts.output : opts.output.replace(/(\.e2e)?\.([cm]?[jt]s)$/, ".spec.$2");
+  const generatedAt = path.join(outputDir, asGenerated);
+  if (asGenerated !== opts.output && fs.existsSync(generatedAt) && !helperWrote(generatedAt))
+    throw new Error(`${generatedAt} exists and the helper did not write it: generate under a new name`);
+  if (fs.existsSync(target) && !helperWrote(target))
+    throw new Error(`${target} exists and the helper did not write it: generate under a new name, or add the case to that test by hand (no draft needed)`);
+  const params = {
+    ...(opts.trace
+      ? { trace: path.resolve(opts.trace) }
+      : { endpointURL: `${String(opts.baseUrl).replace(/\/$/, "")}${opts.endpoint}`, method: String(opts.method || "GET").toUpperCase() }),
+    ...(opts.schema ? { apiSchema: opts.schema } : {}),
+    ...(opts.requestData !== undefined ? { requestData: asJson(opts.requestData) } : {}),
+    ...(opts.responseData !== undefined ? { responseData: asJson(opts.responseData) } : {}),
+    ...(opts.statusCode !== undefined ? { responseStatusCode: String(opts.statusCode) } : {}),
+    // Left out, the MCP's generation resolves it from the workspace; "" is no auth header.
+    ...(opts.authHeader !== undefined ? { authHeader: opts.authHeader } : {}),
+    ...(opts.authScheme !== undefined ? { authScheme: opts.authScheme } : {}),
+    ...(opts.chainingKey ? { chainingKey: opts.chainingKey } : {}),
+    ...(opts.pathParams ? { pathParams: opts.pathParams } : {}),
+    ...(opts.queryParams ? { queryParams: opts.queryParams } : {}),
+    language: opts.language,
+    ...(opts.framework ? { framework: opts.framework } : {}),
+    outputDir,
+    output: asGenerated,
+    force: true,
+  };
+  const record = { kind: opts.kind, method: params.method, endpoint: opts.endpoint, trace: params.trace };
+  try {
+    const [{ [spec[1]]: Service }, { generatedFilesFrom }] = await Promise.all([mcpModule(spec[0]), mcpModule("services/TestGenerationService.js")]);
+    const service = new Service();
+    const client = sdkClient();
+    if (client) service.client = client;
+    const result = await withLicence(() => service.generateTest(params));
+    const text = (result.content || []).map((c) => c.text || "").join("\n");
+    if (result.isError) throw new Error(`Skyramp generation failed: ${text.trim().split("\n")[0] || "no message"}`);
+    let test = generatedFilesFrom(text)[0] || generatedAt;
+    if (!fs.existsSync(test)) throw new Error(`Skyramp generation reported success but wrote no ${test}`);
+    if (path.resolve(test) === generatedAt && generatedAt !== target) {
+      fs.renameSync(generatedAt, target);
+      test = target;
+    }
+    fs.mkdirSync(draftsDir(), { recursive: true });
+    const draft = path.join(draftsDir(), `${Date.now()}-${path.basename(test)}`);
+    fs.copyFileSync(test, draft);
+    log({ ...record, test, draft });
+    return { test, draft };
+  } catch (e) {
+    log({ ...record, error: String((e && e.message) || e).split("\n")[0] });
+    throw e;
+  }
+}
+
+module.exports = { generate, trace, traceEntries, resolveRefs, _internal: { withLicence } };

package/assets/skyramp-walk/walk.cjs

@@ -0,0 +1,321 @@
+/**
+ * Skyramp walk helper (testbot exp/skyramp-ui). Walk a browser test once against the running app; the helper records
+ * it the way Skyramp's recorder does and generates a Skyramp Playwright test from it.
+ *
+ *   const { walk } = require(process.env.SKYRAMP_WALK);
+ *   await walk({ baseUrl: "http://localhost:5173", apiHosts: ["localhost:8000"],
+ *                outputDir: "e2e", output: "add_product.spec.ts", language: "typescript" }, async (w) => {
+ *     await w.goto("/products");
+ *     await w.click("page.getByRole('button', { name: 'Add Product' })");
+ *     await w.fill("page.getByPlaceholder('e.g. Apple Macbook Pro')", "Desk Lamp");
+ *     w.expectRequest();                       // the next action's request body is checked in the test
+ *     await w.click("page.getByRole('button', { name: 'Submit' })");
+ *     await w.expectText("page.getByRole('heading').first()", "Product Details");
+ *   });
+ *
+ * Other options: actionTimeoutMs (each action, default 10 s), checkTimeoutMs (each expect*, retried until it holds,
+ * default 5 s), navigationTimeoutMs (goto, default 30 s), settleMs (after each action, default 800 ms).
+ *
+ * When a step fails, the error names the step, its action and expression, the page URL and a short accessibility
+ * snapshot of the page to fix the selector from, and the steps recorded before it are written as a partial recording.
+ *
+ * Three things make Skyramp tie each action to the request it caused, and so write the request-body check:
+ * - each action is stamped when it starts, so the request it fires falls in its own window;
+ * - every API call passes through a route while recording, so its response body is kept even when the page navigates
+ *   the moment it arrives (Playwright's HAR drops it otherwise, and the export keeps only entries with a JSON body);
+ * - expectRequest() records Skyramp's request-body marker before the action whose request matters.
+ * Generation needs @skyramp/skyramp 1.3.52 or later (SKYRAMP_WALK_SDK, else NODE_PATH).
+ */
+"use strict";
+const path = require("path");
+const fs = require("fs");
+
+const req = (name, dirs) => {
+  for (const d of dirs.filter(Boolean)) {
+    try { return require(require.resolve(name, { paths: [d] })); } catch { /* next */ }
+  }
+  return require(name);
+};
+const roots = () => [process.env.SKYRAMP_WALK_SDK, ...(process.env.NODE_PATH || "").split(path.delimiter)];
+
+/**
+ * The fork's Playwright, launching the Chromium walk.ts installed for it (SKYRAMP_WALK_BROWSERS_PATH) rather than
+ * whatever a repo's PLAYWRIGHT_BROWSERS_PATH points at. Playwright reads that variable once, as it loads.
+ */
+function loadPlaywright(load = () => req("playwright", roots())) {
+  const want = process.env.SKYRAMP_WALK_BROWSERS_PATH;
+  const prev = process.env.PLAYWRIGHT_BROWSERS_PATH;
+  if (want) process.env.PLAYWRIGHT_BROWSERS_PATH = want;
+  try {
+    return load();
+  } finally {
+    if (want) {
+      if (prev === undefined) delete process.env.PLAYWRIGHT_BROWSERS_PATH;
+      else process.env.PLAYWRIGHT_BROWSERS_PATH = prev;
+    }
+  }
+}
+
+const firstLines = (s, n) => String(s ?? "").split("\n").slice(0, n).join("\n");
+
+/** Run attempt until it stops throwing or timeoutMs passes; attempt gets the time left. The last error is thrown. */
+async function retryUntil(attempt, timeoutMs, { now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  const deadline = now() + timeoutMs;
+  const waits = [100, 250, 500, 1000];
+  for (let i = 0; ; i++) {
+    try {
+      return await attempt(Math.max(1, deadline - now()));
+    } catch (e) {
+      const left = deadline - now();
+      if (left <= 0) throw e;
+      await sleep(Math.min(waits[Math.min(i, waits.length - 1)], left));
+    }
+  }
+}
+
+/**
+ * The API route: fetch the request so its response body is kept, and fulfil it with that response. Navigations pass
+ * straight through, a redirect goes back to the browser to follow, and when the fetch fails (the page is closing, or
+ * Node cannot reach the server the browser can) the request continues untouched instead of failing the walk.
+ */
+function apiRoute(state, warn = (m) => process.stderr.write(`${m}\n`)) {
+  const pass = (route) => route.continue().catch(() => { /* already handled, or the page is gone */ });
+  return async (route) => {
+    const request = route.request();
+    if (state.closing || request.isNavigationRequest()) return pass(route);
+    let response;
+    try {
+      response = await route.fetch({ maxRedirects: 0 });
+    } catch (e) {
+      if (!state.closing) warn(`skyramp walk: ${request.method()} ${request.url()} went through without its response kept (${firstLines(e && e.message, 1)})`);
+      return pass(route);
+    }
+    try {
+      await route.fulfill({ response, body: await response.body() });
+    } catch {
+      /* the page is gone; the request was made already, so it is not sent again */
+    }
+  };
+}
+
+/** A step's failure, with what the agent needs to fix it: the step, the page URL and its accessibility snapshot. */
+function stepFailure({ step, label, url, snapshot, error }, maxSnapshot = 3000) {
+  const snap = snapshot.length > maxSnapshot ? `${snapshot.slice(0, maxSnapshot)}\n… (${snapshot.length - maxSnapshot} more characters)` : snapshot;
+  const e = new Error(
+    `walk step ${step} failed: ${label}\n${firstLines(error && error.message, 6)}\npage: ${url || "(none)"}\n` +
+      `accessibility snapshot of the page (fix the selector from it):\n${snap.replace(/^/gm, "  ")}`,
+    { cause: error },
+  );
+  e.walkStep = step;
+  return e;
+}
+
+/**
+ * The fork's own serialisation of a locator expression ("page.getByTestId('x').first()"), as its export writes a
+ * click on it: { expr, selector, locator }, or undefined when the export cannot express it. The export's assertions
+ * map only test-id, role and text selectors, so each assertion's locator comes from here instead.
+ */
+function forkLocator(exp, expr) {
+  if (!expr || !/^page\./.test(expr)) return undefined;
+  const { jsonl } = exp.buildJsonlContent([{ toolName: "browser_click", args: {}, code: `await ${expr}.click();`, timestamp: 1, pageAlias: "page" }], "chromium", "");
+  for (const line of jsonl.split("\n")) {
+    if (!line) continue;
+    const o = JSON.parse(line);
+    if (o.name === "click" && o.locator && o.locator.kind) return { expr, selector: o.selector, locator: o.locator };
+  }
+  return undefined;
+}
+
+/**
+ * The locator in a form the export can express: Playwright's own print of it (single-quoted, which is what the export
+ * parses), else the agent's expression as written; undefined when neither. The export drops what it cannot parse (a
+ * filter, a role's level) without a word, so a form counts only when its selector is the live locator's own.
+ */
+function exportable(exp, expr, loc) {
+  let canonical;
+  let live;
+  try {
+    if (loc && typeof loc._selector === "string") {
+      live = loc._selector;
+      canonical = `page.${String(loc)}`;
+    }
+  } catch { /* not a locator */ }
+  for (const form of [canonical, expr]) {
+    const got = forkLocator(exp, form);
+    if (got && (live === undefined || got.selector === live)) return got;
+  }
+  return undefined;
+}
+
+const ASSERTS = new Set(["assertText", "assertVisible", "assertValue", "assertCount", "assertChecked", "assertDisabled"]);
+
+/** Give each assertion line the locator recorded for it (found by its timestamp) in place of the export's mapping. */
+function patchAssertLocators(jsonl, byTimestamp) {
+  return jsonl
+    .split("\n")
+    .map((line) => {
+      if (!line) return line;
+      const o = JSON.parse(line);
+      const got = ASSERTS.has(o.name) && byTimestamp.get(Number(o.timestamp));
+      return got ? JSON.stringify({ ...o, selector: got.selector, locator: got.locator }) : line;
+    })
+    .join("\n");
+}
+
+const EXPORTABLE = "getByTestId, getByRole, getByText, getByLabel, getByPlaceholder, getByAltText, getByTitle, locator('css'), chains of these, .first() and .nth(n)";
+
+let generating = Promise.resolve();
+
+/**
+ * Run `fn` with the walk's credential in this process's env (a run token from SKYRAMP_WALK_TOKEN_FILE, else
+ * SKYRAMP_WALK_LICENSE_FILE, else a local SKYRAMP_LICENSE_FILE), and restore the env after it. Calls run one at a
+ * time, so walks started together never see another's restore.
+ */
+function withCredential(fn) {
+  const run = async () => {
+    const saved = { LICENSE_FILE: process.env.LICENSE_FILE, SKYRAMP_RUN_TOKEN: process.env.SKYRAMP_RUN_TOKEN, CI: process.env.CI };
+    const tokenFile = process.env.SKYRAMP_WALK_TOKEN_FILE;
+    const licence = process.env.SKYRAMP_WALK_LICENSE_FILE || (!process.env.LICENSE_FILE && process.env.SKYRAMP_LICENSE_FILE);
+    if (tokenFile) process.env.SKYRAMP_RUN_TOKEN = fs.readFileSync(tokenFile, "utf-8").trim();
+    else if (licence) process.env.LICENSE_FILE = licence;
+    if (tokenFile || licence) process.env.CI = "true";
+    try {
+      return await fn();
+    } finally {
+      for (const [k, v] of Object.entries(saved)) {
+        if (v === undefined) delete process.env[k];
+        else process.env[k] = v;
+      }
+    }
+  };
+  const next = generating.then(run, run);
+  generating = next.catch(() => {});
+  return next;
+}
+
+async function walk(opts, body) {
+  const { chromium } = loadPlaywright();
+  const exp = req("playwright/lib/mcp/skyramp", roots());
+  const { SkyrampClient } = req("@skyramp/skyramp", roots());
+  const scratch = fs.mkdtempSync(path.join(require("os").tmpdir(), "skyramp-walk-"));
+  const zip = opts.zip || path.join(scratch, "walk.zip");
+  const har = path.join(scratch, "walk.har");
+  const checkTimeout = opts.checkTimeoutMs ?? 5_000;
+  const browser = await chromium.launch({ headless: opts.headless !== false });
+  const context = await browser.newContext({ recordHar: { path: har, mode: "minimal" }, viewport: { width: 1280, height: 720 }, ...(opts.storageState ? { storageState: opts.storageState } : {}) });
+  context.setDefaultTimeout(opts.actionTimeoutMs ?? 10_000);
+  context.setDefaultNavigationTimeout(opts.navigationTimeoutMs ?? 30_000);
+  const state = { closing: false };
+  const hosts = opts.apiHosts || [];
+  if (hosts.length)
+    // A pattern, not a predicate: the URL-predicate form did not intercept these requests in the Skyramp fork.
+    await context.route(new RegExp(`^https?://(?:${hosts.map((h) => h.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})(?:[/?#]|$)`), apiRoute(state));
+  const page = await context.newPage();
+  const actions = [];
+  const checks = new Map();
+  const leftOut = [];
+  let last = 0;
+  // Timestamps are unique, so each assertion line can be found again in the export by its own.
+  const push = (toolName, args, code = "", timestamp = Date.now()) => {
+    const t = Math.max(timestamp, last + 1);
+    last = t;
+    actions.push({ toolName, args, code, timestamp: t, pageAlias: "page" });
+    return t;
+  };
+  const omit = (k, what, expr) => {
+    leftOut.push({ step: k, expr });
+    process.stderr.write(`skyramp walk: step ${k}: Skyramp's export cannot write ${what} on ${expr}, so the generated test leaves it out; use ${EXPORTABLE}, or add it to the test by hand\n`);
+  };
+  const at = (expr) => new Function("page", `return (${expr});`)(page);
+  const settle = () => page.waitForTimeout(opts.settleMs ?? 800);
+  let n = 0;
+  const step = async (label, run) => {
+    const k = ++n;
+    try {
+      return await run(k);
+    } catch (error) {
+      let url = "";
+      let snapshot = "";
+      try { url = page.url(); } catch { /* closed */ }
+      try { snapshot = await page.locator("body").ariaSnapshot({ timeout: 2000 }); } catch (s) { snapshot = `(no snapshot: ${firstLines(s && s.message, 1)})`; }
+      throw stepFailure({ step: k, label, url, snapshot, error });
+    }
+  };
+  const act = (toolName, expr, verb, args, run) =>
+    step(`${verb.replace(/\(.*$/s, "")} ${expr}`, async (k) => {
+      const loc = at(expr);
+      const mapped = exportable(exp, expr, loc);
+      if (!mapped) omit(k, "this action", expr);
+      const t = Date.now();
+      await run(loc);
+      push(toolName, args, `await ${mapped ? mapped.expr : expr}.${verb};`, t);
+      await settle();
+    });
+  const url = (p) => (/^https?:/.test(p) ? p : `${(opts.baseUrl || "").replace(/\/$/, "")}${p.startsWith("/") ? "" : "/"}${p}`);
+  // Each check is made now, against the live page and retried like Playwright's expect, so a walk that records one the app does not meet fails here.
+  const assert = (name, type, expr, expected, check) =>
+    step(`${name}(${expr}${expected !== undefined ? `, ${JSON.stringify(expected)}` : ""})`, async (k) => {
+      const loc = at(expr);
+      try {
+        // Each attempt waits up to a second for the element; never so briefly that its timeout hides what the check saw.
+        await retryUntil((left) => check(loc, Math.max(100, Math.min(left, 1000))), checkTimeout);
+      } catch (e) {
+        throw new Error(`not met within ${checkTimeout} ms: ${firstLines(e && e.message, 3)}`, { cause: e });
+      }
+      const mapped = exportable(exp, expr, loc);
+      if (!mapped) return omit(k, "this check", expr);
+      checks.set(push("browser_assert", { type, selector: mapped.selector, ...(expected !== undefined ? { expected: String(expected) } : {}) }), mapped);
+    });
+  const w = {
+    page,
+    goto: (p) => step(`goto ${url(p)}`, async () => { const t = Date.now(); await page.goto(url(p)); push("browser_navigate", { url: url(p) }, "", t); await settle(); }),
+    click: (expr) => act("browser_click", expr, "click()", {}, (l) => l.click()),
+    fill: (expr, text) => act("browser_type", expr, `fill(${JSON.stringify(text)})`, { text }, (l) => l.fill(text)),
+    select: (expr, value) => act("browser_select_option", expr, `selectOption(${JSON.stringify(value)})`, { values: [value] }, (l) => l.selectOption(value)),
+    press: (expr, key) => act("browser_press_key", expr, `press(${JSON.stringify(key)})`, { key }, (l) => l.press(key)),
+    expectRequest: () => { push("browser_assert_api_request", {}); },
+    expectText: (expr, text) => assert("expectText", "text", expr, text, async (l, timeout) => { const got = (await l.textContent({ timeout })) || ""; if (!got.includes(text)) throw new Error(`expected it to contain ${JSON.stringify(text)}, got ${JSON.stringify(got.trim().slice(0, 200))}`); }),
+    expectVisible: (expr) => assert("expectVisible", "visible", expr, undefined, async (l) => { if (!(await l.isVisible())) throw new Error("expected it to be visible; it is not"); }),
+    expectValue: (expr, value) => assert("expectValue", "value", expr, value, async (l, timeout) => { const got = await l.inputValue({ timeout }); if (got !== String(value)) throw new Error(`expected value ${JSON.stringify(String(value))}, got ${JSON.stringify(got)}`); }),
+    expectCount: (expr, count) => assert("expectCount", "count", expr, count, async (l) => { const got = await l.count(); if (got !== count) throw new Error(`expected ${count} matching, got ${got}`); }),
+  };
+  let failure;
+  try {
+    await body(w);
+  } catch (e) {
+    failure = e;
+  }
+  // Requests still in flight fail once the context closes; none of that may replace the walk's own error.
+  state.closing = true;
+  await context.unrouteAll({ behavior: "ignoreErrors" }).catch(() => {});
+  await context.close().catch((e) => { failure = failure || e; });
+  await browser.close().catch(() => {});
+  const record = async () => {
+    const jsonl = patchAssertLocators(exp.buildJsonlContent(actions, "chromium", har).jsonl, checks);
+    await exp.writeSkyrampZip(zip, jsonl, har);
+    return jsonl;
+  };
+  if (failure) {
+    try {
+      const partial = path.join(scratch, "partial.jsonl");
+      fs.writeFileSync(partial, await record());
+      process.stderr.write(`skyramp walk: the recording up to the failure (actions recorded: ${actions.length}) is in ${partial} (zip: ${zip})\n`);
+    } catch { /* the walk's own error is the one that matters */ }
+    throw failure;
+  }
+  await record();
+  const result = await withCredential(() => new SkyrampClient().generateRestTest({
+    testType: "ui",
+    language: opts.language || "typescript",
+    framework: "playwright",
+    outputDir: path.resolve(opts.outputDir || "."),
+    output: opts.output,
+    playwrightInput: zip,
+    generateInclude: hosts,
+    force: true,
+  }));
+  if (!/success/i.test(String(result))) throw new Error(`Skyramp generation failed: ${result}`);
+  return { zip, test: path.resolve(opts.outputDir || ".", opts.output), actions: actions.length, ...(leftOut.length ? { leftOut } : {}) };
+}
+
+module.exports = { walk, _internal: { withCredential, retryUntil, apiRoute, stepFailure, forkLocator, exportable, patchAssertLocators, loadPlaywright } };

package/dist/VERSION.json

@@ -1 +1 @@
-{"version":"0.13.0-v3.179","commit":"8395f727a14f1021b299b0f8ec92a186326162d3"}
+{"version":"0.13.0-v3.181","commit":"301a6fa10fd353e0dd1a5c52f8f0d3bac25d952e"}