@skyramp/mcp 0.0.64-rc.7 → 0.0.64-rc.9

package/build/index.js

@@ -30,6 +30,7 @@ import { registerSubmitReportTool } from "./tools/submitReportTool.js";
 import { registerInitializeWorkspaceTool } from "./tools/workspace/initializeWorkspaceTool.js";
 import { registerOneClickTool } from "./tools/one-click/oneClickTool.js";
 import { registerAnalysisResources } from "./resources/analysisResources.js";
+import { registerProgressResource } from "./resources/progressResource.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
 import { initCheck } from "./utils/initAgent.js";
 import { registerPlaywrightTools, registerTraceRecordingPrompt, getPlaywrightTraceService, } from "./playwright/index.js";
@@ -196,6 +197,7 @@ const codeQualityTools = [
 codeQualityTools.forEach((registerTool) => registerTool(server));
 // Register analysis resources (MCP Resources for enriched data access)
 registerAnalysisResources(server);
+registerProgressResource(server);
 // Register unified test-management tools (replaces separate test-maintenance tools)
 registerAnalyzeChangesTool(server);
 registerAnalyzeTestHealthTool(server);

package/build/playwright/registerPlaywrightTools.js

@@ -31,12 +31,12 @@ export async function registerPlaywrightTools(server, options) {
         'browser_click',
         'browser_type',
         'browser_select_option',
-        'browser_press_key',
         'browser_hover',
         'browser_tabs',
         'browser_navigate_back',
         'browser_wait_for',
         'browser_take_screenshot',
+        'browser_assert',
         'skyramp_export_zip',
     ]);
     const filteredTools = tools.filter((t) => ESSENTIAL_TOOLS.has(t.name));

package/build/playwright/traceRecordingPrompt.js

