@guanlin4924/devflow-pi 0.1.97 → 0.1.99

package/plugins/devflow-quality/runtime/playwright/explore-host.mjs

@@ -1,3 +1,32 @@
+// plugins/devflow-quality/runtime/playwright/src/text-match.ts
+function normalizeText(value, normalizeWhitespace, caseSensitive) {
+  let out = normalizeWhitespace ? value.replace(/\s+/g, " ").trim() : value;
+  if (!caseSensitive)
+    out = out.toLowerCase();
+  return out;
+}
+function textMatches(actual, expected, match) {
+  return match === "exact" ? actual === expected : actual.includes(expected);
+}
+
+// plugins/devflow-quality/runtime/playwright/src/explore/request-tracker.ts
+class RequestTracker {
+  pending = new Set;
+  started = (request) => {
+    if (["fetch", "xhr", "document"].includes(request.resourceType()))
+      this.pending.add(request);
+  };
+  finished = (request) => {
+    this.pending.delete(request);
+  };
+  get size() {
+    return this.pending.size;
+  }
+  clear() {
+    this.pending.clear();
+  }
+}
+
 // plugins/devflow-quality/runtime/playwright/src/explore/host.ts
 import readline from "node:readline";
 import fs2 from "node:fs";
@@ -226,6 +255,7 @@ class Redactor {
 
 // plugins/devflow-quality/runtime/playwright/src/explore/view.ts
 var INTERACTIVE = new Set(["button", "link", "textbox", "searchbox", "checkbox", "radio", "combobox", "listbox", "option", "menuitem", "menuitemcheckbox", "menuitemradio", "tab", "switch", "slider", "spinbutton", "treeitem"]);
+var NAMEABLE = new Set(["dialog", "alertdialog", "region", "form", "navigation", ...INTERACTIVE]);
 var INFO = new Set(["heading", "alert", "status", "dialog", "alertdialog"]);
 var CONTEXT = new Set(["dialog", "alertdialog", "form", "navigation", "banner", "main", "region", "table", "row", "tabpanel", "menu"]);
 var TEXT_CONTAINERS = new Set(["dialog", "alertdialog", "alert", "status"]);
@@ -393,6 +423,37 @@ async function nameRows(page, nodes) {
     }
   }
 }
