@skyramp/mcp 0.4.1 → 0.4.2-rc.1

package/node_modules/playwright/lib/mcp/skyramp/loadTraceTool.js

@@ -31,6 +31,7 @@ module.exports = __toCommonJS(loadTraceTool_exports);
 var import_mcpBundle = require("playwright-core/lib/mcpBundle");
 var import_utils = require("playwright-core/lib/utils");
 var import_tool = require("../sdk/tool");
+var import_cssValue = require("./common/cssValue");
 var import_mouseActions = require("./common/mouseActions");
 const loadTraceSchema = {
   name: "skyramp_load_trace",
@@ -106,6 +107,12 @@ function describeStep(action, index) {
     detail += ` = ${JSON.stringify(a.text)}`;
   else if (a.name === "assertValue" && a.value !== void 0)
     detail += ` = ${JSON.stringify(a.value)}`;
+  else if (a.name === "assertCSS")
+    detail += ` ${a.cssName} = ${JSON.stringify(a.cssValue)}`;
+  else if (a.name === "assertClass")
+    detail += ` .${a.className}`;
+  else if (a.name === "assertAttribute")
+    detail += ` [${a.attrName}=${JSON.stringify(a.attrValue)}]`;
   else if (a.name === "press" && a.key !== void 0)
     detail += ` ${a.key}`;
   else if (a.name === "visualSnapshot")
@@ -358,6 +365,30 @@ async function performClientAction(page, actionInContext) {
         throw new Error(`assertValue failed: expected ${JSON.stringify(action.value)}, got ${JSON.stringify(actual)}`);
       return;
     }
+    // SKYR-4462: appearance assertions read the live element. Class and
+    // attribute match codegen's toHaveClass / toHaveAttribute exactly; the css
+    // replay normalises both sides (see common/cssValue), so it is more lenient
+    // than the generated toHaveCSS, which compares the computed string as is.
+    // The recorder writes the computed value, so the two agree on every
+    // recorded trace; the difference shows only on a hand-edited cssValue.
+    case "assertCSS": {
+      const actual = (await locator.evaluate((el, prop) => getComputedStyle(el).getPropertyValue(prop), String(action.cssName), opts)).trim();
+      if ((0, import_cssValue.normalizeCssValue)(actual, String(action.cssName)) !== (0, import_cssValue.normalizeCssValue)(String(action.cssValue), String(action.cssName)))
+        throw new Error(`assertCSS failed: expected ${action.cssName} ${JSON.stringify(action.cssValue)}, got ${JSON.stringify(actual)}`);
+      return;
+    }
+    case "assertClass": {
+      const classes = await locator.evaluate((el) => Array.from(el.classList), void 0, opts);
+      if (!classes.includes(String(action.className)))
+        throw new Error(`assertClass failed: expected class ${JSON.stringify(action.className)}, got [${classes.join(" ")}]`);
+      return;
+    }
+    case "assertAttribute": {
+      const actual = await locator.evaluate((el, attr) => el.getAttribute(attr), String(action.attrName), opts);
+      if (actual !== action.attrValue)
+        throw new Error(`assertAttribute failed: expected ${action.attrName}=${JSON.stringify(action.attrValue)}, got ${JSON.stringify(actual)}`);
+      return;
+    }
     case "assertChecked": {
       const checked = await locator.isChecked(opts);
       if (checked !== !!action.checked)

package/node_modules/playwright/lib/mcp/skyramp/skyRampImport.js

@@ -67,6 +67,9 @@ const ACTION_NAMES = /* @__PURE__ */ new Set([
   "assertSnapshot",
   "visualSnapshot",
   "assertTableCell",
+  "assertCSS",
+  "assertClass",
+  "assertAttribute",
   "dragTo",
   "dragAndDrop",
   "diagramNodeAdd",

package/node_modules/playwright/lib/mcp/skyramp/traceRecordingBackend.js

@@ -53,6 +53,7 @@ var import_resultCode = require("./resultCode");
 var import_mouseActionTool = require("./mouseActionTool");
 var import_visualSnapshotTool = require("./visualSnapshotTool");
 var import_gojsTool = require("./gojsTool");
+var import_cssValue = require("./common/cssValue");
 var import_visualSnapshot = require("./common/visualSnapshot");
 var import_tableAssertTool = require("./tableAssertTool");
 var import_tableSelectorBuilder = require("./tableSelectorBuilder");
@@ -80,6 +81,9 @@ function dropDynamicParentChain(chain) {
   const m = /^locator\(['"]#(.+)['"]\)$/.exec(chain);
   return m && (0, import_dynamicId.isDynamicId)(m[1]) ? null : chain;
 }
+const LIVE_READ_TIMEOUT_MS = 5e3;
+const MAX_ANCESTOR_HOVERS = 8;
+const ANCESTOR_WALK_BUDGET_MS = 1e4;
 class TraceRecordingBackend {
   // per-type baseline filename counter
   constructor(options) {
@@ -872,6 +876,24 @@ Continue recording with browser_* tools, then call skyramp_export_zip to write t
         if (typeof a.disabled !== "boolean")
           return null;
         return { toolName: "browser_assert", code: `assertDisabled:${a.selector}:${a.disabled}`, args: { type: "disabled", selector: a.selector, disabled: a.disabled } };
+      // SKYR-4462: appearance assertions loaded from a trace keep their fields so
+      // load-and-continue exports them again; a line missing its property or
+      // value would seed a matcher with a hole in it and is dropped instead.
+      case "assertCSS": {
+        if (typeof a.selector !== "string" || !a.selector || typeof a.cssName !== "string" || !a.cssName.trim() || typeof a.cssValue !== "string" || !a.cssValue.trim())
+          return null;
+        return { toolName: "browser_assert", code: `assertCSS:${a.selector}:${a.cssName.trim()}:${a.cssValue}`, args: { type: "css", selector: a.selector, property: a.cssName.trim(), expected: a.cssValue } };
+      }
+      case "assertClass": {
+        if (typeof a.selector !== "string" || !a.selector || typeof a.className !== "string" || !a.className.trim())
+          return null;
+        return { toolName: "browser_assert", code: `assertClass:${a.selector}:${a.className.trim()}`, args: { type: "class", selector: a.selector, expected: a.className.trim() } };
+      }
+      case "assertAttribute": {
+        if (typeof a.selector !== "string" || !a.selector || typeof a.attrName !== "string" || !a.attrName.trim() || typeof a.attrValue !== "string")
+          return null;
+        return { toolName: "browser_assert", code: `assertAttribute:${a.selector}:${a.attrName.trim()}:${a.attrValue}`, args: { type: "attribute", selector: a.selector, property: a.attrName.trim(), expected: a.attrValue } };
+      }
       case "assertCount":
         if (typeof a.count !== "number" || !Number.isInteger(a.count) || a.count < 0)
           return null;
@@ -1276,13 +1298,25 @@ Linked GoJS nodes ${params.fromKey} \u2192 ${params.toKey} (${params.fromPort}\u
   }
   /**
    * Handle browser_assert by using browser_hover to resolve the ref to a
-   * proper Playwright selector (testid > role > text), then verify the
-   * assertion against the snapshot data.
+   * proper Playwright selector (testid > role > text), then verify
+   * text/value/checked/disabled/visible/count against the snapshot data, and
+   * css/class/attribute against the live element (getComputedStyle / classList
+   * / getAttribute, read with the pointer moved off the element). Only passing
+   * assertions are recorded.
    */
   async _handleAssert(params) {
     const timestamp = Date.now();
     if (!params.expected && (params.type === "text" || params.type === "value" || params.type === "count"))
       return { content: [{ type: "text", text: '### Error\n"expected" parameter is required.' }], isError: true };
+    if ((params.type === "css" || params.type === "class") && !params.expected?.trim())
+      return { content: [{ type: "text", text: '### Error\n"expected" parameter is required and must not be blank.' }], isError: true };
+    if (params.type === "attribute" && params.expected === void 0)
+      return { content: [{ type: "text", text: '### Error\n"expected" parameter is required (an empty string is a valid attribute value).' }], isError: true };
+    if ((params.type === "css" || params.type === "attribute") && !params.property?.trim())
+      return { content: [{ type: "text", text: `### Error
+For "${params.type}" assertions, "property" (the ${params.type === "css" ? "CSS property" : "attribute name"}) is required.` }], isError: true };
+    if (params.type === "class" && /\s/.test(params.expected.trim()))
+      return { content: [{ type: "text", text: '### Error\nFor "class" assertions, "expected" is one class name; call once per class.' }], isError: true };
     if (params.type === "count" && !/^\d+$/.test(params.expected))
       return { content: [{ type: "text", text: '### Error\nFor "count" assertions, "expected" must be a non-negative integer.' }], isError: true };
     if ((params.type === "checked" || params.type === "disabled") && params.expected !== void 0 && params.expected !== "true" && params.expected !== "false")
@@ -1329,17 +1363,101 @@ Could not parse locator: ${locatorExpr}` }], isError: true };
     const elementText = textMatch?.[1] || "";
     const valueMatch = refLine.match(/\]:\s*(.+)$/);
     const elementValue = valueMatch?.[1]?.trim() || "";
-    if (parsed.locator.kind === "text") {
-      const improved = await this._improveTextSelector(snapLines, params.ref, parsed);
-      if (improved) {
-        traceDebug(`Improved ambiguous text selector to: ${improved.selector}`);
-        parsed = improved;
-      }
-    }
     let passed = false;
     let details = "";
     let countSelector = "";
-    if (params.type === "text") {
+    let liveValue;
+    let unhoverMove;
+    if (params.type === "css" || params.type === "class" || params.type === "attribute") {
+      const tab = this._browserBackend.context?.currentTab();
+      if (!tab)
+        return { content: [{ type: "text", text: "### Assertion Failed\nNo active page." }], isError: true };
+      const notReady = await this._requireLoadedPage(tab, "domcontentloaded");
+      if (notReady)
+        return notReady;
+      if (parsed.locator.kind === "text") {
+        const improved = await this._improveTextSelector(snapLines, params.ref, parsed);
+        if (improved) {
+          traceDebug(`Improved ambiguous text selector before live read: ${improved.selector}`);
+          parsed = improved;
+        }
+      }
+      const live = tab.page.locator(parsed.selector);
+      const kind = params.type;
+      const name = kind === "class" ? "" : params.property.trim();
+      const read = () => live.evaluate((el, a) => {
+        const e = el;
+        const r = e.getBoundingClientRect();
+        const hovered = e.matches(":hover");
+        let value = null;
+        let unknownProperty = false;
+        if (a.kind === "css") {
+          const css = globalThis.CSS;
+          const supported = a.name.startsWith("--") || !css?.supports || css.supports(a.name, "initial");
+          if (!supported)
+            unknownProperty = true;
+          else
+            value = getComputedStyle(e).getPropertyValue(a.name).trim();
+        } else if (a.kind === "class") {
+          value = Array.from(e.classList).join(" ");
+        } else {
+          value = e.getAttribute(a.name);
+        }
+        return { value, hovered, unknownProperty, rect: { left: r.left, top: r.top, right: r.right, bottom: r.bottom }, vw: window.innerWidth, vh: window.innerHeight };
+      }, { kind, name }, { timeout: LIVE_READ_TIMEOUT_MS });
+      try {
+        let reading = await read();
+        if (reading.hovered) {
+          const { rect, vw, vh } = reading;
+          const clamp = (v, lo, hi) => Math.min(Math.max(v, lo), hi);
+          const midX = clamp((rect.left + rect.right) / 2, 1, vw - 1);
+          const midY = clamp((rect.top + rect.bottom) / 2, 1, vh - 1);
+          const target = rect.bottom + 8 < vh ? { x: midX, y: rect.bottom + 8 } : rect.top - 8 >= 0 ? { x: midX, y: rect.top - 8 } : rect.right + 8 < vw ? { x: rect.right + 8, y: midY } : rect.left - 8 >= 0 ? { x: rect.left - 8, y: midY } : null;
+          if (target) {
+            let moved = true;
+            await tab.page.mouse.move(target.x, target.y).catch((e) => {
+              moved = false;
+              traceDebug(`un-hover move failed: ${e.message}`);
+            });
+            reading = await read();
+            if (moved && !reading.hovered)
+              unhoverMove = target;
+          }
+          if (reading.hovered)
+            return { content: [{ type: "text", text: `### Error
+Could not read the un-hovered state of "${params.element}": the pointer could not be moved off it (it fills the viewport, or the move failed). A :hover-dependent value would be recorded wrongly \u2014 assert a property the hover does not change, or use a wider element.` }], isError: true };
+        }
+        if (kind === "css") {
+          if (reading.unknownProperty)
+            return { content: [{ type: "text", text: `### Error
+"${name}" is not a CSS property this browser knows; check the spelling (e.g. "flex-direction", "background-color").` }], isError: true };
+          const actual = reading.value ?? "";
+          passed = (0, import_cssValue.normalizeCssValue)(actual, name) === (0, import_cssValue.normalizeCssValue)(params.expected, name);
+          liveValue = actual;
+          details = passed ? `CSS assertion passed: "${params.element}" has ${name}: ${actual}.` : `CSS assertion FAILED: "${params.element}" has ${name}: ${actual || "(empty)"}, expected ${params.expected}.`;
+        } else if (kind === "class") {
+          const className = params.expected.trim();
+          const classes = (reading.value ?? "").split(" ").filter(Boolean);
+          passed = classes.includes(className);
+          details = passed ? `Class assertion passed: "${params.element}" carries class "${className}".` : `Class assertion FAILED: "${params.element}" has classes [${classes.join(" ")}], expected "${className}".`;
+        } else {
+          const actual = reading.value;
+          passed = actual !== null && actual === params.expected;
+          liveValue = actual ?? void 0;
+          details = passed ? `Attribute assertion passed: "${params.element}" has ${name}="${actual}".` : `Attribute assertion FAILED: "${params.element}" has ${name}=${actual === null ? "(absent)" : `"${actual}"`}, expected "${params.expected}".`;
+        }
+      } catch (e) {
+        const msg = String(e?.message ?? e);
+        if (/strict mode violation/i.test(msg))
+          return { content: [{ type: "text", text: `### Error
+Target ${parsed.selector} matches multiple elements, so the ${kind} read is ambiguous. Use a more specific target (a data-testid, or role + exact name). ${msg.split("\n")[0]}` }], isError: true };
+        if (e?.name === "TimeoutError")
+          return { content: [{ type: "text", text: `### Error
+"${params.element}" (${parsed.selector}) did not resolve within ${LIVE_READ_TIMEOUT_MS} ms. Re-snapshot and retry with a fresh ref.` }], isError: true };
+        return { content: [{ type: "text", text: `### Error
+Could not read ${kind} of "${params.element}": ${msg}` }], isError: true };
+      }
+    } else if (params.type === "text") {
       passed = elementText.includes(params.expected) || elementValue.includes(params.expected);
       details = passed ? `Text assertion passed: "${params.element}" contains "${params.expected}".` : `Text assertion FAILED: "${params.element}" has text "${elementText}"${elementValue ? ` / value "${elementValue}"` : ""}, expected "${params.expected}".`;
     } else if (params.type === "value") {
@@ -1399,6 +1517,13 @@ Could not count "${refRole}" elements: ${e.message}` }], isError: true };
       if (tautological) {
         traceDebug(`Skipped tautological assertion: selector already matches "${recordedExpected}"`);
       } else {
+        if (parsed.locator.kind === "text" && params.type !== "count" && params.type !== "css" && params.type !== "class" && params.type !== "attribute") {
+          const improved = await this._improveTextSelector(snapLines, params.ref, parsed);
+          if (improved) {
+            traceDebug(`Improved ambiguous text selector to: ${improved.selector}`);
+            parsed = improved;
+          }
+        }
         let assertName;
         let args;
         let code;
@@ -1432,13 +1557,30 @@ Could not count "${refRole}" elements: ${e.message}` }], isError: true };
             args = { type: "value", ref: params.ref, selector: parsed.selector, expected: recordedExpected };
             code = `assertValue:${parsed.selector}:${recordedExpected}`;
             break;
+          case "css":
+            assertName = "assertCSS";
+            args = { type: "css", ref: params.ref, selector: parsed.selector, property: params.property.trim(), expected: liveValue ?? params.expected };
+            code = `assertCSS:${parsed.selector}:${params.property.trim()}:${liveValue ?? params.expected}`;
+            break;
+          case "class":
+            assertName = "assertClass";
+            args = { type: "class", ref: params.ref, selector: parsed.selector, expected: params.expected.trim() };
+            code = `assertClass:${parsed.selector}:${params.expected.trim()}`;
+            break;
+          case "attribute":
+            assertName = "assertAttribute";
+            args = { type: "attribute", ref: params.ref, selector: parsed.selector, property: params.property.trim(), expected: liveValue ?? params.expected };
+            code = `assertAttribute:${parsed.selector}:${params.property.trim()}:${liveValue ?? params.expected}`;
+            break;
           default:
             assertName = "assertText";
             args = { type: "text", ref: params.ref, selector: parsed.selector, expected: recordedExpected, substring: params.substring };
             code = `assertText:${parsed.selector}:${recordedExpected}:${params.substring}`;
             break;
         }
-        this._trackedActions.push({ toolName: "browser_assert", args, code, timestamp });
+        if (unhoverMove)
+          this._trackedActions.push({ toolName: "browser_mouse_action", args: { name: "mouse.move", position: unhoverMove }, code: "", timestamp: timestamp - 1, pageAlias: this._currentPageAlias });
+        this._trackedActions.push({ toolName: "browser_assert", args, code, timestamp, pageAlias: this._currentPageAlias });
         traceDebug(`Assert: ${assertName} with selector ${args.selector}`);
       }
     }
@@ -1670,7 +1812,7 @@ ${text}` }], isError: true });
     let details;
     if (passed) {
       details = `Hidden assertion passed: "${params.element}" is absent or not visible.`;
-      this._trackedActions.push({ toolName: "browser_assert", args: { type: "hidden", selector, locator }, code: `assertHidden:${selector}`, timestamp });
+      this._trackedActions.push({ toolName: "browser_assert", args: { type: "hidden", selector, locator }, code: `assertHidden:${selector}`, timestamp, pageAlias: this._currentPageAlias });
       traceDebug(`Assert: assertHidden with selector ${selector}`);
     } else {
       const count = await tab.page.locator(selector).count().catch(() => -1);
@@ -1730,7 +1872,10 @@ ${details}` }] };
    */
   async _improveTextSelector(snapLines, ref, original) {
     const textBody = original.locator.body;
-    const occurrences = snapLines.filter((l) => l.includes(textBody)).length;
+    const occurrences = snapLines.filter((l) => {
+      const lineText = TraceRecordingBackend._snapshotLineText(l);
+      return lineText !== null && lineText.includes(textBody);
+    }).length;
     if (occurrences <= 1)
       return null;
     traceDebug(`Text "${textBody}" appears ${occurrences} times in snapshot \u2014 looking for parent test-id`);
@@ -1738,16 +1883,24 @@ ${details}` }] };
     const refIdx = snapLines.findIndex((l) => l.includes(refPattern));
     if (refIdx < 0)
       return null;
-    const refIndent = snapLines[refIdx].match(/^(\s*)/)?.[1]?.length ?? 0;
+    let currentIndent = snapLines[refIdx].match(/^(\s*)/)?.[1]?.length ?? 0;
+    const deadline = Date.now() + ANCESTOR_WALK_BUDGET_MS;
+    let hovers = 0;
     for (let i = refIdx - 1; i >= 0; i--) {
       const line = snapLines[i];
       const indent = line.match(/^(\s*)/)?.[1]?.length ?? 0;
-      if (indent >= refIndent)
+      if (indent >= currentIndent)
         continue;
       const ancestorRefMatch = line.match(/\[ref=(\w+)\]/);
       if (!ancestorRefMatch)
         continue;
+      if (hovers >= MAX_ANCESTOR_HOVERS || Date.now() >= deadline) {
+        traceDebug(`Ancestor walk stopped after ${hovers} hovers \u2014 depth or time budget reached`);
+        break;
+      }
       const ancestorRef = ancestorRefMatch[1];
+      currentIndent = indent;
+      hovers++;
       try {
         const ancestorHover = await this._browserBackend.callTool("browser_hover", {
           element: "parent element",
@@ -1782,6 +1935,19 @@ ${details}` }] };
     }
     return null;
   }
+  /**
+   * Text value of an aria-snapshot line, in either form the renderer emits:
+   * `- generic "foo" [ref=e1]` (quoted accessible name) or
+   * `- generic [ref=e1]: foo` (colon-delimited text for nodes with no name).
+   * Returns null for a line that carries no text.
+   */
+  static _snapshotLineText(line) {
+    const quoted = line.match(/^\s*-\s*\w+\s+"([^"]*)"/);
+    if (quoted)
+      return quoted[1];
+    const colon = line.match(/\[ref=\w+\](?:\s*\[[^\]]*\])*\s*:\s*(.+?)\s*$/);
+    return colon?.[1]?.trim() || null;
+  }
   static {
     /** Extract selector and locator info from a snapshot line for assertion tracking. */
     // Roles that map to valid Playwright getByRole() selectors.

package/node_modules/playwright/lib/mcp/test/skyRampExport.js

@@ -441,6 +441,8 @@ function assertActionToJsonl(action, pageGuid, timestamp) {
       expected = String(args.disabled === true || args.expected === "true" || args.expected === true);
     } else if (assertType === "count") {
       expected = String(args.count ?? args.expected ?? "");
+    } else if (assertType === "css" || assertType === "class" || assertType === "attribute") {
+      expected = typeof args.expected === "string" ? args.expected : "";
     }
   } else {
     const parts = code.split(":");
@@ -475,6 +477,26 @@ function assertActionToJsonl(action, pageGuid, timestamp) {
         return null;
       return JSON.stringify({ name: "assertCount", selector, count, locator, ...base });
     }
+    // SKYR-4462: appearance assertions — toHaveCSS / toHaveClass / toHaveAttribute
+    // downstream. A line missing its property or value would emit a matcher with
+    // a hole in it, so it is dropped (reported as skipped) instead.
+    case "css": {
+      const cssName = typeof args.property === "string" ? args.property.trim() : "";
+      if (!cssName || !expected)
+        return null;
+      return JSON.stringify({ name: "assertCSS", selector, cssName, cssValue: expected, locator, ...base });
+    }
+    case "class": {
+      if (!expected.trim())
+        return null;
+      return JSON.stringify({ name: "assertClass", selector, className: expected.trim(), locator, ...base });
+    }
+    case "attribute": {
+      const attrName = typeof args.property === "string" ? args.property.trim() : "";
+      if (!attrName || typeof args.expected !== "string")
+        return null;
+      return JSON.stringify({ name: "assertAttribute", selector, attrName, attrValue: expected, locator, ...base });
+    }
     default:
       return null;
   }
@@ -805,6 +827,8 @@ function buildJsonlContent(actions, browserName, harPath, viewport = RECORDING_V
       if (assertLine) {
         lines.push(assertLine);
         actionCount++;
+      } else {
+        skipped.push(action.toolName);
       }
       continue;
     }