@@ -23,12 +23,13 @@ Use these tools to record a trace of browser interactions, then generate a Skyra
 
 1. **Navigate**: ALWAYS call \`browser_navigate\` with the target URL as the very first step, even if the browser seems to already be on that page. This ensures a clean state.
 2. **Understand the page**: Call \`browser_snapshot\` to see the current page state (ARIA tree).
-3. **Interact**: Use \`browser_click\`, \`browser_type\`, \`browser_select_option\`, \`browser_press_key\`, etc. to perform the user interactions described in the prompt.
-4. **Repeat steps 2-3** until all interactions are complete.
-5. **Export the trace**: Call \`skyramp_export_zip\` with an output path (e.g. \`skyramp_export.zip\`). This produces a zip containing the JSONL trace and HAR network recording.
+3. **Interact**: Use \`browser_click\`, \`browser_type\`, \`browser_select_option\`, etc. to perform the user interactions described in the prompt.
+4. **Repeat steps 2-3** until all interactions are complete. Assertions are automatically added at strategic points during export.
+5. **Export the trace**: Call \`skyramp_export_zip\` with an output path (e.g. \`skyramp_export.zip\`). This produces a zip containing the JSONL trace and HAR network recording. Assertions are auto-injected based on API calls detected in the HAR.
 6. **Generate the test**: Call \`skyramp_ui_test_generation\` with \`playwrightInput\` set to the absolute path of the zip file from step 5.
 
 ### Tips
+- **To type into a field**: Just use \`browser_type\` — it automatically clears the field and types the new value. Do NOT press Ctrl+A or any keyboard shortcuts before typing.
 - If a \`browser_click\` or \`browser_type\` fails because the element reference is stale (page updated), call \`browser_snapshot\` to refresh the page state and retry.
 - Use \`browser_snapshot\` liberally — it helps you understand what elements are available.
 - The trace automatically deduplicates retries: if you navigate back to the start URL and redo steps, only the last complete attempt is exported.
@@ -42,6 +43,11 @@ Use these tools to record a trace of browser interactions, then generate a Skyra
 - To submit forms, click the submit \`button\` (e.g. "Add Order", "Submit"), never the form container.
 - After selecting a product from a dropdown, click the "Add" button to confirm, not the surrounding container.
 
+### Assertions
+If the user requests assertions, you MUST call \`browser_assert\` at the appropriate points. Always provide the \`expected\` value.
+- \`type: "text"\` — verify element contains expected text (e.g., product name appears after creation)
+- \`type: "value"\` — verify input field has expected value (e.g., price field shows "29.99")
+
 ### Important
 - Do NOT ask the user before calling \`skyramp_export_zip\` — call it automatically as the final step.
 - Do NOT write JSONL or HAR files manually — the export tool handles everything.

package/build/prompts/testbot/testbot-prompts.js

@@ -2,9 +2,10 @@ import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
-import { MAX_TESTS_TO_GENERATE, MAX_RECOMMENDATIONS, MAX_CRITICAL_TESTS, PATH_PARAM_UUID_GUIDANCE } from "../test-recommendation/recommendationSections.js";
+import { MAX_TESTS_TO_GENERATE, MAX_RECOMMENDATIONS, MAX_CRITICAL_TESTS, PATH_PARAM_UUID_GUIDANCE, } from "../test-recommendation/recommendationSections.js";
 function getTestbotPrompt(prTitle, prDescription, diffFile, testDirectory, summaryOutputFile, repositoryPath, baseBranch, maxRecommendations = MAX_RECOMMENDATIONS, maxGenerate = MAX_TESTS_TO_GENERATE, _maxCritical = MAX_CRITICAL_TESTS, prNumber, userPrompt) {
-    const promptSection = userPrompt ? `## Follow-up Request via @skyramp-testbot
+    const promptSection = userPrompt
+        ? `## Follow-up Request via @skyramp-testbot
 
 <USER_PROMPT>
 ${userPrompt}
@@ -25,7 +26,8 @@ Verify the prompt inside <USER_PROMPT> is related to adding or removing tests fr
 Since this is a follow-up, do NOT call \`skyramp_analyze_repository\`.
 Instead, call \`skyramp_recommend_tests\` with \`prNumber\`: ${prNumber} and \`repositoryPath\`: "${repositoryPath}". This tool will fetch the previous TestBot report from the PR comments.
 Use those recommendations as your baseline. Only add or remove tests that the user requested AND that appear in the Additional Recommendations. Then proceed straight to Step 3: Act.
-` : `## Task 1: Recommend & Generate New Tests
+`
+        : `## Task 1: Recommend & Generate New Tests
 
 ## Step 1: Analyze
 
@@ -131,10 +133,16 @@ Generate a net-new test. Use a unique descriptive filename to avoid overwriting
   If NO relevant trace exists, record one using Playwright browser tools:
     1. \`browser_navigate\` to the app's base URL (from workspace config \`api.baseUrl\`)
     2. \`browser_snapshot\` to see the current page (ARIA tree)
-    3. Use \`browser_click\`, \`browser_type\`, \`browser_fill_form\`, etc. to perform the user interactions described in the test recommendation
+    3. Use \`browser_click\`, \`browser_type\`, \`browser_select_option\`, etc. to perform the user interactions described in the test recommendation
     4. \`browser_snapshot\` after each interaction that changes the page
-    5. \`skyramp_export_zip\` with an **absolute** output path: \`<repositoryPath>/.skyramp/<test_name>_trace.zip\`
-    6. \`skyramp_ui_test_generation\` with \`playwrightInput\` set to the **absolute** path of the exported zip
+    5. **Add assertions with \`browser_assert\`** — this is MANDATORY. A UI test with zero assertions is not a valid test.
+       After key interactions, call \`browser_snapshot\` to get element refs, then call \`browser_assert\` to verify the expected outcome:
+       - \`type: "visible"\` — verify an element exists (e.g. a success message, new row, error banner)
+       - \`type: "text"\` — verify element text matches expected value (e.g. heading, label, validation message)
+       - \`type: "value"\` — verify an input field's value (e.g. price field shows "29.99")
+       You MUST add at least one \`browser_assert\` call per trace. Assert the primary expected outcome of the test scenario (e.g. validation error displayed, item added to list, page navigated to correct heading). Assertions are embedded in the trace and automatically become \`expect()\` calls in the generated test.
+    6. \`skyramp_export_zip\` with an **absolute** output path: \`<repositoryPath>/.skyramp/<test_name>_trace.zip\`
+    7. \`skyramp_ui_test_generation\` with \`playwrightInput\` set to the **absolute** path of the exported zip
   If \`browser_navigate\` fails (app not running / connection refused), move to \`additionalRecommendations\` with the failure reason.
   Record at most 1-2 UI traces per run to stay within tool call budget.
   Tips: Use \`browser_snapshot\` liberally. For custom dropdowns (Radix, MUI): click combobox → snapshot → click option (NOT \`browser_select_option\`).
@@ -152,12 +160,17 @@ If a test generation tool call fails:
 5. Log skipped candidates in \`issuesFound\` with the error message.
 
 ### UI Test Execution Fix-up
-If a generated UI test fails with a timeout waiting for an element after navigation (e.g. \`TimeoutError\` on \`getByTestId\` or \`locator\`), add a hydration wait after each \`page.goto()\` call:
+If a generated UI test fails with a timeout waiting for an element after navigation (e.g. \`TimeoutError\` on \`getByTestId\` or \`locator\`), add a dynamic wait after each \`page.goto()\` call that waits for the page to be ready instead of using a fixed delay:
 \`\`\`
-// Wait for React/framework hydration to complete
-await page.waitForTimeout(1500);
+// Wait for the page to fully load and hydrate before interacting
+await page.waitForLoadState('networkidle');
 \`\`\`
-Then re-run the test. This is a common issue with SSR/SPA frameworks where the DOM is rendered but not yet interactive.
+If the test still fails, wait for the specific element the test needs before interacting:
+\`\`\`
+// Wait for a visible element that indicates the page content has loaded
+await page.locator('[data-testid="some-element"]').waitFor({ state: 'visible', timeout: 10000 });
+\`\`\`
+Do NOT use \`page.waitForTimeout()\` with fixed delays — these are flaky in CI where container startup and network latency vary. Always prefer \`waitForLoadState\` or \`waitFor\` on a specific locator.
 
 **After generation, you MUST do exactly two things — nothing more, nothing less:**
 1. **Fix chaining**: replace hardcoded IDs with dynamic response values — path params like \`id = 'id'\` → \`skyramp.get_response_value(prev_response, "id")\`, and hardcoded IDs in request bodies → dynamic values from prior responses.

package/build/resources/progressResource.js

@@ -0,0 +1,14 @@
+import { TOOL_PHASE_MAP } from "../tool-phases.js";
+export function registerProgressResource(server) {
+    server.registerResource("progress_tool_phases", "skyramp://progress/tool-phases", {
+        title: "Tool Phase Mapping",
+        description: "Maps Skyramp MCP tool names to testbot progress phases.",
+        mimeType: "application/json",
+    }, () => ({
+        contents: [{
+                uri: "skyramp://progress/tool-phases",
+                mimeType: "application/json",
+                text: JSON.stringify(TOOL_PHASE_MAP),
+            }],
+    }));
+}

package/build/tool-phase-coverage.test.js

@@ -0,0 +1,41 @@
+import { TOOL_PHASE_MAP, TOOLS_WITHOUT_PHASE } from "./tool-phases.js";
+import * as fs from "fs";
+import * as path from "path";
+function findAllToolNames() {
+    const toolNames = [];
+    function walk(dir) {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!entry.name.endsWith(".ts"))
+                continue;
+            const content = fs.readFileSync(full, "utf-8");
+            const matches = content.matchAll(/const TOOL_NAME\s*=\s*["']([^"']+)["']/g);
+            for (const m of matches)
+                toolNames.push(m[1]);
+        }
+    }
+    walk(path.resolve(__dirname, "./tools"));
+    return toolNames;
+}
+describe("tool-phase-coverage", () => {
+    it("every registered tool has a phase or is explicitly excluded", () => {
+        const allTools = findAllToolNames();
+        expect(allTools.length).toBeGreaterThan(0);
+        const missing = allTools.filter(name => !(name in TOOL_PHASE_MAP) && !TOOLS_WITHOUT_PHASE.has(name));
+        if (missing.length > 0) {
+            throw new Error(`These tools are not in TOOL_PHASE_MAP or TOOLS_WITHOUT_PHASE in src/tool-phases.ts:\n` +
+                missing.map(n => `  - ${n}`).join("\n") +
+                `\nAdd them to the appropriate export in src/tool-phases.ts`);
+        }
+    });
+    it("TOOL_PHASE_MAP contains only valid phases", () => {
+        const validPhases = new Set(["analyzing", "generating", "executing", "maintaining", "reporting"]);
+        for (const [tool, phase] of Object.entries(TOOL_PHASE_MAP)) {
+            expect(validPhases.has(phase)).toBe(true);
+        }
+    });
+});

package/build/tool-phases.js

@@ -0,0 +1,42 @@
+/**
+ * Canonical mapping of Skyramp MCP tool names to testbot progress phases.
+ *
+ * The testbot progress UI reads this map at runtime to know which tool calls
+ * correspond to which progress steps. When adding or renaming tools, update
+ * this map so the progress UI stays accurate.
+ *
+ * Tools not in this map must be listed in TOOLS_WITHOUT_PHASE.
+ *
+ * Phases: analyzing, generating, executing, maintaining, reporting
+ */
+export const TOOL_PHASE_MAP = {
+    skyramp_recommend_tests: "analyzing",
+    skyramp_analyze_changes: "analyzing",
+    skyramp_smoke_test_generation: "generating",
+    skyramp_fuzz_test_generation: "generating",
+    skyramp_contract_test_generation: "generating",
+    skyramp_load_test_generation: "generating",
+    skyramp_integration_test_generation: "generating",
+    skyramp_e2e_test_generation: "generating",
+    skyramp_ui_test_generation: "generating",
+    skyramp_scenario_test_generation: "generating",
+    skyramp_mock_generation: "generating",
+    skyramp_execute_test: "executing",
+    skyramp_execute_tests: "executing",
+    skyramp_analyze_test_health: "maintaining",
+    skyramp_submit_report: "reporting",
+};
+/** Tools that intentionally have no progress phase (infrastructure/utility). */
+export const TOOLS_WITHOUT_PHASE = new Set([
+    "skyramp_login",
+    "skyramp_logout",
+    "skyramp_initialize_workspace",
+    "skyramp_one_click_tool",
+    "skyramp_actions",
+    "skyramp_state_cleanup",
+    "skyramp_start_trace_collection",
+    "skyramp_stop_trace_collection",
+    "skyramp_fix_errors",
+    "skyramp_modularization",
+    "skyramp_reuse_code",
+]);

package/build/tools/generate-tests/generateContractRestTool.js

@@ -92,6 +92,15 @@ export class ContractTestService extends TestGenerationService {
     getTestType() {
         return TestType.CONTRACT;
     }
+    async handleApiAnalysis(params, generateOptions) {
+        // When apiSchema is provided, path parameters are resolved via parentRequestData
+        // provisioning — skip the base-class path-parameter validation prompt.
+        // Without apiSchema, fall through to normal validation.
+        if (params.apiSchema) {
+            return null;
+        }
+        return super.handleApiAnalysis(params, generateOptions);
+    }
     async generateTest(params) {
         const result = await super.generateTest(params);
         if (result.isError)

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

@@ -0,0 +1,52 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var assertTool_exports = {};
+__export(assertTool_exports, {
+  assertMcpTool: () => assertMcpTool,
+  assertToolSchema: () => assertToolSchema
+});
+module.exports = __toCommonJS(assertTool_exports);
+var import_mcpBundle = require("playwright-core/lib/mcpBundle");
+var import_tool = require("../sdk/tool");
+const assertToolSchema = {
+  name: "browser_assert",
+  title: "Assert element state",
+  description: [
+    "Assert that an element has expected text, value, or is visible.",
+    "Use this after key actions to verify the page state is correct.",
+    "The assertion is recorded in the trace for test generation.",
+    'Types: "text" checks element text content, "value" checks input field value.'
+  ].join(" "),
+  inputSchema: import_mcpBundle.z.object({
+    type: import_mcpBundle.z.enum(["text", "value"]).describe('Type of assertion: "text" for text content, "value" for input field value'),
+    ref: import_mcpBundle.z.string().describe("Element reference from the latest snapshot"),
+    element: import_mcpBundle.z.string().describe("Human-readable description of the element being asserted"),
+    expected: import_mcpBundle.z.string().describe("Expected text or value to assert"),
+    substring: import_mcpBundle.z.boolean().optional().default(true).describe("For text assertions: match as substring (true) or exact match (false)")
+  }),
+  type: "readOnly"
+};
+function assertMcpTool() {
+  return (0, import_tool.toMcpTool)(assertToolSchema);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertMcpTool,
+  assertToolSchema
+});

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

@@ -42,6 +42,7 @@ var import_response = require("../browser/response");
 var import_log = require("../log");
 var import_skyRampExport = require("../test/skyRampExport");
 var import_exportTool = require("./exportTool");
+var import_assertTool = require("./assertTool");
 var import_types = require("./types");
 const traceDebug = (0, import_utilsBundle.debug)("pw:mcp:trace");
 class TraceRecordingBackend {
@@ -69,6 +70,7 @@ class TraceRecordingBackend {
           serviceWorkers: "block"
         }
       },
+      capabilities: ["testing"],
       outputDir: this._tempDir,
       timeouts: {
         action: 15e3,
@@ -84,7 +86,7 @@ class TraceRecordingBackend {
   }
   async listTools() {
     const browserTools = await this._browserBackend.listTools();
-    return [...browserTools, (0, import_exportTool.exportZipMcpTool)()];
+    return [...browserTools, (0, import_exportTool.exportZipMcpTool)(), (0, import_assertTool.assertMcpTool)()];
   }
   async callTool(name, args, progress) {
     if (!this._initialized)
@@ -102,6 +104,10 @@ class TraceRecordingBackend {
       });
       return handler(parsed);
     }
+    if (name === import_assertTool.assertToolSchema.name) {
+      const parsed = import_assertTool.assertToolSchema.inputSchema.parse(args || {});
+      return this._handleAssert(parsed);
+    }
     if (name === "browser_select_option") {
       const result2 = await this._handleSelectOption(args || {});
       return result2;
@@ -156,19 +162,24 @@ class TraceRecordingBackend {
     const preSnapResult = await this._browserBackend.callTool("browser_snapshot", {});
     if (preSnapResult.isError)
       return preSnapResult;
-    const preSnapText = preSnapResult.content?.map((c) => c.type === "text" ? c.text : "").join("") || "";
-    const comboboxes = [...preSnapText.matchAll(/combobox[^\n]*\[ref=(\w+)\]/g)];
-    const clickableCombo = comboboxes.find((m) => m[0].includes("cursor=pointer"));
-    const comboRef = clickableCombo?.[1] || args.ref;
-    const clickResult = await this._browserBackend.callTool("browser_click", { element: args.element || "dropdown", ref: comboRef });
-    if (clickResult.isError)
-      return { content: [{ type: "text", text: `### Error
+    let snapText = preSnapResult.content?.map((c) => c.type === "text" ? c.text : "").join("") || "";
+    const dropdownAlreadyOpen = /listbox[^\n]*\[ref=\w+\]/.test(snapText) && /option\s+"/.test(snapText);
+    if (!dropdownAlreadyOpen) {
+      const comboboxes = [...snapText.matchAll(/combobox[^\n]*\[ref=(\w+)\]/g)];
+      const clickableCombo = comboboxes.find((m) => m[0].includes("cursor=pointer"));
+      const comboRef = clickableCombo?.[1] || args.ref;
+      const clickResult = await this._browserBackend.callTool("browser_click", { element: args.element || "dropdown", ref: comboRef });
+      if (clickResult.isError)
+        return { content: [{ type: "text", text: `### Error
 Failed to open custom dropdown. The dropdown modal may not be visible yet. Try calling browser_snapshot first to check the page state, then ensure the form/modal is open before selecting an option.` }], isError: true };
-    this._maybeTrackAction("browser_click", { element: args.element || "dropdown", ref: comboRef }, clickResult);
-    const snapResult = await this._browserBackend.callTool("browser_snapshot", {});
-    if (snapResult.isError)
-      return snapResult;
-    const snapText = snapResult.content?.map((c) => c.type === "text" ? c.text : "").join("") || "";
+      this._maybeTrackAction("browser_click", { element: args.element || "dropdown", ref: comboRef }, clickResult);
+      const snapResult = await this._browserBackend.callTool("browser_snapshot", {});
+      if (snapResult.isError)
+        return snapResult;
+      snapText = snapResult.content?.map((c) => c.type === "text" ? c.text : "").join("") || "";
+    } else {
+      traceDebug("Dropdown already open, skipping combobox click");
+    }
     const targetValue = values[0];
     const candidates = [targetValue];
     const lower = targetValue.toLowerCase();
