@wdio/mcp 2.2.1 → 2.3.1

package/lib/server.js

@@ -14,10 +14,11 @@ var startBrowserToolDefinition = {
   description: "starts a browser session (Chrome, Firefox, Edge, Safari) and sets it to the current state",
   inputSchema: {
     browser: browserSchema.describe("Browser to launch: chrome, firefox, edge, safari (default: chrome)"),
-    headless: z.boolean().optional(),
+    headless: z.boolean().optional().default(true),
     windowWidth: z.number().min(400).max(3840).optional().default(1920),
     windowHeight: z.number().min(400).max(2160).optional().default(1080),
-    navigationUrl: z.string().optional().describe("URL to navigate to after starting the browser")
+    navigationUrl: z.string().optional().describe("URL to navigate to after starting the browser"),
+    capabilities: z.record(z.string(), z.unknown()).optional().describe("Additional W3C capabilities to merge with defaults (e.g. goog:chromeOptions args/extensions/prefs)")
   }
 };
 var closeSessionToolDefinition = {
@@ -42,10 +43,11 @@ var getBrowser = () => {
 getBrowser.__state = state;
 var startBrowserTool = async ({
   browser = "chrome",
-  headless = false,
+  headless = true,
   windowWidth = 1920,
   windowHeight = 1080,
-  navigationUrl
+  navigationUrl,
+  capabilities: userCapabilities = {}
 }) => {
   const browserDisplayNames = {
     chrome: "Chrome",
@@ -98,8 +100,35 @@ var startBrowserTool = async ({
       capabilities.browserName = "safari";
       break;
   }
+  const mergeCapabilityOptions = (defaultOptions, customOptions) => {
+    if (!defaultOptions || typeof defaultOptions !== "object" || !customOptions || typeof customOptions !== "object") {
+      return customOptions ?? defaultOptions;
+    }
+    const defaultRecord = defaultOptions;
+    const customRecord = customOptions;
+    const merged = { ...defaultRecord, ...customRecord };
+    if (Array.isArray(defaultRecord.args) || Array.isArray(customRecord.args)) {
+      merged.args = [
+        ...Array.isArray(defaultRecord.args) ? defaultRecord.args : [],
+        ...Array.isArray(customRecord.args) ? customRecord.args : []
+      ];
+    }
+    return merged;
+  };
+  const mergedCapabilities = {
+    ...capabilities,
+    ...userCapabilities,
+    "goog:chromeOptions": mergeCapabilityOptions(capabilities["goog:chromeOptions"], userCapabilities["goog:chromeOptions"]),
+    "ms:edgeOptions": mergeCapabilityOptions(capabilities["ms:edgeOptions"], userCapabilities["ms:edgeOptions"]),
+    "moz:firefoxOptions": mergeCapabilityOptions(capabilities["moz:firefoxOptions"], userCapabilities["moz:firefoxOptions"])
+  };
+  for (const [key, value] of Object.entries(mergedCapabilities)) {
+    if (value === void 0) {
+      delete mergedCapabilities[key];
+    }
+  }
   const wdioBrowser = await remote({
-    capabilities
+    capabilities: mergedCapabilities
   });
   const { sessionId } = wdioBrowser;
   state.browsers.set(sessionId, wdioBrowser);
@@ -346,7 +375,8 @@ var startAppToolDefinition = {
     udid: z5.string().optional().describe('Unique Device Identifier for iOS real device testing (e.g., "00008030-001234567890002E")'),
     noReset: z5.boolean().optional().describe("Do not reset app state before session (preserves app data). Default: false"),
     fullReset: z5.boolean().optional().describe("Uninstall app before/after session. Default: true. Set to false with noReset=true to preserve app state completely"),
-    newCommandTimeout: z5.number().min(0).optional().describe("How long (in seconds) Appium will wait for a new command before assuming the client has quit and ending the session. Default: 60. Set to 300 for 5 minutes, etc.")
+    newCommandTimeout: z5.number().min(0).optional().describe("How long (in seconds) Appium will wait for a new command before assuming the client has quit and ending the session. Default: 60. Set to 300 for 5 minutes, etc."),
+    capabilities: z5.record(z5.string(), z5.unknown()).optional().describe("Additional Appium/WebDriver capabilities to merge with defaults (e.g. appium:udid, appium:chromedriverExecutable, appium:autoWebview)")
   }
 };
 var getState = () => {
@@ -374,7 +404,8 @@ var startAppTool = async (args) => {
       udid,
       noReset,
       fullReset,
-      newCommandTimeout
+      newCommandTimeout,
+      capabilities: userCapabilities = {}
     } = args;
     if (!appPath && noReset !== true) {
       return {
@@ -412,12 +443,21 @@ var startAppTool = async (args) => {
       fullReset,
       newCommandTimeout
     });
+    const mergedCapabilities = {
+      ...capabilities,
+      ...userCapabilities
+    };
+    for (const [key, value] of Object.entries(mergedCapabilities)) {
+      if (value === void 0) {
+        delete mergedCapabilities[key];
+      }
+    }
     const browser = await remote2({
       protocol: "http",
       hostname: serverConfig.hostname,
       port: serverConfig.port,
       path: serverConfig.path,
-      capabilities
+      capabilities: mergedCapabilities
     });
     const { sessionId } = browser;
     const shouldAutoDetach = noReset === true || !appPath;
@@ -426,7 +466,7 @@ var startAppTool = async (args) => {
     state2.currentSession = sessionId;
     state2.sessionMetadata.set(sessionId, {
       type: platform.toLowerCase(),
-      capabilities,
+      capabilities: mergedCapabilities,
       isAttached: shouldAutoDetach
     });
     const appInfo = appPath ? `
@@ -483,160 +523,157 @@ var scrollTool = async ({ direction, pixels = 500 }) => {
 };
 
 // src/scripts/get-interactable-browser-elements.ts
-var elementsScript = (elementType = "interactable") => (function() {
+var elementsScript = (includeBounds) => (function() {
   const interactableSelectors = [
     "a[href]",
-    // Links with href
     "button",
-    // Buttons
     'input:not([type="hidden"])',
-    // Input fields (except hidden)
     "select",
-    // Select dropdowns
     "textarea",
-    // Text areas
     '[role="button"]',
-    // Elements with button role
     '[role="link"]',
-    // Elements with link role
     '[role="checkbox"]',
-    // Elements with checkbox role
     '[role="radio"]',
-    // Elements with radio role
     '[role="tab"]',
-    // Elements with tab role
     '[role="menuitem"]',
-    // Elements with menuitem role
     '[role="combobox"]',
-    // Elements with combobox role
     '[role="option"]',
-    // Elements with option role
     '[role="switch"]',
-    // Elements with switch role
     '[role="slider"]',
-    // Elements with slider role
     '[role="textbox"]',
-    // Elements with textbox role
     '[role="searchbox"]',
-    // Elements with searchbox role
+    '[role="spinbutton"]',
     '[contenteditable="true"]',
-    // Editable content
     '[tabindex]:not([tabindex="-1"])'
-    // Elements with tabindex
-  ];
-  const visualSelectors = [
-    "img",
-    // Images
-    "picture",
-    // Picture elements
-    "svg",
-    // SVG graphics
-    "video",
-    // Video elements
-    "canvas",
-    // Canvas elements
-    '[style*="background-image"]'
-    // Elements with background images
-  ];
+  ].join(",");
   function isVisible(element) {
     if (typeof element.checkVisibility === "function") {
-      return element.checkVisibility({
-        opacityProperty: true,
-        visibilityProperty: true,
-        contentVisibilityAuto: true
-      });
+      return element.checkVisibility({ opacityProperty: true, visibilityProperty: true, contentVisibilityAuto: true });
     }
     const style = window.getComputedStyle(element);
     return style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0" && element.offsetWidth > 0 && element.offsetHeight > 0;
   }
-  function getCssSelector(element) {
-    if (element.id) {
-      return `#${CSS.escape(element.id)}`;
+  function getAccessibleName(el) {
+    const ariaLabel = el.getAttribute("aria-label");
+    if (ariaLabel) return ariaLabel.trim();
+    const labelledBy = el.getAttribute("aria-labelledby");
+    if (labelledBy) {
+      const texts = labelledBy.split(/\s+/).map((id) => document.getElementById(id)?.textContent?.trim() || "").filter(Boolean);
+      if (texts.length > 0) return texts.join(" ").slice(0, 100);
+    }
+    const tag = el.tagName.toLowerCase();
+    if (tag === "img" || tag === "input" && el.getAttribute("type") === "image") {
+      const alt = el.getAttribute("alt");
+      if (alt !== null) return alt.trim();
+    }
+    if (["input", "select", "textarea"].includes(tag)) {
+      const id = el.getAttribute("id");
+      if (id) {
+        const label = document.querySelector(`label[for="${CSS.escape(id)}"]`);
+        if (label) return label.textContent?.trim() || "";
+      }
+      const parentLabel = el.closest("label");
+      if (parentLabel) {
+        const clone = parentLabel.cloneNode(true);
+        clone.querySelectorAll("input,select,textarea").forEach((n) => n.remove());
+        const lt = clone.textContent?.trim();
+        if (lt) return lt;
+      }
+    }
+    const ph = el.getAttribute("placeholder");
+    if (ph) return ph.trim();
+    const title = el.getAttribute("title");
+    if (title) return title.trim();
+    return (el.textContent?.trim().replace(/\s+/g, " ") || "").slice(0, 100);
+  }
+  function getSelector(element) {
+    const tag = element.tagName.toLowerCase();
+    const text = element.textContent?.trim().replace(/\s+/g, " ");
+    if (text && text.length > 0 && text.length <= 50) {
+      const sameTagElements = document.querySelectorAll(tag);
+      let matchCount = 0;
+      sameTagElements.forEach((el) => {
+        if (el.textContent?.includes(text)) matchCount++;
+      });
+      if (matchCount === 1) return `${tag}*=${text}`;
+    }
+    const ariaLabel = element.getAttribute("aria-label");
+    if (ariaLabel && ariaLabel.length <= 80) return `aria/${ariaLabel}`;
+    const testId = element.getAttribute("data-testid");
+    if (testId) {
+      const sel = `[data-testid="${CSS.escape(testId)}"]`;
+      if (document.querySelectorAll(sel).length === 1) return sel;
+    }
+    if (element.id) return `#${CSS.escape(element.id)}`;
+    const nameAttr = element.getAttribute("name");
+    if (nameAttr) {
+      const sel = `${tag}[name="${CSS.escape(nameAttr)}"]`;
+      if (document.querySelectorAll(sel).length === 1) return sel;
     }
     if (element.className && typeof element.className === "string") {
       const classes = element.className.trim().split(/\s+/).filter(Boolean);
-      if (classes.length > 0) {
-        const classSelector = classes.slice(0, 2).map((c) => `.${CSS.escape(c)}`).join("");
-        const tagWithClass = `${element.tagName.toLowerCase()}${classSelector}`;
-        if (document.querySelectorAll(tagWithClass).length === 1) {
-          return tagWithClass;
-        }
+      for (const cls of classes) {
+        const sel = `${tag}.${CSS.escape(cls)}`;
+        if (document.querySelectorAll(sel).length === 1) return sel;
+      }
+      if (classes.length >= 2) {
+        const sel = `${tag}${classes.slice(0, 2).map((c) => `.${CSS.escape(c)}`).join("")}`;
+        if (document.querySelectorAll(sel).length === 1) return sel;
       }
     }
     let current = element;
     const path = [];
     while (current && current !== document.documentElement) {
-      let selector = current.tagName.toLowerCase();
+      let seg = current.tagName.toLowerCase();
       if (current.id) {
-        selector = `#${CSS.escape(current.id)}`;
-        path.unshift(selector);
+        path.unshift(`#${CSS.escape(current.id)}`);
         break;
       }
       const parent = current.parentElement;
       if (parent) {
-        const siblings = Array.from(parent.children).filter(
-          (child) => child.tagName === current.tagName
-        );
-        if (siblings.length > 1) {
-          const index = siblings.indexOf(current) + 1;
-          selector += `:nth-child(${index})`;
-        }
+        const siblings = Array.from(parent.children).filter((c) => c.tagName === current.tagName);
+        if (siblings.length > 1) seg += `:nth-of-type(${siblings.indexOf(current) + 1})`;
       }
-      path.unshift(selector);
+      path.unshift(seg);
       current = current.parentElement;
-      if (path.length >= 4) {
-        break;
-      }
+      if (path.length >= 4) break;
     }
     return path.join(" > ");
   }
-  function getElements() {
-    const selectors = [];
-    if (elementType === "interactable" || elementType === "all") {
-      selectors.push(...interactableSelectors);
-    }
-    if (elementType === "visual" || elementType === "all") {
-      selectors.push(...visualSelectors);
-    }
-    const allElements = [];
-    selectors.forEach((selector) => {
-      const elements = document.querySelectorAll(selector);
-      elements.forEach((element) => {
-        if (!allElements.includes(element)) {
-          allElements.push(element);
-        }
-      });
-    });
-    const elementInfos = allElements.filter((element) => isVisible(element) && !element.disabled).map((element) => {
-      const el = element;
-      const inputEl = element;
-      const rect = el.getBoundingClientRect();
-      const isInViewport = rect.top >= 0 && rect.left >= 0 && rect.bottom <= (window.innerHeight || document.documentElement.clientHeight) && rect.right <= (window.innerWidth || document.documentElement.clientWidth);
-      const info = {
-        tagName: el.tagName.toLowerCase(),
-        type: el.getAttribute("type") || "",
-        id: el.id || "",
-        className: (typeof el.className === "string" ? el.className : "") || "",
-        textContent: el.textContent?.trim() || "",
-        value: inputEl.value || "",
-        placeholder: inputEl.placeholder || "",
-        href: el.getAttribute("href") || "",
-        ariaLabel: el.getAttribute("aria-label") || "",
-        role: el.getAttribute("role") || "",
-        src: el.getAttribute("src") || "",
-        alt: el.getAttribute("alt") || "",
-        cssSelector: getCssSelector(el),
-        isInViewport
+  const elements = [];
+  const seen = /* @__PURE__ */ new Set();
+  document.querySelectorAll(interactableSelectors).forEach((el) => {
+    if (seen.has(el)) return;
+    seen.add(el);
+    const htmlEl = el;
+    if (!isVisible(htmlEl)) return;
+    const inputEl = htmlEl;
+    const rect = htmlEl.getBoundingClientRect();
+    const isInViewport = rect.top >= 0 && rect.left >= 0 && rect.bottom <= (window.innerHeight || document.documentElement.clientHeight) && rect.right <= (window.innerWidth || document.documentElement.clientWidth);
+    const entry = {
+      tagName: htmlEl.tagName.toLowerCase(),
+      name: getAccessibleName(htmlEl),
+      type: htmlEl.getAttribute("type") || "",
+      value: inputEl.value || "",
+      href: htmlEl.getAttribute("href") || "",
+      selector: getSelector(htmlEl),
+      isInViewport
+    };
+    if (includeBounds) {
+      entry.boundingBox = {
+        x: rect.x + window.scrollX,
+        y: rect.y + window.scrollY,
+        width: rect.width,
+        height: rect.height
       };
-      return info;
-    });
-    return elementInfos;
-  }
-  return getElements();
+    }
+    elements.push(entry);
+  });
+  return elements;
 })();
-async function getBrowserInteractableElements(browser, options = {}) {
-  const { elementType = "interactable" } = options;
-  return browser.execute(elementsScript, elementType);
+async function getInteractableBrowserElements(browser, options = {}) {
+  const { includeBounds = false } = options;
+  return browser.execute(elementsScript, includeBounds);
 }
 
 // src/locators/constants.ts
@@ -1604,20 +1641,11 @@ import { encode } from "@toon-format/toon";
 import { z as z7 } from "zod";
 var getVisibleElementsToolDefinition = {
   name: "get_visible_elements",
-  description: 'get a list of visible (in viewport & displayed) interactable elements on the page (buttons, links, inputs). Use elementType="visual" for images/SVGs. Must prefer this to take_screenshot for interactions',
+  description: "Get interactable elements on the page (buttons, links, inputs). Use get_accessibility for page structure and non-interactable elements.",
   inputSchema: {
-    inViewportOnly: z7.boolean().optional().describe(
-      "Only return elements within the visible viewport. Default: true. Set to false to get ALL elements on the page."
-    ),
-    includeContainers: z7.boolean().optional().describe(
-      "Include layout containers (ViewGroup, FrameLayout, ScrollView, etc). Default: false. Set to true to see all elements including layouts."
-    ),
-    includeBounds: z7.boolean().optional().describe(
-      "Include element bounds/coordinates (x, y, width, height). Default: false. Set to true for coordinate-based interactions or layout debugging."
-    ),
-    elementType: z7.enum(["interactable", "visual", "all"]).optional().describe(
-      'Type of elements to return: "interactable" (default) for buttons/links/inputs, "visual" for images/SVGs, "all" for both.'
-    ),
+    inViewportOnly: z7.boolean().optional().describe("Only return elements within the visible viewport. Default: true. Set to false to get ALL elements on the page."),
+    includeContainers: z7.boolean().optional().describe("Mobile only: include layout containers. Default: false."),
+    includeBounds: z7.boolean().optional().describe("Include element bounds/coordinates (x, y, width, height). Default: false."),
     limit: z7.number().optional().describe("Maximum number of elements to return. Default: 0 (unlimited)."),
     offset: z7.number().optional().describe("Number of elements to skip (for pagination). Default: 0.")
   }
@@ -1629,7 +1657,6 @@ var getVisibleElementsTool = async (args) => {
       inViewportOnly = true,
       includeContainers = false,
       includeBounds = false,
-      elementType = "interactable",
       limit = 0,
       offset = 0
     } = args || {};
@@ -1638,7 +1665,7 @@ var getVisibleElementsTool = async (args) => {
       const platform = browser.isAndroid ? "android" : "ios";
       elements = await getMobileVisibleElements(browser, platform, { includeContainers, includeBounds });
     } else {
-      elements = await getBrowserInteractableElements(browser, { elementType });
+      elements = await getInteractableBrowserElements(browser, { includeBounds });
     }
     if (inViewportOnly) {
       elements = elements.filter((el) => el.isInViewport !== false);
@@ -1667,8 +1694,327 @@ var getVisibleElementsTool = async (args) => {
   }
 };
 
-// src/tools/take-screenshot.tool.ts
+// src/scripts/get-browser-accessibility-tree.ts
+var accessibilityTreeScript = () => (function() {
+  const INPUT_TYPE_ROLES = {
+    text: "textbox",
+    search: "searchbox",
+    email: "textbox",
+    url: "textbox",
+    tel: "textbox",
+    password: "textbox",
+    number: "spinbutton",
+    checkbox: "checkbox",
+    radio: "radio",
+    range: "slider",
+    submit: "button",
+    reset: "button",
+    image: "button",
+    file: "button",
+    color: "button"
+  };
+  const LANDMARK_ROLES = /* @__PURE__ */ new Set([
+    "navigation",
+    "main",
+    "banner",
+    "contentinfo",
+    "complementary",
+    "form",
+    "dialog",
+    "region"
+  ]);
+  const CONTAINER_ROLES = /* @__PURE__ */ new Set([
+    "navigation",
+    "banner",
+    "contentinfo",
+    "complementary",
+    "main",
+    "form",
+    "region",
+    "group",
+    "list",
+    "listitem",
+    "table",
+    "row",
+    "rowgroup",
+    "generic"
+  ]);
+  function getRole(el) {
+    const explicit = el.getAttribute("role");
+    if (explicit) return explicit.split(" ")[0];
+    const tag = el.tagName.toLowerCase();
+    switch (tag) {
+      case "button":
+        return "button";
+      case "a":
+        return el.hasAttribute("href") ? "link" : null;
+      case "input": {
+        const type = (el.getAttribute("type") || "text").toLowerCase();
+        if (type === "hidden") return null;
+        return INPUT_TYPE_ROLES[type] || "textbox";
+      }
+      case "select":
+        return "combobox";
+      case "textarea":
+        return "textbox";
+      case "h1":
+      case "h2":
+      case "h3":
+      case "h4":
+      case "h5":
+      case "h6":
+        return "heading";
+      case "img":
+        return "img";
+      case "nav":
+        return "navigation";
+      case "main":
+        return "main";
+      case "header":
+        return !el.closest("article,aside,main,nav,section") ? "banner" : null;
+      case "footer":
+        return !el.closest("article,aside,main,nav,section") ? "contentinfo" : null;
+      case "aside":
+        return "complementary";
+      case "dialog":
+        return "dialog";
+      case "form":
+        return "form";
+      case "section":
+        return el.hasAttribute("aria-label") || el.hasAttribute("aria-labelledby") ? "region" : null;
+      case "summary":
+        return "button";
+      case "details":
+        return "group";
+      case "progress":
+        return "progressbar";
+      case "meter":
+        return "meter";
+      case "ul":
+      case "ol":
+        return "list";
+      case "li":
+        return "listitem";
+      case "table":
+        return "table";
+    }
+    if (el.contentEditable === "true") return "textbox";
+    if (el.hasAttribute("tabindex") && parseInt(el.getAttribute("tabindex") || "-1", 10) >= 0) return "generic";
+    return null;
+  }
+  function getAccessibleName(el, role) {
+    const ariaLabel = el.getAttribute("aria-label");
+    if (ariaLabel) return ariaLabel.trim();
+    const labelledBy = el.getAttribute("aria-labelledby");
+    if (labelledBy) {
+      const texts = labelledBy.split(/\s+/).map((id) => document.getElementById(id)?.textContent?.trim() || "").filter(Boolean);
+      if (texts.length > 0) return texts.join(" ").slice(0, 100);
+    }
+    const tag = el.tagName.toLowerCase();
+    if (tag === "img" || tag === "input" && el.getAttribute("type") === "image") {
+      const alt = el.getAttribute("alt");
+      if (alt !== null) return alt.trim();
+    }
+    if (["input", "select", "textarea"].includes(tag)) {
+      const id = el.getAttribute("id");
+      if (id) {
+        const label = document.querySelector(`label[for="${CSS.escape(id)}"]`);
+        if (label) return label.textContent?.trim() || "";
+      }
+      const parentLabel = el.closest("label");
+      if (parentLabel) {
+        const clone = parentLabel.cloneNode(true);
+        clone.querySelectorAll("input,select,textarea").forEach((n) => n.remove());
+        const lt = clone.textContent?.trim();
+        if (lt) return lt;
+      }
+    }
+    const ph = el.getAttribute("placeholder");
+    if (ph) return ph.trim();
+    const title = el.getAttribute("title");
+    if (title) return title.trim();
+    if (role && CONTAINER_ROLES.has(role)) return "";
+    return (el.textContent?.trim().replace(/\s+/g, " ") || "").slice(0, 100);
+  }
+  function getSelector(element) {
+    const tag = element.tagName.toLowerCase();
+    const text = element.textContent?.trim().replace(/\s+/g, " ");
+    if (text && text.length > 0 && text.length <= 50) {
+      const sameTagElements = document.querySelectorAll(tag);
+      let matchCount = 0;
+      sameTagElements.forEach((el) => {
+        if (el.textContent?.includes(text)) matchCount++;
+      });
+      if (matchCount === 1) return `${tag}*=${text}`;
+    }
+    const ariaLabel = element.getAttribute("aria-label");
+    if (ariaLabel && ariaLabel.length <= 80) return `aria/${ariaLabel}`;
+    const testId = element.getAttribute("data-testid");
+    if (testId) {
+      const sel = `[data-testid="${CSS.escape(testId)}"]`;
+      if (document.querySelectorAll(sel).length === 1) return sel;
+    }
+    if (element.id) return `#${CSS.escape(element.id)}`;
+    const nameAttr = element.getAttribute("name");
+    if (nameAttr) {
+      const sel = `${tag}[name="${CSS.escape(nameAttr)}"]`;
+      if (document.querySelectorAll(sel).length === 1) return sel;
+    }
+    if (element.className && typeof element.className === "string") {
+      const classes = element.className.trim().split(/\s+/).filter(Boolean);
+      for (const cls of classes) {
+        const sel = `${tag}.${CSS.escape(cls)}`;
+        if (document.querySelectorAll(sel).length === 1) return sel;
+      }
+      if (classes.length >= 2) {
+        const sel = `${tag}${classes.slice(0, 2).map((c) => `.${CSS.escape(c)}`).join("")}`;
+        if (document.querySelectorAll(sel).length === 1) return sel;
+      }
+    }
+    let current = element;
+    const path = [];
+    while (current && current !== document.documentElement) {
+      let seg = current.tagName.toLowerCase();
+      if (current.id) {
+        path.unshift(`#${CSS.escape(current.id)}`);
+        break;
+      }
+      const parent = current.parentElement;
+      if (parent) {
+        const siblings = Array.from(parent.children).filter((c) => c.tagName === current.tagName);
+        if (siblings.length > 1) seg += `:nth-of-type(${siblings.indexOf(current) + 1})`;
+      }
+      path.unshift(seg);
+      current = current.parentElement;
+      if (path.length >= 4) break;
+    }
+    return path.join(" > ");
+  }
+  function isVisible(el) {
+    if (typeof el.checkVisibility === "function") {
+      return el.checkVisibility({ opacityProperty: true, visibilityProperty: true, contentVisibilityAuto: true });
+    }
+    const style = window.getComputedStyle(el);
+    return style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0" && el.offsetWidth > 0 && el.offsetHeight > 0;
+  }
+  function getLevel(el) {
+    const m = el.tagName.toLowerCase().match(/^h([1-6])$/);
+    if (m) return parseInt(m[1], 10);
+    const ariaLevel = el.getAttribute("aria-level");
+    if (ariaLevel) return parseInt(ariaLevel, 10);
+    return void 0;
+  }
+  function getState2(el) {
+    const inputEl = el;
+    const isCheckable = ["input", "menuitemcheckbox", "menuitemradio"].includes(el.tagName.toLowerCase()) || ["checkbox", "radio", "switch"].includes(el.getAttribute("role") || "");
+    return {
+      disabled: el.getAttribute("aria-disabled") === "true" || inputEl.disabled ? "true" : "",
+      checked: isCheckable && inputEl.checked ? "true" : el.getAttribute("aria-checked") || "",
+      expanded: el.getAttribute("aria-expanded") || "",
+      selected: el.getAttribute("aria-selected") || "",
+      pressed: el.getAttribute("aria-pressed") || "",
+      required: inputEl.required || el.getAttribute("aria-required") === "true" ? "true" : "",
+      readonly: inputEl.readOnly || el.getAttribute("aria-readonly") === "true" ? "true" : ""
+    };
+  }
+  const result = [];
+  function walk(el, depth = 0) {
+    if (depth > 200) return;
+    if (!isVisible(el)) return;
+    const role = getRole(el);
+    if (!role) {
+      for (const child of Array.from(el.children)) {
+        walk(child, depth + 1);
+      }
+      return;
+    }
+    const name = getAccessibleName(el, role);
+    const isLandmark = LANDMARK_ROLES.has(role);
+    const hasIdentity = !!(name || isLandmark);
+    const selector = hasIdentity ? getSelector(el) : "";
+    const node = { role, name, selector, level: getLevel(el) ?? "", ...getState2(el) };
+    result.push(node);
+    for (const child of Array.from(el.children)) {
+      walk(child, depth + 1);
+    }
+  }
+  for (const child of Array.from(document.body.children)) {
+    walk(child, 0);
+  }
+  return result;
+})();
+async function getBrowserAccessibilityTree(browser) {
+  return browser.execute(accessibilityTreeScript);
+}
+
+// src/tools/get-accessibility-tree.tool.ts
+import { encode as encode2 } from "@toon-format/toon";
 import { z as z8 } from "zod";
+var getAccessibilityToolDefinition = {
+  name: "get_accessibility",
+  description: "Gets the accessibility tree: page structure with headings, landmarks, and semantic roles. Browser-only. Use to understand page layout and context around interactable elements.",
+  inputSchema: {
+    limit: z8.number().optional().describe("Maximum number of nodes to return. Default: 100. Use 0 for unlimited."),
+    offset: z8.number().optional().describe("Number of nodes to skip (for pagination). Default: 0."),
+    roles: z8.array(z8.string()).optional().describe('Filter to specific roles (e.g., ["heading", "navigation", "region"]). Default: all roles.')
+  }
+};
+var getAccessibilityTreeTool = async (args) => {
+  try {
+    const browser = getBrowser();
+    if (browser.isAndroid || browser.isIOS) {
+      return {
+        content: [{
+          type: "text",
+          text: "Error: get_accessibility is browser-only. For mobile apps, use get_visible_elements instead."
+        }]
+      };
+    }
+    const { limit = 100, offset = 0, roles } = args || {};
+    let nodes = await getBrowserAccessibilityTree(browser);
+    if (nodes.length === 0) {
+      return {
+        content: [{ type: "text", text: "No accessibility tree available" }]
+      };
+    }
+    nodes = nodes.filter((n) => n.name && n.name.trim() !== "");
+    if (roles && roles.length > 0) {
+      const roleSet = new Set(roles.map((r) => r.toLowerCase()));
+      nodes = nodes.filter((n) => n.role && roleSet.has(n.role.toLowerCase()));
+    }
+    const total = nodes.length;
+    if (offset > 0) {
+      nodes = nodes.slice(offset);
+    }
+    if (limit > 0) {
+      nodes = nodes.slice(0, limit);
+    }
+    const stateKeys = ["level", "disabled", "checked", "expanded", "selected", "pressed", "required", "readonly"];
+    const usedKeys = stateKeys.filter((k) => nodes.some((n) => n[k] !== ""));
+    const trimmed = nodes.map(({ role, name, selector, ...state2 }) => {
+      const node = { role, name, selector };
+      for (const k of usedKeys) node[k] = state2[k];
+      return node;
+    });
+    const result = {
+      total,
+      showing: trimmed.length,
+      hasMore: offset + trimmed.length < total,
+      nodes: trimmed
+    };
+    const toon = encode2(result).replace(/,""/g, ",").replace(/"",/g, ",");
+    return {
+      content: [{ type: "text", text: toon }]
+    };
+  } catch (e) {
+    return {
+      content: [{ type: "text", text: `Error getting accessibility tree: ${e}` }]
+    };
+  }
+};
+
+// src/tools/take-screenshot.tool.ts
+import { z as z9 } from "zod";
 import sharp from "sharp";
 var MAX_DIMENSION = 2e3;
 var MAX_FILE_SIZE_BYTES = 1024 * 1024;
@@ -1676,7 +2022,7 @@ var takeScreenshotToolDefinition = {
   name: "take_screenshot",
   description: "captures a screenshot of the current page",
   inputSchema: {
-    outputPath: z8.string().optional().describe("Optional path where to save the screenshot. If not provided, returns base64 data.")
+    outputPath: z9.string().optional().describe("Optional path where to save the screenshot. If not provided, returns base64 data.")
   }
 };
 async function processScreenshot(screenshotBase64) {
@@ -1728,12 +2074,12 @@ var takeScreenshotTool = async ({ outputPath }) => {
 };
 
 // src/tools/cookies.tool.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var getCookiesToolDefinition = {
   name: "get_cookies",
   description: "gets all cookies or a specific cookie by name",
   inputSchema: {
-    name: z9.string().optional().describe("Optional cookie name to retrieve a specific cookie. If not provided, returns all cookies")
+    name: z10.string().optional().describe("Optional cookie name to retrieve a specific cookie. If not provided, returns all cookies")
   }
 };
 var getCookiesTool = async ({ name }) => {
@@ -1769,14 +2115,14 @@ var setCookieToolDefinition = {
   name: "set_cookie",
   description: "sets a cookie with specified name, value, and optional attributes",
   inputSchema: {
-    name: z9.string().describe("Cookie name"),
-    value: z9.string().describe("Cookie value"),
-    domain: z9.string().optional().describe("Cookie domain (defaults to current domain)"),
-    path: z9.string().optional().describe('Cookie path (defaults to "/")'),
-    expiry: z9.number().optional().describe("Expiry date as Unix timestamp in seconds"),
-    httpOnly: z9.boolean().optional().describe("HttpOnly flag"),
-    secure: z9.boolean().optional().describe("Secure flag"),
-    sameSite: z9.enum(["strict", "lax", "none"]).optional().describe("SameSite attribute")
+    name: z10.string().describe("Cookie name"),
+    value: z10.string().describe("Cookie value"),
+    domain: z10.string().optional().describe("Cookie domain (defaults to current domain)"),
+    path: z10.string().optional().describe('Cookie path (defaults to "/")'),
+    expiry: z10.number().optional().describe("Expiry date as Unix timestamp in seconds"),
+    httpOnly: z10.boolean().optional().describe("HttpOnly flag"),
+    secure: z10.boolean().optional().describe("Secure flag"),
+    sameSite: z10.enum(["strict", "lax", "none"]).optional().describe("SameSite attribute")
   }
 };
 var setCookieTool = async ({
@@ -1806,7 +2152,7 @@ var deleteCookiesToolDefinition = {
   name: "delete_cookies",
   description: "deletes all cookies or a specific cookie by name",
   inputSchema: {
-    name: z9.string().optional().describe("Optional cookie name to delete a specific cookie. If not provided, deletes all cookies")
+    name: z10.string().optional().describe("Optional cookie name to delete a specific cookie. If not provided, deletes all cookies")
   }
 };
 var deleteCookiesTool = async ({ name }) => {
@@ -1829,124 +2175,6 @@ var deleteCookiesTool = async ({ name }) => {
   }
 };
 
-// src/scripts/get-browser-accessibility-tree.ts
-function flattenAccessibilityTree(node, result = []) {
-  if (!node) return result;
-  if (node.role !== "WebArea" || node.name) {
-    const entry = {
-      role: node.role || "",
-      name: node.name || "",
-      value: node.value ?? "",
-      description: node.description || "",
-      disabled: node.disabled ? "true" : "",
-      focused: node.focused ? "true" : "",
-      selected: node.selected ? "true" : "",
-      checked: node.checked === true ? "true" : node.checked === false ? "false" : node.checked === "mixed" ? "mixed" : "",
-      expanded: node.expanded === true ? "true" : node.expanded === false ? "false" : "",
-      pressed: node.pressed === true ? "true" : node.pressed === false ? "false" : node.pressed === "mixed" ? "mixed" : "",
-      readonly: node.readonly ? "true" : "",
-      required: node.required ? "true" : "",
-      level: node.level ?? "",
-      valuemin: node.valuemin ?? "",
-      valuemax: node.valuemax ?? "",
-      autocomplete: node.autocomplete || "",
-      haspopup: node.haspopup || "",
-      invalid: node.invalid ? "true" : "",
-      modal: node.modal ? "true" : "",
-      multiline: node.multiline ? "true" : "",
-      multiselectable: node.multiselectable ? "true" : "",
-      orientation: node.orientation || "",
-      keyshortcuts: node.keyshortcuts || "",
-      roledescription: node.roledescription || "",
-      valuetext: node.valuetext || ""
-    };
-    result.push(entry);
-  }
-  if (node.children && Array.isArray(node.children)) {
-    for (const child of node.children) {
-      flattenAccessibilityTree(child, result);
-    }
-  }
-  return result;
-}
-async function getBrowserAccessibilityTree(browser) {
-  const puppeteer = await browser.getPuppeteer();
-  const pages = await puppeteer.pages();
-  if (pages.length === 0) {
-    return [];
-  }
-  const page = pages[0];
-  const snapshot = await page.accessibility.snapshot({
-    interestingOnly: true
-  });
-  if (!snapshot) {
-    return [];
-  }
-  return flattenAccessibilityTree(snapshot);
-}
-
-// src/tools/get-accessibility-tree.tool.ts
-import { encode as encode2 } from "@toon-format/toon";
-import { z as z10 } from "zod";
-var getAccessibilityToolDefinition = {
-  name: "get_accessibility",
-  description: "gets accessibility tree snapshot with semantic information about page elements (roles, names, states). Browser-only - use when get_visible_elements does not return expected elements.",
-  inputSchema: {
-    limit: z10.number().optional().describe("Maximum number of nodes to return. Default: 100. Use 0 for unlimited."),
-    offset: z10.number().optional().describe("Number of nodes to skip (for pagination). Default: 0."),
-    roles: z10.array(z10.string()).optional().describe('Filter to specific roles (e.g., ["button", "link", "textbox"]). Default: all roles.'),
-    namedOnly: z10.boolean().optional().describe("Only return nodes with a name/label. Default: true. Filters out anonymous containers.")
-  }
-};
-var getAccessibilityTreeTool = async (args) => {
-  try {
-    const browser = getBrowser();
-    if (browser.isAndroid || browser.isIOS) {
-      return {
-        content: [{
-          type: "text",
-          text: "Error: get_accessibility is browser-only. For mobile apps, use get_visible_elements instead."
-        }]
-      };
-    }
-    const { limit = 100, offset = 0, roles, namedOnly = true } = args || {};
-    let nodes = await getBrowserAccessibilityTree(browser);
-    if (nodes.length === 0) {
-      return {
-        content: [{ type: "text", text: "No accessibility tree available" }]
-      };
-    }
-    if (namedOnly) {
-      nodes = nodes.filter((n) => n.name && n.name.trim() !== "");
-    }
-    if (roles && roles.length > 0) {
-      const roleSet = new Set(roles.map((r) => r.toLowerCase()));
-      nodes = nodes.filter((n) => n.role && roleSet.has(n.role.toLowerCase()));
-    }
-    const total = nodes.length;
-    if (offset > 0) {
-      nodes = nodes.slice(offset);
-    }
-    if (limit > 0) {
-      nodes = nodes.slice(0, limit);
-    }
-    const result = {
-      total,
-      showing: nodes.length,
-      hasMore: offset + nodes.length < total,
-      nodes
-    };
-    const toon = encode2(result).replace(/,""/g, ",").replace(/"",/g, ",");
-    return {
-      content: [{ type: "text", text: toon }]
-    };
-  } catch (e) {
-    return {
-      content: [{ type: "text", text: `Error getting accessibility tree: ${e}` }]
-    };
-  }
-};
-
 // src/tools/gestures.tool.ts
 import { z as z11 } from "zod";
 var tapElementToolDefinition = {
@@ -2282,6 +2510,8 @@ var executeScriptToolDefinition = {
   name: "execute_script",
   description: `Executes JavaScript in browser or mobile commands via Appium.
 
+**Option B for browser interaction** \u2014 prefer get_visible_elements or click_element/set_value with a selector instead. Use execute_script only when no dedicated tool covers the action (e.g. reading computed values, triggering custom events, scrolling to a position).
+
 **Browser:** Runs JavaScript in page context. Use 'return' to get values back.
   - Example: execute_script({ script: "return document.title" })
   - Example: execute_script({ script: "return window.scrollY" })
@@ -2347,7 +2577,7 @@ var package_default = {
     type: "git",
     url: "git://github.com/webdriverio/mcp.git"
   },
-  version: "2.2.0",
+  version: "2.3.0",
   description: "MCP server with WebdriverIO for browser and mobile app automation (iOS/Android via Appium)",
   main: "./lib/server.js",
   module: "./lib/server.js",
@@ -2379,19 +2609,21 @@ var package_default = {
     bundle: "tsup && shx chmod +x lib/server.js",
     postbundle: "npm pack",
     lint: "eslint src/ --fix && tsc --noEmit",
+    "lint:tests": "eslint tests/ --fix && tsc -p tsconfig.test.json --noEmit",
     start: "node lib/server.js",
     dev: "tsx --watch src/server.ts",
-    prepare: "husky"
+    prepare: "husky",
+    test: "vitest run"
   },
   dependencies: {
-    "@modelcontextprotocol/sdk": "1.26",
-    xpath: "^0.0.34",
+    "@modelcontextprotocol/sdk": "1.27",
     "@toon-format/toon": "^2.1.0",
     "@wdio/protocols": "^9.16.2",
     "@xmldom/xmldom": "^0.8.11",
     "puppeteer-core": "^24.35.0",
     sharp: "^0.34.5",
-    webdriverio: "9.23",
+    webdriverio: "9.24",
+    xpath: "^0.0.34",
     zod: "^4.3.5"
   },
   devDependencies: {
@@ -2400,13 +2632,15 @@ var package_default = {
     "@wdio/eslint": "^0.1.3",
     "@wdio/types": "^9.20.0",
     eslint: "^9.39.2",
+    "happy-dom": "^20.7.0",
     husky: "^9.1.7",
     "release-it": "^19.2.3",
     rimraf: "^6.1.2",
     shx: "^0.4.0",
     tsup: "^8.5.1",
     tsx: "^4.21.0",
-    typescript: "5.9"
+    typescript: "5.9",
+    vitest: "^4.0.18"
   },
   packageManager: "pnpm@10.12.4"
 };