+async function nameContainers(page, nodes) {
+  for (const node of nodes.filter((item) => item.ref && !item.name && NAMEABLE.has(item.role))) {
+    const element = page.locator(`aria-ref=${node.ref}`);
+    if (await element.count() !== 1)
+      continue;
+    const name = await element.evaluate((item) => {
+      const ariaLabel = item.getAttribute("aria-label")?.trim();
+      if (ariaLabel)
+        return ariaLabel.replace(/\s+/g, " ").trim();
+      const ids = item.getAttribute("aria-labelledby")?.trim().split(/\s+/).filter(Boolean) ?? [];
+      return ids.map((id) => document.getElementById(id)?.textContent ?? "").join(" ").replace(/\s+/g, " ").trim();
+    });
+    if (!name)
+      continue;
+    const roleLocator = page.getByRole(node.role, { name, exact: true });
+    if (await sameUniqueElement(roleLocator, element))
+      node.name = name;
+  }
+}
+async function sameUniqueElement(candidate, element) {
+  if (await candidate.count() !== 1)
+    return false;
+  const candidateHandle = await candidate.elementHandle();
+  if (!candidateHandle)
+    return false;
+  try {
+    return await element.evaluate((node, other) => node === other, candidateHandle);
+  } finally {
+    await candidateHandle.dispose();
+  }
+}
 
 class ExplorerView {
   page;
@@ -410,22 +471,35 @@ class ExplorerView {
   node(ref) {
     return this.last?.get(ref);
   }
-  async observe(options = {}) {
+  async observe(options = {}, settled = true) {
     let scope = this.page.locator("body");
     if (options.scope) {
       const rawScope = options.scope;
-      if (/^aria-ref=e\d+$/.test(rawScope) || /^e\d+$/.test(rawScope))
-        scope = this.page.locator(rawScope.startsWith("aria-ref=") ? rawScope : `aria-ref=${rawScope}`);
-      else if (rawScope.startsWith("role="))
-        scope = this.page.getByRole(rawScope.slice(5));
-      else if (rawScope.startsWith("testid="))
+      const ref = /^(?:aria-ref=)?(e\d+)$/.exec(rawScope);
+      if (ref) {
+        if (!this.hasRef(ref[1]))
+          throw Object.assign(new Error(`unknown or stale ref ${ref[1]}`), { code: "stale_ref" });
+        scope = this.page.locator(`aria-ref=${ref[1]}`);
+      } else if (rawScope.startsWith("role=")) {
+        const value = rawScope.slice(5);
+        const [role, ...nameParts] = value.split(":");
+        if (!/^[-a-z]+$/.test(role) || nameParts.length && !nameParts.join(":").length)
+          throw Object.assign(new Error("scope must be eN, aria-ref=eN, role=<role>[:<name>], or testid=<id>"), { code: "invalid_params" });
+        scope = nameParts.length ? this.page.getByRole(role, { name: nameParts.join(":"), exact: true }) : this.page.getByRole(role);
+      } else if (rawScope.startsWith("testid=") && rawScope.slice(7))
         scope = this.page.getByTestId(rawScope.slice(7));
       else
-        scope = this.page.locator(rawScope);
+        throw Object.assign(new Error("scope must be eN, aria-ref=eN, role=<role>[:<name>], or testid=<id>"), { code: "invalid_params" });
+      const scopeCount = await scope.count();
+      if (scopeCount === 0)
+        throw Object.assign(new Error("scope does not match exactly one element"), { code: "scope_not_found" });
+      if (scopeCount > 1)
+        throw Object.assign(new Error("scope matches more than one element"), { code: "scope_ambiguous" });
     }
     const raw = await scope.ariaSnapshot({ mode: "ai" });
     const nodes = parseSnapshot(raw);
     await nameRows(this.page, nodes);
+    await nameContainers(this.page, nodes);
     const view = prune(nodes, this.redactor, await passwordRefs(this.page, nodes));
     const fullText = [...view.values()].map((node) => `  ${format(node, this.redactor)}`).join(`
 `);
@@ -451,7 +525,7 @@ class ExplorerView {
 ${await this.tableText(scope)}`;
     const text = `[page] ${this.redactor.url(url)} · ${this.redactor.text(await this.page.title())} [${mode}]
 ${body}`;
-    return { mode, text, stats: { raw: raw.length, pruned: fullText.length, sent: body.length } };
+    return { mode, text, settled, stats: { raw: raw.length, pruned: fullText.length, sent: body.length } };
   }
   async tableText(scope) {
     const rows = scope.locator("table tbody tr:visible, .el-table__body-wrapper tbody tr:visible");
@@ -490,6 +564,18 @@ function inferredRole(tag, type) {
     return;
   return { checkbox: "checkbox", radio: "radio", range: "slider" }[type ?? ""] ?? "textbox";
 }
+async function sameUnique(candidate, element) {
+  if (await candidate.count() !== 1)
+    return false;
+  const candidateHandle = await candidate.elementHandle();
+  if (!candidateHandle)
+    return false;
+  try {
+    return await element.evaluate((node, other) => node === other, candidateHandle);
+  } finally {
+    await candidateHandle.dispose();
+  }
+}
 
 class Recorder {
   page;
@@ -508,11 +594,29 @@ class Recorder {
     this.feature = feature;
     this.environmentProfile = environmentProfile;
     this.startUrl = startUrl;
-    this.steps.push({ action: "goto", url: new URL(startUrl).pathname });
+    const initial = new URL(redactor.url(startUrl));
+    this.steps.push({ action: "goto", url: `${initial.pathname}${initial.search}${initial.hash}` });
   }
   async unique(locator) {
     return await locator.count() === 1;
   }
+  async rowTarget(element, role, name) {
+    const row = element.locator("xpath=ancestor::tr[1]");
+    if (await row.count() !== 1)
+      return null;
+    const cells = row.locator(":scope > td:visible, :scope > th:visible");
+    for (let i = 0;i < await cells.count(); i++) {
+      const markerText = (await cells.nth(i).innerText()).replace(/\s+/g, " ").trim();
+      if (markerText.length < 2)
+        continue;
+      const rows = this.page.getByRole("row", { name: markerText, exact: false });
+      const inner = rows.getByRole(role, { name, exact: true });
+      if (await rows.count() === 1 && await sameUnique(inner, element)) {
+        return { locator: { within: { role: "row", name: markerText, exact: false }, role, name, exact: true }, data_dependent: true, reviewReasons: ["data_dependent_locator"] };
+      }
+    }
+    return null;
+  }
   async contextTarget(node, role, name) {
     const context = node.ctx.split(" > ").filter((item) => /^(dialog|alertdialog|form|navigation|banner|main|region)\b/.test(item)).pop();
     if (!context)
@@ -525,60 +629,10 @@ class Recorder {
     const within = contextName ? { role: contextRole, name: contextName, exact: true } : { role: contextRole };
     const root = contextName ? this.page.getByRole(contextRole, { name: contextName, exact: true }) : this.page.getByRole(contextRole);
     const inner = root.getByRole(role, { name, exact: true });
-    if (await this.unique(root) && await this.unique(inner))
+    if (await this.unique(root) && await sameUnique(inner, this.page.locator(`aria-ref=${node.ref}`)))
       return { locator: { within, role, name, exact: true } };
     return null;
   }
-  async elementPlusTarget(element, role, name) {
-    const row = element.locator("xpath=ancestor::tr[1]");
-    if (await row.count() !== 1)
-      return null;
-    const root = row.locator("xpath=ancestor::*[contains(concat(' ', normalize-space(@class), ' '), ' el-table ')][1]");
-    if (await root.count() !== 1)
-      return null;
-    const headers = root.locator(".el-table__header-wrapper th:visible");
-    const headerByClass = new Map;
-    for (let i = 0;i < await headers.count(); i++) {
-      const header = headers.nth(i);
-      const title = (await header.innerText()).replace(/\s+/g, " ").trim();
-      for (const className of (await header.getAttribute("class") ?? "").split(/\s+/)) {
-        if (/^el-table_\d+_column_\d+$/.test(className) && title)
-          headerByClass.set(className, title);
-      }
-    }
-    const cells = row.locator(":scope > td:visible");
-    let actionColumn = "";
-    let markerColumn = "";
-    let markerText = "";
-    for (let i = 0;i < await cells.count(); i++) {
-      const cell = cells.nth(i);
-      const text = (await cell.innerText()).replace(/\s+/g, " ").trim();
-      const className = (await cell.getAttribute("class") ?? "").split(/\s+/).find((item) => headerByClass.has(item));
-      const column = className ? headerByClass.get(className) ?? "" : "";
-      if (text && !markerText) {
-        markerText = text;
-        markerColumn = column;
-      }
-      if (column && await cell.getByRole(role, { name, exact: true }).count() > 0)
-        actionColumn = column;
-    }
-    if (!actionColumn || !markerColumn || !markerText)
-      return null;
-    const target = {
-      within: {
-        role: "row",
-        name: markerText,
-        exact: false
-      },
-      role,
-      name,
-      exact: true
-    };
-    const matchingRows = root.locator(".el-table__body-wrapper tbody tr:visible").filter({ hasText: markerText });
-    if (await matchingRows.count() !== 1 || !await this.unique(matchingRows.getByRole(role, { name, exact: true })))
-      return null;
-    return { locator: target, data_dependent: true };
-  }
   async targetFor(ref) {
     if (!this.view.hasRef(ref))
       throw Object.assign(new Error(`unknown or stale ref ${ref}`), { code: "stale_ref" });
@@ -589,27 +643,29 @@ class Recorder {
     if (await element.count() !== 1)
       throw Object.assign(new Error(`ref ${ref} is not unique`), { code: "stale_ref" });
     const testid = await element.getAttribute("data-testid");
-    if (testid && await this.unique(this.page.getByTestId(testid)))
+    if (testid && await sameUnique(this.page.getByTestId(testid), element))
       return { locator: `testid:${testid}` };
     const tag = await element.evaluate((item) => item.tagName.toLowerCase());
     const role = node.role || inferredRole(tag, await element.getAttribute("type"));
     const name = node.name;
     if (role && name) {
       const roleLocator = this.page.getByRole(role, { name, exact: true });
-      if (await this.unique(roleLocator))
-        return { locator: `role:${role}:${name}` };
+      const rowTarget = await this.rowTarget(element, role, name);
+      if (rowTarget)
+        return rowTarget;
+      if (await sameUnique(roleLocator, element)) {
+        const inRow2 = await element.locator("xpath=ancestor::tr[1]").count() === 1;
+        return { locator: `role:${role}:${name}`, ...inRow2 ? { data_dependent: true, reviewReasons: ["row_scope_missing"] } : {} };
+      }
       const within = await this.contextTarget(node, role, name);
       if (within)
         return within;
-      const tableTarget = await this.elementPlusTarget(element, role, name);
-      if (tableTarget)
-        return tableTarget;
     }
     const ariaLabel = await element.getAttribute("aria-label");
-    if (ariaLabel && await this.unique(this.page.getByLabel(ariaLabel, { exact: true })))
+    if (ariaLabel && await sameUnique(this.page.getByLabel(ariaLabel, { exact: true }), element))
       return { locator: `label:${ariaLabel}` };
     const placeholder = await element.getAttribute("placeholder");
-    if (placeholder && await this.unique(this.page.getByPlaceholder(placeholder, { exact: true })))
+    if (placeholder && await sameUnique(this.page.getByPlaceholder(placeholder, { exact: true }), element))
       return { locator: `placeholder:${placeholder}` };
     const candidates = [];
     if (testid)
@@ -618,19 +674,28 @@ class Recorder {
       candidates.push(`role:${role}:${name}`);
     if (placeholder)
       candidates.push(`placeholder:${placeholder}`);
-    return { needs_locator: true, candidates: candidates.map((candidate) => this.redactor.value(candidate)) };
+    const inRow = await element.locator("xpath=ancestor::tr[1]").count() === 1;
+    return { needs_locator: true, candidates: candidates.map((candidate) => this.redactor.value(candidate)), ...inRow ? { data_dependent: true, reviewReasons: ["row_scope_missing"] } : {} };
   }
   recordPrepared(id, action, target, extra = {}) {
     const step = { action, ...extra, locator: target.locator ?? "" };
     this.steps.push(step);
     this.explorationSteps.push({
       id,
+      action,
+      role: typeof target.locator === "object" && target.locator ? target.locator.role : undefined,
       ...target.needs_locator ? { needs_locator: true } : {},
       ...target.candidates ? { candidates: target.candidates } : {},
       ...target.data_dependent ? { data_dependent: true } : {},
+      ...target.reviewReasons ? { reviewReasons: target.reviewReasons } : {},
       ...action.startsWith("assert_") ? { oracle_hint: "characterization" } : {}
     });
   }
+  recordAssertionReview(id, kind, expectedFromPage, circular, targetName, weak = false) {
+    const item = this.explorationSteps.find((step) => step.id === id);
+    if (item)
+      Object.assign(item, { ...expectedFromPage ? { expected_from_page: true } : {}, ...circular ? { circular: true } : {}, ...weak ? { reviewReasons: [...item.reviewReasons ?? [], "weak_assertion"] } : {} });
+  }
   noteSecretVariable(name) {
     this.secretVariables.add(name);
   }
@@ -640,16 +705,50 @@ class Recorder {
     await fs.mkdir(root, { recursive: true, mode: 448 });
     const steps = this.steps.map((step, index) => ({ id: `s${String(index + 1).padStart(2, "0")}`, ...step }));
     const metadata = this.explorationSteps.map((item, index) => ({ ...item, id: `s${String(index + 2).padStart(2, "0")}` }));
-    const manual = metadata.filter((item) => item.needs_locator).map((item) => item.id);
+    const review_items = [];
+    const reviewKeys = new Set;
+    const addReview = (item) => {
+      const key = `${item.step}\x00${item.reason}`;
+      if (!reviewKeys.has(key)) {
+        reviewKeys.add(key);
+        review_items.push(item);
+      }
+    };
+    for (const item of metadata) {
+      for (const reason of item.reviewReasons ?? [])
+        addReview({ step: item.id, reason });
+      if (item.needs_locator)
+        addReview({ step: item.id, reason: "needs_locator" });
+      if (item.expected_from_page)
+        addReview({ step: item.id, reason: "expected_from_page" });
+      if (item.circular)
+        addReview({ step: item.id, reason: "circular_assertion" });
+      if (item.action === "assert_visible" && ["button", "link"].includes(item.role ?? ""))
+        addReview({ step: item.id, reason: "weak_assertion" });
+    }
+    const business = metadata.some((item) => item.action?.startsWith("assert_") && item.action !== "assert_visible" && !item.circular);
+    if (!business)
+      addReview({ step: "case", reason: "no_business_assertion" });
+    const manual = [...new Set(review_items.filter((item) => item.reason !== "expected_from_page" && item.reason !== "data_dependent_locator").map((item) => item.step))];
     const draft = {
       cases: [{ tc_id: tcId ?? "TC-0000", name: name.replace(/\.json$/, ""), variables: Object.fromEntries([...this.secretVariables].map((key) => [key, { secret: key }])), data: { setup: [], cleanup: [] }, steps }],
-      exploration: { environment_profile: this.environmentProfile, start_url: this.redactor.url(this.startUrl), recorded_steps: steps.length, needs_manual: manual, steps: metadata }
+      exploration: { environment_profile: this.environmentProfile, start_url: this.redactor.url(this.startUrl), recorded_steps: steps.length, needs_manual: manual, review_items, steps: metadata }
     };
     const output = path.join(root, fileName);
-    const serialized = this.redactor.text(JSON.stringify(draft, null, 2));
+    const redactLiterals = (value) => {
+      if (typeof value === "string")
+        return this.redactor.text(value);
+      if (Array.isArray(value))
+        return value.map(redactLiterals);
+      if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactLiterals(item)]));
+      }
+      return value;
+    };
+    const serialized = JSON.stringify(redactLiterals(draft), null, 2);
     await fs.writeFile(output, `${serialized}
 `, { mode: 384 });
-    return { path: output, manual };
+    return { path: output, manual, review_items };
   }
 }
 
@@ -660,8 +759,22 @@ var page = null;
 var view = null;
 var recorder = null;
 var redactor = null;
+var profileMemory = null;
 var idleTimer = null;
 var totalTimer = null;
+var requests = new RequestTracker;
+function installRequestCounter(currentContext) {
+  requests.clear();
+  currentContext.on("request", requests.started);
+  currentContext.on("requestfinished", requests.finished);
+  currentContext.on("requestfailed", requests.finished);
+}
+function removeRequestCounter() {
+  context?.off("request", requests.started);
+  context?.off("requestfinished", requests.finished);
+  context?.off("requestfailed", requests.finished);
+  requests.clear();
+}
 function reply(id, result) {
   process.stdout.write(`${JSON.stringify({ id, ok: true, result })}
 `);
@@ -680,12 +793,14 @@ async function shutdown() {
     clearTimeout(totalTimer);
   idleTimer = null;
   totalTimer = null;
+  removeRequestCounter();
   await browser?.close().catch(() => {});
   browser = null;
   context = null;
   page = null;
   view = null;
   recorder = null;
+  profileMemory = null;
 }
 function touch() {
   if (idleTimer)
@@ -708,6 +823,33 @@ function secretValue(key, profile) {
     throw Object.assign(new Error(`secret ${String(key)} is unavailable`), { code: "secret_unavailable" });
   return value;
 }
+async function settle(currentPage) {
+  const deadline = Date.now() + 8000;
+  await currentPage.waitForLoadState("domcontentloaded").catch(() => {});
+  if (!context)
+    return true;
+  let quietSince = 0;
+  let previousSnapshot = null;
+  while (Date.now() < deadline) {
+    if (requests.size === 0) {
+      if (!quietSince)
+        quietSince = Date.now();
+      if (Date.now() - quietSince >= 500) {
+        const snapshot = await currentPage.ariaSnapshot({ mode: "ai" }).catch(() => "");
+        if (previousSnapshot !== null && snapshot === previousSnapshot)
+          return true;
+        previousSnapshot = snapshot;
+        await new Promise((resolve) => setTimeout(resolve, 300));
+        continue;
+      }
+    } else {
+      quietSince = 0;
+      previousSnapshot = null;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return false;
+}
 async function doStart(request) {
   if (page)
     throw Object.assign(new Error("only one explore session is allowed"), { code: "session_exists" });
@@ -715,24 +857,32 @@ async function doStart(request) {
   if (!environmentFile || !path2.isAbsolute(environmentFile)) {
     throw Object.assign(new Error("environment profile path is missing"), { code: "environment_profile_invalid" });
   }
-  const profile = JSON.parse(fs2.readFileSync(environmentFile, "utf8"));
-  const policy = buildPolicy(profile);
-  redactor = new Redactor;
-  for (const envName of Object.values(profile.secret_env ?? {})) {
-    const value = process.env[envName];
-    if (value)
-      redactor.add(value);
-  }
-  browser = await chromium.launch();
-  context = await browser.newContext();
-  await new NetworkRecorder(redactor).install(context, policy);
-  page = await context.newPage();
-  const startUrl = absoluteUrl(String(request.params?.url ?? "/"), profile);
-  await page.goto(startUrl, { waitUntil: "domcontentloaded" });
-  view = new ExplorerView(page, redactor);
-  recorder = new Recorder(page, view, redactor, String(request.params?.feature ?? "explore"), profile.profile ?? path2.basename(environmentFile, path2.extname(environmentFile)), startUrl);
-  totalTimer = setTimeout(() => void shutdown(), 60 * 60 * 1000);
-  reply(request.id, await view.observe({ full: true }));
+  try {
+    const profile = JSON.parse(fs2.readFileSync(environmentFile, "utf8"));
+    profileMemory = profile;
+    const policy = buildPolicy(profile);
+    redactor = new Redactor;
+    for (const envName of Object.values(profile.secret_env ?? {})) {
+      const value = process.env[envName];
+      if (value)
+        redactor.add(value);
+    }
+    browser = await chromium.launch();
+    context = await browser.newContext();
+    installRequestCounter(context);
+    await new NetworkRecorder(redactor).install(context, policy);
+    page = await context.newPage();
+    const startUrl = absoluteUrl(String(request.params?.url ?? "/"), profile);
+    await page.goto(startUrl, { waitUntil: "domcontentloaded" });
+    const settled = await settle(page);
+    view = new ExplorerView(page, redactor);
+    recorder = new Recorder(page, view, redactor, String(request.params?.feature ?? "explore"), profile.profile ?? path2.basename(environmentFile, path2.extname(environmentFile)), startUrl);
+    totalTimer = setTimeout(() => void shutdown(), 60 * 60 * 1000);
+    reply(request.id, await view.observe({ full: true }, settled));
+  } catch (error) {
+    await shutdown();
+    throw error;
+  }
 }
 async function doAct(request) {
   const current = session();
@@ -745,10 +895,10 @@ async function doAct(request) {
   let value = request.params?.value;
   let secretKey;
   if (request.params?.value_from_secret !== undefined) {
-    const environmentFile = process.env.DEVFLOW_EXPLORE_ENVIRONMENT_FILE;
-    const profile = JSON.parse(fs2.readFileSync(environmentFile, "utf8"));
     secretKey = request.params.value_from_secret;
-    value = secretValue(secretKey, profile);
+    if (!profileMemory)
+      throw Object.assign(new Error("explore profile is unavailable"), { code: "environment_profile_invalid" });
+    value = secretValue(secretKey, profileMemory);
     current.redactor.add(value);
     current.recorder.noteSecretVariable(String(secretKey));
   }
@@ -775,14 +925,14 @@ async function doAct(request) {
     default:
       throw Object.assign(new Error(`unknown action ${action}`), { code: "invalid_params" });
   }
-  await current.page.waitForLoadState("domcontentloaded").catch(() => {});
+  const settled = await settle(current.page);
   const id = `s${String(current.recorder.steps.length + 1).padStart(2, "0")}`;
   const extra = {};
   if (action === "fill" || action === "select" || action === "press") {
     extra.value = secretKey === undefined ? current.redactor.text(String(value ?? "")) : `\${${String(secretKey)}}`;
   }
   current.recorder.recordPrepared(id, action, prepared, extra);
-  reply(request.id, await current.view.observe());
+  reply(request.id, { ...await current.view.observe({}, settled), settled });
 }
 async function doAssert(request) {
   const current = session();
@@ -798,24 +948,25 @@ async function doAssert(request) {
   const match = request.params?.match === "contains" ? "contains" : "exact";
   const normalizeWhitespace = request.params?.normalize_whitespace !== false;
   const caseSensitive = request.params?.case_sensitive !== false;
+  const matchesText = (actual, expected2) => textMatches(normalizeText(actual, normalizeWhitespace, caseSensitive), normalizeText(expected2, normalizeWhitespace, caseSensitive), match);
   if (kind === "visible") {
     if (!await locator.isVisible())
       throw Object.assign(new Error("element is not visible"), { code: "assertion_failed" });
   } else if (kind === "value") {
     const actual = await locator.inputValue();
     expected = String(requested ?? actual);
-    if (actual !== expected)
+    if (!matchesText(actual, expected))
       throw Object.assign(new Error(`value assertion failed: expected ${current.redactor.text(expected)}`), { code: "assertion_failed" });
   } else if (kind === "text") {
     const actual = await locator.innerText();
     expected = String(requested ?? actual.trim());
-    const matches = match === "contains" ? actual.includes(expected) : actual.trim() === expected;
+    const matches = matchesText(actual, expected);
     if (!matches)
       throw Object.assign(new Error(`text assertion failed: expected ${current.redactor.text(expected)}`), { code: "assertion_failed" });
   } else if (kind === "each_text") {
     const actual = await locator.allInnerTexts();
     expected = typeof requested === "string" ? requested : actual[0]?.trim() ?? "";
-    const matches = actual.every((item) => match === "contains" ? item.includes(expected) : item.trim() === expected);
+    const matches = actual.length > 0 && actual.every((item) => matchesText(item, expected));
     if (!matches)
       throw Object.assign(new Error("each_text assertion failed"), { code: "assertion_failed" });
   } else {
@@ -832,7 +983,16 @@ async function doAssert(request) {
     extra.case_sensitive = caseSensitive;
   }
   current.recorder.recordPrepared(`s${String(current.recorder.steps.length + 1).padStart(2, "0")}`, action, prepared, extra);
-  reply(request.id, { actual: current.redactor.value(kind === "each_text" ? await locator.allInnerTexts() : expected), view: await current.view.observe() });
+  const settled = await settle(current.page);
+  const targetName = current.view.node(ref)?.name ?? "";
+  const normalize = (value) => value.replace(/\s+/g, " ").trim();
+  const normalizedExpected = expected === undefined ? "" : normalize(expected);
+  const normalizedName = normalize(targetName);
+  const withinName = typeof prepared.locator === "object" && prepared.locator !== null ? String(prepared.locator.within?.name ?? "") : "";
+  const normalizedWithinName = normalize(withinName);
+  const circular = kind !== "visible" && Boolean(normalizedExpected && (normalizedName && (normalizedExpected.includes(normalizedName) || normalizedName.includes(normalizedExpected)) || normalizedWithinName && (normalizedExpected.includes(normalizedWithinName) || normalizedWithinName.includes(normalizedExpected))));
+  current.recorder.recordAssertionReview(`s${String(current.recorder.steps.length).padStart(2, "0")}`, kind, requested === undefined, circular, targetName, kind === "visible" && ["button", "link"].includes(current.view.node(ref)?.role ?? ""));
+  reply(request.id, { actual: current.redactor.value(kind === "each_text" ? await locator.allInnerTexts() : expected), view: await current.view.observe({}, settled), settled });
 }
 async function handle(request) {
   touch();
@@ -863,9 +1023,12 @@ async function handle(request) {
   }
 }
 var input = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+var requestQueue = Promise.resolve();
 input.on("line", (line) => {
   try {
-    handle(JSON.parse(line));
+    const request = JSON.parse(line);
+    requestQueue = requestQueue.then(() => handle(request)).catch((error) => process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`));
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}
 `);