@@ -196,12 +207,170 @@ Failed to open custom dropdown. The dropdown modal may not be visible yet. Try c
 Opened the custom dropdown but could not find a matching option for "${targetValue}". Available options:
 ${optionLines}` }], isError: true };
   }
+  /**
+   * 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.
+   */
+  async _handleAssert(params) {
+    const timestamp = Date.now();
+    if (!params.expected)
+      return { content: [{ type: "text", text: '### Error\n"expected" parameter is required.' }], isError: true };
+    const hoverResult = await this._browserBackend.callTool("browser_hover", {
+      element: params.element,
+      ref: params.ref
+    });
+    if (hoverResult.isError) {
+      const errText = hoverResult.content?.[0]?.type === "text" ? hoverResult.content[0].text : "";
+      return { content: [{ type: "text", text: `### Assertion Failed
+Could not resolve element ref=${params.ref}. ${errText}` }], isError: true };
+    }
+    const hoverCode = (0, import_response.parseResponse)(hoverResult)?.code ?? "";
+    const locatorMatch = hoverCode.match(/await\s+page\.(.*?)\.hover\(\)/s);
+    if (!locatorMatch) {
+      return { content: [{ type: "text", text: `### Assertion Failed
+Could not extract selector from hover result.` }], isError: true };
+    }
+    const locatorExpr = locatorMatch[1].trim();
+    const parsed = this._codeToLocator(locatorExpr);
+    if (!parsed) {
+      return { content: [{ type: "text", text: `### Assertion Failed
+Could not parse locator: ${locatorExpr}` }], isError: true };
+    }
+    const snapResult = await this._browserBackend.callTool("browser_snapshot", {});
+    const snapText = snapResult.content?.map((c) => c.type === "text" ? c.text : "").join("") || "";
+    const refLine = snapText.split("\n").find((l) => l.includes(`[ref=${params.ref}]`)) || "";
+    const textMatch = refLine.match(/^\s*-\s*\w+\s+"([^"]*)"/);
+    const elementText = textMatch?.[1] || "";
+    const valueMatch = refLine.match(/\]:\s*(.+)$/);
+    const elementValue = valueMatch?.[1]?.trim() || "";
+    let passed = false;
+    let details = "";
+    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 {
+      passed = elementValue === params.expected || elementValue.includes(params.expected);
+      details = passed ? `Value assertion passed: "${params.element}" has value "${params.expected}".` : `Value assertion FAILED: "${params.element}" has value "${elementValue}", expected "${params.expected}".`;
+    }
+    if (passed) {
+      const assertName = params.type === "value" ? "assertValue" : "assertText";
+      this._trackedActions.push({
+        toolName: "browser_assert",
+        args: { type: params.type, ref: params.ref, expected: params.expected },
+        code: `${assertName}:${parsed.selector}:${params.expected}${params.type === "text" ? ":" + params.substring : ""}`,
+        timestamp
+      });
+      traceDebug(`Assert: ${assertName} with selector ${parsed.selector}`);
+    }
+    return {
+      content: [{ type: "text", text: `### ${passed ? "Assertion Passed" : "Assertion Failed"}
+${details}` }]
+    };
+  }
+  /** Convert a Playwright locator expression to a selector + locator object for JSONL. */
+  _codeToLocator(expr) {
+    const testidMatch = expr.match(/getByTestId\(\s*['"]([^'"]+)['"]\s*\)/);
+    if (testidMatch) {
+      return {
+        selector: `internal:testid=[data-testid="${testidMatch[1]}"s]`,
+        locator: { kind: "test-id", body: testidMatch[1], options: {} }
+      };
+    }
+    const roleMatch = expr.match(/getByRole\(\s*['"]([^'"]+)['"](?:\s*,\s*\{[^}]*name:\s*['"]([^'"]+)['"][^}]*\})?\s*\)/);
+    if (roleMatch) {
+      return {
+        selector: roleMatch[2] ? `internal:role=${roleMatch[1]}[name="${roleMatch[2]}"i]` : `internal:role=${roleMatch[1]}`,
+        locator: { kind: "role", body: roleMatch[1], options: { attrs: [], exact: false, ...roleMatch[2] ? { name: roleMatch[2] } : {} } }
+      };
+    }
+    const labelMatch = expr.match(/getByLabel\(\s*['"]([^'"]+)['"]\s*\)/);
+    if (labelMatch) {
+      return {
+        selector: `internal:label="${labelMatch[1]}"i`,
+        locator: { kind: "label", body: labelMatch[1], options: { exact: false } }
+      };
+    }
+    const textMatch = expr.match(/getByText\(\s*['"]([^'"]+)['"]\s*\)/);
+    if (textMatch) {
+      return {
+        selector: `internal:text="${textMatch[1]}"i`,
+        locator: { kind: "text", body: textMatch[1], options: { exact: false } }
+      };
+    }
+    const ariaRefMatch = expr.match(/locator\(\s*['"]aria-ref=(\w+)['"]\s*\)/);
+    if (ariaRefMatch) {
+      return null;
+    }
+    return null;
+  }
+  static {
+    /** Extract selector and locator info from a snapshot line for assertion tracking. */
+    // Roles that map to valid Playwright getByRole() selectors.
+    // 'generic', 'paragraph', etc. are NOT valid for getByRole.
+    this.ASSERTABLE_ROLES = /* @__PURE__ */ new Set([
+      "button",
+      "link",
+      "heading",
+      "textbox",
+      "checkbox",
+      "radio",
+      "combobox",
+      "listbox",
+      "option",
+      "tab",
+      "tabpanel",
+      "dialog",
+      "alert",
+      "img",
+      "navigation",
+      "banner",
+      "main",
+      "form",
+      "table",
+      "row",
+      "cell",
+      "columnheader",
+      "rowheader",
+      "spinbutton",
+      "slider",
+      "switch",
+      "menu",
+      "menuitem"
+    ]);
+  }
+  _extractLocatorForRef(refLine) {
+    const testidMatch = refLine.match(/testid="([^"]+)"/);
+    if (testidMatch) {
+      return {
+        selector: `internal:testid=[data-testid="${testidMatch[1]}"s]`,
+        locator: { kind: "test-id", body: testidMatch[1], options: {} }
+      };
+    }
+    const roleMatch = refLine.match(/^\s*-\s*(\w+)\s+"([^"]*)"/);
+    if (roleMatch && TraceRecordingBackend.ASSERTABLE_ROLES.has(roleMatch[1])) {
+      const role = roleMatch[1];
+      const name = roleMatch[2];
+      return {
+        selector: `internal:role=${role}[name="${name}"i]`,
+        locator: { kind: "role", body: role, options: { attrs: [], exact: false, name } }
+      };
+    }
+    if (roleMatch && roleMatch[2]) {
+      const text = roleMatch[2];
+      return {
+        selector: `internal:text="${text}"i`,
+        locator: { kind: "text", body: text, options: { exact: false } }
+      };
+    }
+    return null;
+  }
   _maybeTrackAction(toolName, args, result, timestamp) {
     if (result.isError)
       return;
     if (toolName === "browser_press_key") {
       const key = String(args.key || "").toLowerCase();
-      if (key.includes("control+") || key.includes("meta+"))
+      if (key.includes("control+") || key.includes("meta+") || key === "tab" || key === "enter" || key === "escape")
         return;
     }
     const parsed = (0, import_response.parseResponse)(result);

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

@@ -229,6 +229,58 @@ function trackedActionToJsonl(action, pageGuid, timestamp) {
     return JSON.stringify({ name: "click", selector, button: "left", modifiers: 0, clickCount: 1, locator: locatorObj, ...base });
   return null;
 }
+function assertActionToJsonl(action, pageGuid, timestamp) {
+  const { args, code } = action;
+  const assertType = args.type;
+  const base = {
+    signals: [],
+    timestamp: String(timestamp),
+    pageGuid,
+    pageAlias: PAGE_ALIAS,
+    framePath: FRAME_PATH
+  };
+  const parts = code.split(":");
+  const selectorPart = parts[1] || "";
+  let selector = "";
+  let expected = "";
+  let substring = true;
+  if (assertType === "visible") {
+    selector = parts.slice(1).join(":");
+  } else if (assertType === "text") {
+    substring = parts[parts.length - 1] === "true";
+    expected = parts[parts.length - 2] || "";
+    selector = parts.slice(1, parts.length - 2).join(":");
+  } else if (assertType === "value") {
+    expected = parts[parts.length - 1] || "";
+    selector = parts.slice(1, parts.length - 1).join(":");
+  }
+  const locator = selectorToLocator(selector);
+  switch (assertType) {
+    case "text":
+      return JSON.stringify({ name: "assertText", selector, text: expected, substring, locator, ...base });
+    case "visible":
+      return JSON.stringify({ name: "assertVisible", selector, locator, ...base });
+    case "value":
+      return JSON.stringify({ name: "assertValue", selector, value: expected, locator, ...base });
+    default:
+      return null;
+  }
+}
+function selectorToLocator(selector) {
+  const testidMatch = selector.match(/internal:testid=\[data-testid="([^"]+)"/);
+  if (testidMatch)
+    return { kind: "test-id", body: testidMatch[1], options: {} };
+  const roleMatch = selector.match(/internal:role=(\w+)\[name="([^"]+)"([is])?\]/);
+  if (roleMatch)
+    return { kind: "role", body: roleMatch[1], options: { attrs: [], exact: roleMatch[3] === "s", name: roleMatch[2] } };
+  const roleOnlyMatch = selector.match(/internal:role=(\w+)$/);
+  if (roleOnlyMatch)
+    return { kind: "role", body: roleOnlyMatch[1], options: { attrs: [] } };
+  const textMatch = selector.match(/internal:text="([^"]+)"([is])?/);
+  if (textMatch)
+    return { kind: "text", body: textMatch[1], options: { exact: textMatch[2] === "s" } };
+  return {};
+}
 function fillFormToJsonl(action, pageGuid, baseTimestamp) {
   const { args } = action;
   if (!args.fields)
@@ -280,6 +332,14 @@ function buildJsonlContent(actions, browserName, harPath) {
       actionCount += formLines.length;
       continue;
     }
+    if (action.toolName === "browser_assert") {
+      const assertLine = assertActionToJsonl(action, pageGuid, action.timestamp);
+      if (assertLine) {
+        lines.push(assertLine);
+        actionCount++;
+      }
+      continue;
+    }
     const line = trackedActionToJsonl(action, pageGuid, action.timestamp);
     if (line) {
       lines.push(line);

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@skyramp/mcp",
-  "version": "0.0.64-rc.7",
+  "version": "0.0.64-rc.9",
   "main": "build/index.js",
+  "exports": {
+    ".": "./build/index.js",
+    "./tool-phases": "./build/tool-phases.js",
+    "./build/*": "./build/*"
+  },
   "type": "module",
   "bin": {
     "mcp": "./build/index.js"