@piwitests/reporter 0.22.1 → 0.24.0

package/dist/index.js

@@ -33,7 +33,9 @@ __export(index_exports, {
   PiwiDashboardReporter: () => PiwiDashboardReporter,
   createGlobalSetup: () => createGlobalSetup,
   default: () => index_default,
+  extendPiwiAi: () => extendPiwiAi,
   extendPiwiFixtures: () => extendPiwiFixtures,
+  piwiAiFixtures: () => piwiAiFixtures,
   piwiFixtures: () => piwiFixtures,
   wrapConfig: () => wrapConfig
 });
@@ -103,7 +105,15 @@ var PIWI_ENV_KEYS = {
   captureServerTraces: "PIWI_CAPTURE_SERVER_TRACES",
   inspectOnFailure: "PIWI_INSPECT_ON_FAIL",
   pickLocatorOnFailure: "PIWI_PICK_LOCATOR_ON_FAIL",
-  outputFile: "PIWI_OUTPUT_FILE"
+  outputFile: "PIWI_OUTPUT_FILE",
+  aiMode: "PIWI_AI",
+  aiDir: "PIWI_AI_DIR",
+  aiOnMiss: "PIWI_AI_ON_MISS",
+  aiMaxSteps: "PIWI_AI_MAX_FLOW_STEPS",
+  aiMaxSnapshotChars: "PIWI_AI_MAX_SNAPSHOT_CHARS",
+  aiOptionalProbeTimeout: "PIWI_AI_OPTIONAL_PROBE_TIMEOUT",
+  aiResponseWaitTimeout: "PIWI_AI_RESPONSE_WAIT_TIMEOUT",
+  aiScreenshotFallback: "PIWI_AI_SCREENSHOT_FALLBACK"
 };
 var PIWI_DESKTOP_CONFIG_ENV = "PIWI_DESKTOP_CONFIG";
 function readBool(val) {
@@ -186,6 +196,18 @@ function applyOptionsToEnv(options) {
   if (options.inspectOnFailure !== void 0) env[PIWI_ENV_KEYS.inspectOnFailure] = String(options.inspectOnFailure);
   if (options.pickLocatorOnFailure !== void 0)
     env[PIWI_ENV_KEYS.pickLocatorOnFailure] = String(options.pickLocatorOnFailure);
+  if (options.ai?.mode !== void 0) env[PIWI_ENV_KEYS.aiMode] = options.ai.mode;
+  if (options.ai?.dir !== void 0) env[PIWI_ENV_KEYS.aiDir] = options.ai.dir;
+  if (options.ai?.onMiss !== void 0) env[PIWI_ENV_KEYS.aiOnMiss] = options.ai.onMiss;
+  if (options.ai?.maxSteps !== void 0) env[PIWI_ENV_KEYS.aiMaxSteps] = String(options.ai.maxSteps);
+  if (options.ai?.maxSnapshotChars !== void 0)
+    env[PIWI_ENV_KEYS.aiMaxSnapshotChars] = String(options.ai.maxSnapshotChars);
+  if (options.ai?.optionalProbeTimeout !== void 0)
+    env[PIWI_ENV_KEYS.aiOptionalProbeTimeout] = String(options.ai.optionalProbeTimeout);
+  if (options.ai?.responseWaitTimeout !== void 0)
+    env[PIWI_ENV_KEYS.aiResponseWaitTimeout] = String(options.ai.responseWaitTimeout);
+  if (options.ai?.screenshotFallback !== void 0)
+    env[PIWI_ENV_KEYS.aiScreenshotFallback] = String(options.ai.screenshotFallback);
 }
 
 // src/internal/transport/http-client.ts
@@ -437,6 +459,7 @@ function toWireTestCase(tc) {
     networkRequests: rest.networkRequests || null,
     webVitals: rest.webVitals || null,
     pageState: rest.pageState || null,
+    aiUsage: rest.aiUsage || null,
     consoleLogs: rest.consoleLogs || null,
     ariaSnapshot: rest.ariaSnapshot || null,
     testSource: rest.testSource || null,
@@ -836,7 +859,9 @@ var ATTACHMENT_NAMES = {
   webVitals: "piwi-web-vitals",
   locatorSuggestion: "piwi-locator-suggestion",
   pageState: "piwi-page-state",
-  userPick: "piwi-user-pick"
+  userPick: "piwi-user-pick",
+  aiUsage: "piwi-ai-usage",
+  aiMeta: "piwi-ai-meta"
 };
 var INTERNAL_ATTACHMENT_NAMES = new Set(Object.values(ATTACHMENT_NAMES));
 var LOCATOR_SUGGESTION_ANNOTATION = ATTACHMENT_NAMES.locatorSuggestion;
@@ -945,6 +970,13 @@ var FileHandler = class {
       } catch {
       }
     }
+    const aiUsage = find(ATTACHMENT_NAMES.aiUsage);
+    if (aiUsage?.body) {
+      try {
+        testCase.aiUsage = JSON.parse(aiUsage.body.toString());
+      } catch {
+      }
+    }
   }
   /** Compute SHA-256 hash and size for a single test case's trace file. Returns `null` when the case has no trace on disk. */
   async computeSingleTraceHash(testCase) {
@@ -1772,10 +1804,10 @@ function readSourceSnippet(file, declLine, context, failingLine) {
       const hasFailingLine = failingLine != null;
       const isFailing = hasFailingLine && lineNum === failingLine;
       const isDecl = lineNum === declLine && !isFailing;
-      let marker = "  ";
-      if (isFailing) marker = "> ";
-      else if (isDecl) marker = hasFailingLine ? "* " : "> ";
-      return `${marker}${String(lineNum).padStart(4)} | ${l}`;
+      let marker2 = "  ";
+      if (isFailing) marker2 = "> ";
+      else if (isDecl) marker2 = hasFailingLine ? "* " : "> ";
+      return `${marker2}${String(lineNum).padStart(4)} | ${l}`;
     }).join("\n");
   } catch {
     return null;
@@ -4132,8 +4164,30 @@ function mergeCandidates(base, extra) {
 var path15 = __toESM(require("path"));
 
 // ../core/src/locator-fingerprint.ts
+var ELEMENT_MATCH_SCORES = { role: 60, text: 55, label: 50 };
 var PRESENT_SIMILARITY = 0.8;
 var MATCH_SIMILARITY = 0.2;
+var TEXT_CONTENT_ROLES = /* @__PURE__ */ new Set([
+  "button",
+  "link",
+  "heading",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "tab",
+  "option",
+  "cell",
+  "columnheader",
+  "rowheader",
+  "gridcell",
+  "treeitem",
+  "listitem",
+  "checkbox",
+  "radio",
+  "switch"
+]);
+var FORM_FIELD_ROLES = /* @__PURE__ */ new Set(["textbox", "combobox", "searchbox", "spinbutton", "slider"]);
+var escapeQuote = (s) => s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
 function parseAriaCandidates(ariaSnapshot) {
   if (!ariaSnapshot) return [];
   const out = [];
@@ -4196,6 +4250,40 @@ function matchRenamedElement(fp, candidates) {
   }
   return null;
 }
+function freshLocatorsFromCandidate(c) {
+  const out = [];
+  const name = c.name;
+  if (!name) return out;
+  out.push(
+    c.level != null ? {
+      locator: `getByRole('${escapeQuote(c.role)}', { name: '${escapeQuote(name)}', level: ${c.level} })`,
+      method: "getByRole",
+      args: { role: c.role, name, level: c.level },
+      score: ELEMENT_MATCH_SCORES.role
+    } : {
+      locator: `getByRole('${escapeQuote(c.role)}', { name: '${escapeQuote(name)}' })`,
+      method: "getByRole",
+      args: { role: c.role, name },
+      score: ELEMENT_MATCH_SCORES.role
+    }
+  );
+  if (TEXT_CONTENT_ROLES.has(c.role)) {
+    out.push({
+      locator: `getByText('${escapeQuote(name)}')`,
+      method: "getByText",
+      args: { text: name },
+      score: ELEMENT_MATCH_SCORES.text
+    });
+  } else if (FORM_FIELD_ROLES.has(c.role)) {
+    out.push({
+      locator: `getByLabel('${escapeQuote(name)}')`,
+      method: "getByLabel",
+      args: { label: name },
+      score: ELEMENT_MATCH_SCORES.label
+    });
+  }
+  return out;
+}
 
 // ../core/src/locator-methods.ts
 var LOCATOR_BUILDER_METHODS = [
@@ -5392,13 +5480,804 @@ function extendPiwiFixtures(test) {
   return test.extend(piwiFixtures);
 }
 
+// src/internal/ai/ai-fixtures.ts
+var fs15 = __toESM(require("fs"));
+var path19 = __toESM(require("path"));
+var import_test = require("@playwright/test");
+
+// src/internal/ai/artifact.ts
+var fs14 = __toESM(require("fs"));
+var path17 = __toESM(require("path"));
+var ARTIFACT_VERSION = 1;
+var LOCATOR_METHOD_SET = new Set(LOCATOR_METHODS);
+var ACTION_METHOD_SET2 = new Set(ACTION_METHODS);
+var POSTCONDITION_ASSERTS = /* @__PURE__ */ new Set([
+  "visible",
+  "hidden",
+  "attached",
+  "url"
+]);
+function sortDeep(value) {
+  if (Array.isArray(value)) return value.map(sortDeep);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      const v = value[key];
+      if (v !== void 0) out[key] = sortDeep(v);
+    }
+    return out;
+  }
+  return value;
+}
+function serializeEntry(entry) {
+  return `${JSON.stringify(sortDeep(entry), null, 2)}
+`;
+}
+var ArtifactError = class extends Error {
+};
+function assert(condition, message) {
+  if (!condition) throw new ArtifactError(message);
+}
+function validateStructuredLocator(value, where) {
+  assert(value !== null && typeof value === "object", `${where}: locator must be an object`);
+  const loc = value;
+  assert(typeof loc.method === "string", `${where}: locator.method must be a string`);
+  assert(LOCATOR_METHOD_SET.has(loc.method), `${where}: locator method "${String(loc.method)}" is not allowlisted`);
+  assert(Array.isArray(loc.args), `${where}: locator.args must be an array`);
+  if (loc.chain !== void 0) {
+    assert(Array.isArray(loc.chain), `${where}: locator.chain must be an array`);
+    loc.chain.forEach((child, i) => validateStructuredLocator(child, `${where}.chain[${i}]`));
+  }
+}
+function validateRunStep(value, where) {
+  assert(value !== null && typeof value === "object", `${where}: step must be an object`);
+  const step = value;
+  validateStructuredLocator(step.locator, `${where}.locator`);
+  assert(typeof step.action === "string", `${where}: action must be a string`);
+  assert(ACTION_METHOD_SET2.has(step.action), `${where}: action "${String(step.action)}" is not allowlisted`);
+  if (step.value !== void 0) assert(typeof step.value === "string", `${where}: value must be a string`);
+  if (step.optional !== void 0) assert(typeof step.optional === "boolean", `${where}: optional must be a boolean`);
+  if (step.waitForResponse !== void 0) {
+    assert(typeof step.waitForResponse === "string", `${where}: waitForResponse must be a string`);
+  }
+}
+function validatePostcondition(value) {
+  assert(value !== null && typeof value === "object", "postcondition must be an object");
+  const post = value;
+  assert(
+    POSTCONDITION_ASSERTS.has(post.assert),
+    `postcondition.assert "${String(post.assert)}" is not supported`
+  );
+  if (post.assert === "url") {
+    assert(typeof post.url === "string", "postcondition.url must be a string for a url assert");
+  } else {
+    validateStructuredLocator(post.locator, "postcondition.locator");
+  }
+}
+function parseEntry(text) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    throw new ArtifactError(`entry is not valid JSON: ${error.message}`);
+  }
+  assert(raw !== null && typeof raw === "object", "entry must be an object");
+  const obj = raw;
+  assert(obj.version === ARTIFACT_VERSION, `unsupported entry version ${String(obj.version)}`);
+  assert(typeof obj.template === "string", "entry.template must be a string");
+  if (obj.kind === "locator") {
+    validateStructuredLocator(obj.locator, "entry.locator");
+    return obj;
+  }
+  if (obj.kind === "run") {
+    assert(Array.isArray(obj.steps), "entry.steps must be an array");
+    obj.steps.forEach((step, i) => validateRunStep(step, `entry.steps[${i}]`));
+    validatePostcondition(obj.postcondition);
+    return obj;
+  }
+  throw new ArtifactError(`unsupported entry kind "${String(obj.kind)}"`);
+}
+function readEntry(file) {
+  let text;
+  try {
+    text = fs14.readFileSync(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+  return parseEntry(text);
+}
+function writeEntry(file, entry) {
+  const canonical = serializeEntry(entry);
+  return withEntryLock(file, () => {
+    if (fs14.existsSync(file) && fs14.readFileSync(file, "utf8") === canonical) return { written: false };
+    fs14.mkdirSync(path17.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs14.writeFileSync(tmp, canonical);
+    fs14.renameSync(tmp, file);
+    return { written: true };
+  });
+}
+function withEntryLock(file, fn) {
+  const lock = `${file}.lock`;
+  fs14.mkdirSync(path17.dirname(file), { recursive: true });
+  const deadline = Date.now() + 5e3;
+  for (; ; ) {
+    try {
+      const fd = fs14.openSync(lock, "wx");
+      fs14.closeSync(fd);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (Date.now() > deadline) {
+        try {
+          fs14.unlinkSync(lock);
+        } catch {
+        }
+      }
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    try {
+      fs14.unlinkSync(lock);
+    } catch {
+    }
+  }
+}
+
+// src/internal/ai/keys.ts
+var crypto3 = __toESM(require("crypto"));
+var path18 = __toESM(require("path"));
+var DEFAULT_AI_DIR = "__piwi__";
+function normalizeTemplate(template) {
+  return template.trim().replace(/\s+/g, " ").toLowerCase();
+}
+function hashTemplate(normalized, ordinal = 0) {
+  const input = ordinal > 0 ? `${normalized}#${ordinal}` : normalized;
+  return crypto3.createHash("sha256").update(input).digest("hex").slice(0, 8);
+}
+function slug(text, maxLength = 40) {
+  const base = text.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return (base || "x").slice(0, maxLength).replace(/-+$/g, "") || "x";
+}
+function entryDir(specFile, dir = DEFAULT_AI_DIR) {
+  return path18.join(path18.dirname(specFile), dir, path18.basename(specFile));
+}
+function entryPath(params) {
+  const basis = `${normalizeTemplate(params.testTitle)}::${normalizeTemplate(params.template)}`;
+  const hash = hashTemplate(basis, params.ordinal ?? 0);
+  const name = `${slug(params.testTitle)}.${slug(params.template)}.${hash}.json`;
+  return path18.join(entryDir(params.specFile, params.dir), name);
+}
+function parseLocation(location) {
+  const match = /:(\d+):(\d+)$/.exec(location);
+  if (!match) return null;
+  return { line: Number(match[1]), col: Number(match[2]) };
+}
+function orderByPosition(locations) {
+  return [...new Set(locations)].sort((a, b) => {
+    const pa = parseLocation(a);
+    const pb = parseLocation(b);
+    if (!pa || !pb) return a < b ? -1 : a > b ? 1 : 0;
+    return pa.line - pb.line || pa.col - pb.col;
+  });
+}
+function ordinalForLocation(sites, location) {
+  const ordered = orderByPosition(sites);
+  const index = ordered.indexOf(location);
+  return index < 0 ? 0 : index;
+}
+function findTemplateSites(source, template) {
+  const needle = template.trim();
+  if (!needle) return [];
+  const sites = [];
+  const lines = source.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    let from = 0;
+    for (; ; ) {
+      const col = lines[i].indexOf(needle, from);
+      if (col < 0) break;
+      sites.push(`${i + 1}:${col + 1}`);
+      from = col + needle.length;
+    }
+  }
+  return sites;
+}
+
+// src/internal/ai/params.ts
+var PLACEHOLDER = /\{([^{}]+)\}/g;
+var MARKER = /\{\{([^{}]+)\}\}/g;
+function extractPlaceholders(template) {
+  const names = [];
+  for (const match of template.matchAll(PLACEHOLDER)) {
+    const name = match[1].trim();
+    if (name && !names.includes(name)) names.push(name);
+  }
+  return names;
+}
+function marker(name) {
+  return `{{${name}}}`;
+}
+function validateParams(template, params) {
+  const placeholders = extractPlaceholders(template);
+  if (placeholders.length === 0) return;
+  const missing = placeholders.filter((name) => params?.[name] === void 0);
+  if (missing.length > 0) {
+    throw new Error(`piwi AI: template "${template}" is missing parameter(s): ${missing.join(", ")}`);
+  }
+}
+function substituteMarkers(text, params) {
+  return text.replace(MARKER, (whole, name) => {
+    const value = params[name.trim()];
+    return value === void 0 ? whole : value;
+  });
+}
+function substituteArgs(args, params) {
+  return args.map((arg) => substituteValue(arg, params));
+}
+function substituteValue(value, params) {
+  if (typeof value === "string") return substituteMarkers(value, params);
+  if (Array.isArray(value)) return value.map((v) => substituteValue(v, params));
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, v] of Object.entries(value)) out[key] = substituteValue(v, params);
+    return out;
+  }
+  return value;
+}
+function maskValues(text, params) {
+  const entries = Object.entries(params).filter(([, value]) => value.length > 0).sort((a, b) => b[1].length - a[1].length);
+  let masked = text;
+  for (const [name, value] of entries) {
+    masked = masked.split(value).join(marker(name));
+  }
+  return masked;
+}
+function isParametric(template, compiledText) {
+  return extractPlaceholders(template).every((name) => compiledText.includes(marker(name)));
+}
+
+// src/internal/ai/interpreter.ts
+var LOCATOR_METHOD_SET2 = new Set(LOCATOR_METHODS);
+var ACTION_METHOD_SET3 = new Set(ACTION_METHODS);
+var StepDriftError = class extends Error {
+  constructor(step, fingerprint) {
+    super(
+      `piwi AI: element drifted from its recorded identity (role="${fingerprint.role ?? ""}" name="${fingerprint.name ?? ""}") before ${describeLocator(step.locator)}.${step.action}() \u2014 the flow was not run to avoid corrupting page state`
+    );
+    this.step = step;
+    this.fingerprint = fingerprint;
+    this.name = "StepDriftError";
+  }
+};
+var PostconditionError = class extends Error {
+  constructor(post, cause) {
+    super(`piwi AI: postcondition (${describePostcondition(post)}) not satisfied \u2014 ${cause}`);
+    this.name = "PostconditionError";
+  }
+};
+function describeLocator(loc) {
+  const head = `${loc.method}(${loc.args.map((a) => JSON.stringify(a)).join(", ")})`;
+  const tail = (loc.chain ?? []).map(describeLocator).join(".");
+  return tail ? `${head}.${tail}` : head;
+}
+function renderSourceArg(arg) {
+  if (typeof arg === "string") return `'${arg.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+  if (arg === null || typeof arg === "number" || typeof arg === "boolean") return String(arg);
+  if (Array.isArray(arg)) return `[${arg.map(renderSourceArg).join(", ")}]`;
+  return `{ ${Object.entries(arg).map(([key, value]) => `${key}: ${renderSourceArg(value)}`).join(", ")} }`;
+}
+function locatorSource(loc) {
+  const head = `${loc.method}(${loc.args.map(renderSourceArg).join(", ")})`;
+  const tail = (loc.chain ?? []).map(locatorSource).join(".");
+  return tail ? `${head}.${tail}` : head;
+}
+function describePostcondition(post) {
+  return post.assert === "url" ? `url \u2192 ${post.url ?? ""}` : `${describeLocator(post.locator)} ${post.assert}`;
+}
+function buildLocator(root, structured, params = {}) {
+  if (!LOCATOR_METHOD_SET2.has(structured.method)) {
+    throw new Error(`piwi AI: locator method "${structured.method}" is not allowlisted`);
+  }
+  const args = substituteArgs(structured.args, params);
+  let current = root[structured.method](...args);
+  for (const child of structured.chain ?? []) {
+    current = buildLocator(current, child, params);
+  }
+  return current;
+}
+async function probePresent(locator, timeout) {
+  try {
+    await locator.first().waitFor({ state: "visible", timeout });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function checkFingerprintDrift(ariaSnapshot, fingerprint) {
+  if (!ariaSnapshot) return "unknown";
+  const candidates = parseAriaCandidates(ariaSnapshot);
+  if (candidates.length === 0) return "unknown";
+  return fingerprintPresent(fingerprint, candidates) ? "present" : "drifted";
+}
+async function performAction(page, locator, step, ctx) {
+  if (!ACTION_METHOD_SET3.has(step.action)) throw new Error(`piwi AI: action "${step.action}" is not allowlisted`);
+  const args = step.value === void 0 ? [] : [substituteMarkers(step.value, ctx.params)];
+  const act = () => locator[step.action](...args);
+  if (!step.waitForResponse) {
+    await act();
+    return;
+  }
+  const pattern = substituteMarkers(step.waitForResponse, ctx.params);
+  const waitForResponse = ctx.responseWaitTimeout === void 0 ? page.waitForResponse(pattern) : page.waitForResponse(pattern, { timeout: ctx.responseWaitTimeout });
+  await Promise.all([waitForResponse, act()]);
+}
+async function executeStep(step, ctx) {
+  const body = async () => {
+    const locator = buildLocator(ctx.page, step.locator, ctx.params);
+    if (step.optional) {
+      const present = await probePresent(locator, ctx.optionalProbeTimeout ?? 2e3);
+      if (!present) return "skipped";
+    }
+    if (step.fingerprint && ctx.readAria) {
+      const aria = await ctx.readAria(ctx.page);
+      if (checkFingerprintDrift(aria, step.fingerprint) === "drifted") {
+        throw new StepDriftError(step, step.fingerprint);
+      }
+    }
+    await performAction(ctx.page, locator, step, ctx);
+    return "ran";
+  };
+  const title = `${step.action}: ${describeLocator(step.locator)}${step.optional ? " (optional)" : ""}`;
+  return ctx.step ? ctx.step(title, body) : body();
+}
+async function assertPostcondition(post, ctx) {
+  const body = async () => {
+    try {
+      if (post.assert === "url") {
+        await ctx.page.waitForURL(substituteMarkers(post.url ?? "", ctx.params));
+        return;
+      }
+      const locator = buildLocator(ctx.page, post.locator, ctx.params);
+      const state = post.assert === "hidden" ? "hidden" : post.assert === "attached" ? "attached" : "visible";
+      await locator.first().waitFor({ state });
+    } catch (error) {
+      throw new PostconditionError(post, error.message);
+    }
+  };
+  await (ctx.step ? ctx.step(`postcondition: ${describePostcondition(post)}`, body) : body());
+}
+async function executeRun(entry, ctx) {
+  for (const step of entry.steps) {
+    await executeStep(step, ctx);
+  }
+  await assertPostcondition(entry.postcondition, ctx);
+}
+
+// src/internal/ai/compile.ts
+function hasAnchor(args) {
+  return Object.keys(args).some((key) => key.startsWith("anchor"));
+}
+function positionalArgs(method, args) {
+  switch (method) {
+    case "getByTestId":
+      return typeof args.testId === "string" ? [args.testId] : null;
+    case "getByRole": {
+      if (typeof args.role !== "string") return null;
+      const options = {};
+      if (typeof args.name === "string") options.name = args.name;
+      if (typeof args.level === "number") options.level = args.level;
+      return Object.keys(options).length > 0 ? [args.role, options] : [args.role];
+    }
+    case "getByLabel":
+      return typeof args.label === "string" ? [args.label] : null;
+    case "getByPlaceholder":
+      return typeof args.placeholder === "string" ? [args.placeholder] : null;
+    case "getByText":
+    case "getByAltText":
+      return typeof args.text === "string" ? [args.text] : null;
+    case "getByTitle":
+      return typeof args.title === "string" ? [args.title] : null;
+    case "locator":
+      return typeof args.selector === "string" ? [args.selector] : null;
+    default:
+      return null;
+  }
+}
+function rankedToStructured(ranked) {
+  if (hasAnchor(ranked.args)) return null;
+  const args = positionalArgs(ranked.method, ranked.args);
+  if (!args) return null;
+  return { method: ranked.method, args };
+}
+function compileFromCandidate(candidate) {
+  const fingerprint = { role: candidate.role, name: candidate.name };
+  if (candidate.level != null) fingerprint.level = candidate.level;
+  for (const ranked of freshLocatorsFromCandidate(candidate)) {
+    const structured = rankedToStructured(ranked);
+    if (structured) return { locator: structured, fingerprint, score: ranked.score };
+  }
+  return null;
+}
+
+// src/internal/ai/resolution.ts
+var MAX_SNAPSHOT_CHARS = 24e3;
+var DEFAULT_MAX_STEPS = 20;
+var ServerStepResolver = class {
+  constructor(serverUrl, apiKey) {
+    this.serverUrl = serverUrl;
+    this.apiKey = apiKey;
+  }
+  async resolveStep(request) {
+    const headers = { "Content-Type": "application/json" };
+    if (this.apiKey) headers["X-API-Key"] = this.apiKey;
+    const url = `${this.serverUrl.replace(/\/+$/, "")}/api/ai/step-resolution`;
+    const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(request) });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(body.message || `piwi AI: step resolution failed (${res.status})`);
+    }
+    return await res.json();
+  }
+};
+function candidateOf(element) {
+  return { role: element.role, name: element.name ?? null, level: element.level ?? null };
+}
+function locatorFromElement(element) {
+  return compileFromCandidate(candidateOf(element));
+}
+function lazyLocator(resolveOnce) {
+  let pending = null;
+  const ensure = () => pending ??= resolveOnce();
+  const handler = {
+    get(_t, prop) {
+      if (typeof prop !== "string" || prop === "then" || prop === "catch" || prop === "finally") return void 0;
+      return (...args) => ensure().then((loc) => loc[prop](...args));
+    }
+  };
+  return new Proxy({}, handler);
+}
+function buildPostcondition(resolved, template) {
+  if (!resolved)
+    throw new Error(`piwi AI: flow "${template}" resolved without a postcondition (the oracle is mandatory)`);
+  if (resolved.assert === "url") {
+    if (!resolved.url) throw new Error(`piwi AI: flow "${template}" postcondition is a url assert without a url`);
+    return { assert: "url", url: resolved.url };
+  }
+  const compiled = resolved.element ? locatorFromElement(resolved.element) : null;
+  if (!compiled) throw new Error(`piwi AI: flow "${template}" postcondition element could not be compiled`);
+  return { assert: resolved.assert, locator: compiled.locator };
+}
+var readMaskedSnapshot = async (page, params) => {
+  const raw = await ariaSnapshotBestEffort(page.locator("body"));
+  return raw ? maskValues(raw, params) : "";
+};
+var observeXhrResponses = async (page, action, settleMs) => {
+  const urls = [];
+  const onResponse = (res) => {
+    const type = res.request().resourceType();
+    if (type === "xhr" || type === "fetch") urls.push(res.url());
+  };
+  page.on("response", onResponse);
+  try {
+    await action();
+    await page.waitForLoadState("networkidle", settleMs === void 0 ? void 0 : { timeout: settleMs }).catch(() => {
+    });
+  } finally {
+    page.off("response", onResponse);
+  }
+  return urls;
+};
+var captureViewportScreenshot = async (page) => {
+  try {
+    const buffer = await page.screenshot({ type: "jpeg", quality: 60 });
+    return { mediaType: "image/jpeg", data: buffer.toString("base64") };
+  } catch {
+    return null;
+  }
+};
+async function maybeScreenshot(ctx, ariaSnapshot) {
+  if (!ctx.screenshotFallback || ariaSnapshot.length > 0) return void 0;
+  const capture = ctx.captureScreenshot ?? captureViewportScreenshot;
+  return await capture(ctx.page) ?? void 0;
+}
+function assertParametric(template, locatorJson) {
+  if (extractPlaceholders(template).length > 0 && !isParametric(template, locatorJson)) {
+    throw new Error(
+      `piwi AI: resolved locator for "${template}" is not parametric \u2014 the grounding pinned a concrete value instead of a placeholder`
+    );
+  }
+}
+async function resolveLocator(template, ctx) {
+  const readSnapshot = ctx.readSnapshot ?? readMaskedSnapshot;
+  const cap = ctx.maxSnapshotChars ?? MAX_SNAPSHOT_CHARS;
+  const ariaSnapshot = (await readSnapshot(ctx.page, ctx.params)).slice(0, cap);
+  const screenshot = await maybeScreenshot(ctx, ariaSnapshot);
+  const decision = await ctx.resolver.resolveStep({
+    kind: "locator",
+    template,
+    paramNames: Object.keys(ctx.params),
+    ariaSnapshot,
+    history: [],
+    ...screenshot ? { screenshot } : {}
+  });
+  if (!decision.element) throw new Error(`piwi AI: resolver returned no element for "${template}"`);
+  const compiled = locatorFromElement(decision.element);
+  if (!compiled) throw new Error(`piwi AI: element for "${template}" could not be compiled to a stable locator`);
+  const entry = {
+    version: ARTIFACT_VERSION,
+    kind: "locator",
+    template,
+    locator: compiled.locator,
+    fingerprint: compiled.fingerprint
+  };
+  assertParametric(template, JSON.stringify(compiled.locator));
+  const built = buildLocator(ctx.page, compiled.locator, ctx.params);
+  await built.first().waitFor({ state: "visible" });
+  return entry;
+}
+async function resolveRun(template, ctx) {
+  const readSnapshot = ctx.readSnapshot ?? readMaskedSnapshot;
+  const maxSteps = ctx.maxSteps ?? DEFAULT_MAX_STEPS;
+  const cap = ctx.maxSnapshotChars ?? MAX_SNAPSHOT_CHARS;
+  const paramNames = Object.keys(ctx.params);
+  const steps = [];
+  const history = [];
+  for (let i = 0; i < maxSteps; i++) {
+    const ariaSnapshot = (await readSnapshot(ctx.page, ctx.params)).slice(0, cap);
+    const screenshot = await maybeScreenshot(ctx, ariaSnapshot);
+    const decision = await ctx.resolver.resolveStep({
+      kind: "run",
+      template,
+      paramNames,
+      ariaSnapshot,
+      history,
+      ...screenshot ? { screenshot } : {}
+    });
+    if (decision.done) {
+      const postcondition = buildPostcondition(decision.postcondition, template);
+      await assertPostcondition(postcondition, { page: ctx.page, params: ctx.params });
+      return { version: ARTIFACT_VERSION, kind: "run", template, steps, postcondition };
+    }
+    if (!decision.element || !decision.action) {
+      throw new Error(`piwi AI: resolver returned neither a step nor done for "${template}"`);
+    }
+    const compiled = locatorFromElement(decision.element);
+    if (!compiled) throw new Error(`piwi AI: a step element for "${template}" could not be compiled`);
+    const step = { locator: compiled.locator, action: decision.action, fingerprint: compiled.fingerprint };
+    if (decision.value !== void 0) step.value = decision.value;
+    if (decision.optional) step.optional = true;
+    steps.push(step);
+    const observe = ctx.observeResponses ?? observeXhrResponses;
+    const observed = await observe(
+      ctx.page,
+      () => executeStep(step, {
+        page: ctx.page,
+        params: ctx.params,
+        optionalProbeTimeout: ctx.optionalProbeTimeout
+      }).then(() => void 0),
+      ctx.responseWaitTimeout
+    );
+    history.push({ action: decision.action, element: decision.element, value: decision.value });
+    if (observed.length > 0) {
+      const waitDecision = await ctx.resolver.resolveStep({
+        kind: "wait",
+        template,
+        paramNames,
+        ariaSnapshot: "",
+        history,
+        observedResponses: observed.map((url) => maskValues(url, ctx.params))
+      });
+      if (waitDecision.waitForResponse) step.waitForResponse = waitDecision.waitForResponse;
+    }
+  }
+  throw new Error(`piwi AI: exceeded the ${maxSteps}-step budget resolving "${template}"`);
+}
+
+// src/internal/ai/ai-fixtures.ts
+function parseAiMode(value) {
+  return value === "resolve" || value === "heal" ? value : "replay";
+}
+function readPositiveInt(value) {
+  if (value === void 0 || value.trim() === "") return void 0;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : void 0;
+}
+function readAiConfig(env) {
+  return {
+    mode: parseAiMode(env.PIWI_AI),
+    dir: env.PIWI_AI_DIR || DEFAULT_AI_DIR,
+    onMiss: env.PIWI_AI_ON_MISS === "fixme" ? "fixme" : "fail",
+    update: env.PIWI_AI_UPDATE === "true",
+    maxSteps: readPositiveInt(env.PIWI_AI_MAX_FLOW_STEPS),
+    maxSnapshotChars: readPositiveInt(env.PIWI_AI_MAX_SNAPSHOT_CHARS),
+    optionalProbeTimeout: readPositiveInt(env.PIWI_AI_OPTIONAL_PROBE_TIMEOUT),
+    responseWaitTimeout: readPositiveInt(env.PIWI_AI_RESPONSE_WAIT_TIMEOUT),
+    screenshotFallback: env.PIWI_AI_SCREENSHOT_FALLBACK === "true"
+  };
+}
+function testIdentity(testInfo) {
+  const titles = testInfo.titlePath.slice(1);
+  return titles.length > 0 ? titles.join(" \u203A ") : testInfo.title;
+}
+function relativeToCwd(file) {
+  return path19.relative(process.cwd(), file).split(path19.sep).join("/");
+}
+function recordIntents(intents, entry) {
+  const add = (locator, kind) => {
+    intents.set(`${entry.template}\0${locator}`, { template: entry.template, locator, kind });
+  };
+  if (entry.kind === "locator") {
+    add(locatorSource(entry.locator), "locator");
+    return;
+  }
+  for (const step of entry.steps) add(locatorSource(step.locator), "run");
+  if (entry.postcondition.locator) add(locatorSource(entry.postcondition.locator), "run");
+}
+function missMessage(template, testTitle, relPath) {
+  return [
+    `piwi AI: no committed entry for "${template}" in test "${testTitle}".`,
+    `  expected file: ${relPath}`,
+    `  run:  piwi ai resolve --grep ${JSON.stringify(testTitle)}`,
+    `  (requires a configured authoring model; commit the generated file afterwards)`
+  ].join("\n");
+}
+function createAiApi(page, testInfo, config, used, intents) {
+  const testTitle = testIdentity(testInfo);
+  let source = null;
+  const readSource = () => {
+    if (source === null) {
+      try {
+        source = fs15.readFileSync(testInfo.file, "utf8");
+      } catch {
+        source = "";
+      }
+    }
+    return source;
+  };
+  const ordinalFor = (template, location) => {
+    if (!location) return 0;
+    const sites = findTemplateSites(readSource(), template);
+    if (sites.length <= 1) return 0;
+    const callLine = /:(\d+):\d+$/.exec(location)?.[1];
+    const perFileSites = sites.map((s) => `${testInfo.file}:${s}`);
+    const match = perFileSites.find((s) => /:(\d+):\d+$/.exec(s)?.[1] === callLine);
+    return match ? ordinalForLocation(perFileSites, match) : 0;
+  };
+  const resolveFile = (template) => {
+    const location = captureCallerLocation();
+    const ordinal = ordinalFor(template, location);
+    return entryPath({ specFile: testInfo.file, testTitle, template, ordinal, dir: config.dir });
+  };
+  const missInReplay = (template, file) => {
+    const message = missMessage(template, testTitle, relativeToCwd(file));
+    if (config.onMiss === "fixme") {
+      testInfo.annotations.push({ type: "fixme", description: message });
+      testInfo.fixme();
+    }
+    throw new Error(message);
+  };
+  const requireResolver = () => {
+    const serverUrl = process.env.PIWI_DASHBOARD_URL;
+    if (!serverUrl) {
+      throw new Error(`piwi AI: ${config.mode} mode needs PIWI_DASHBOARD_URL (the authoring server) to be set`);
+    }
+    return new ServerStepResolver(serverUrl, process.env.PIWI_API_KEY ?? null);
+  };
+  const readAria = (p) => ariaSnapshotBestEffort(p.locator("body"));
+  const step = (title, body) => import_test.test.step(title, body);
+  const canReuse = (entry, kind) => entry?.kind === kind && !(config.mode !== "replay" && config.update);
+  return {
+    piwiLocator(template, ...params) {
+      const values = params[0] ?? {};
+      validateParams(template, params[0]);
+      const file = resolveFile(template);
+      const existing = readEntry(file);
+      if (canReuse(existing, "locator")) {
+        used.add(file);
+        recordIntents(intents, existing);
+        return buildLocator(page, existing.locator, values);
+      }
+      if (config.mode === "replay") return missInReplay(template, file);
+      const resolver = requireResolver();
+      return lazyLocator(async () => {
+        const entry = await resolveLocator(template, {
+          page,
+          params: values,
+          resolver,
+          maxSnapshotChars: config.maxSnapshotChars,
+          screenshotFallback: config.screenshotFallback
+        });
+        writeEntry(file, entry);
+        used.add(file);
+        recordIntents(intents, entry);
+        return buildLocator(page, entry.locator, values);
+      });
+    },
+    async piwiRun(template, ...params) {
+      const values = params[0] ?? {};
+      validateParams(template, params[0]);
+      const file = resolveFile(template);
+      const existing = readEntry(file);
+      if (canReuse(existing, "run")) {
+        used.add(file);
+        recordIntents(intents, existing);
+        await step(
+          `piwiRun: ${template}`,
+          () => executeRun(existing, {
+            page,
+            params: values,
+            readAria,
+            step,
+            optionalProbeTimeout: config.optionalProbeTimeout,
+            responseWaitTimeout: config.responseWaitTimeout
+          })
+        );
+        return;
+      }
+      if (config.mode === "replay") {
+        missInReplay(template, file);
+        return;
+      }
+      const resolver = requireResolver();
+      await step(`piwiRun (resolve): ${template}`, async () => {
+        const entry = await resolveRun(template, {
+          page,
+          params: values,
+          resolver,
+          maxSteps: config.maxSteps,
+          maxSnapshotChars: config.maxSnapshotChars,
+          optionalProbeTimeout: config.optionalProbeTimeout,
+          responseWaitTimeout: config.responseWaitTimeout,
+          screenshotFallback: config.screenshotFallback
+        });
+        writeEntry(file, entry);
+        used.add(file);
+        recordIntents(intents, entry);
+      });
+    }
+  };
+}
+async function attachUsage(testInfo, used, intents) {
+  if (used.size === 0) return;
+  const entries = [...used].map(relativeToCwd).sort();
+  const intentList = [...intents.values()].sort(
+    (a, b) => a.template.localeCompare(b.template) || a.locator.localeCompare(b.locator)
+  );
+  await testInfo.attach(ATTACHMENT_NAMES.aiUsage, {
+    contentType: "application/json",
+    body: Buffer.from(JSON.stringify({ entries, ...intentList.length > 0 ? { intents: intentList } : {} }))
+  });
+}
+var piwiAiFixtures = {
+  page: async ({ page }, use, testInfo) => {
+    const config = readAiConfig(process.env);
+    const used = /* @__PURE__ */ new Set();
+    const intents = /* @__PURE__ */ new Map();
+    const ai = createAiApi(page, testInfo, config, used, intents);
+    Object.assign(page, ai);
+    try {
+      await use(page);
+    } finally {
+      await attachUsage(testInfo, used, intents);
+    }
+  }
+};
+function extendPiwiAi(test) {
+  return test.extend(piwiAiFixtures);
+}
+
 // src/index.ts
 var index_default = PiwiDashboardReporter;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PiwiDashboardReporter,
   createGlobalSetup,
+  extendPiwiAi,
   extendPiwiFixtures,
+  piwiAiFixtures,
   piwiFixtures,
   wrapConfig
 });