@browserstack/mcp-server 2.3.0-beta.5 → 2.3.0-beta.7

package/capability/devicecontrol.capability-index.json

@@ -3,7 +3,7 @@
  "version": "1.0",
  "build_id": "8445466_2026-10-19T06:53:46Z",
  "devicecontrol": {
-  "summary": "Device control: drive a real desktop or mobile browser page by page. The account side lists every operating system, browser and version combination available, reports parallel-session capacity, and keeps each session's record \u2014 status, shareable link, video, and console, network and profiling logs \u2014 after the browser is released. The session side opens a browser on a chosen combination and drives it: navigate, go back and forward, reload, read the page HTML, find elements by CSS or XPath, click, type, clear, run JavaScript, screenshot the viewport, resize the window, and move between tabs and iframes. Web pages are RUN here \u2014 unlike Test Management, which authors cases, and Test Reporting, which records results pushed in from a runner. Mobile APPS are not here: those are mobile device control, which drives an installed app rather than a browser. Scrolling is done through execute_script, there is no capability that waits, and element ids go stale as soon as the page navigates or re-renders. A session holds a browser until it is ended.",
+  "summary": "Device control: drive a real desktop or mobile browser page by page. The account side lists every operating system, browser and version combination available, reports parallel-session capacity, and keeps each session's record \u2014 status, shareable link, video, and console, network and profiling logs \u2014 after the browser is released. The session side opens a browser on a chosen combination and drives it: navigate, go back and forward, reload, find elements by CSS or XPath, click, type, clear, screenshot the viewport, resize the window, and move between tabs and iframes. Web pages are RUN here \u2014 unlike Test Management, which authors cases, and Test Reporting, which records results pushed in from a runner. Mobile APPS are not here: those are mobile device control, which drives an installed app rather than a browser. Scrolling is done with scroll_to_element or scroll_page, there is no capability that waits, and element ids go stale as soon as the page navigates or re-renders. A session holds a browser until it is ended.",
   "routing_terms": [
    "automate",
    "browser",
@@ -262,7 +262,8 @@
      "The session ends itself after idle_timeout seconds without a command, and after 2 hours in total.",
      "console_logs and network_logs must be asked for here; they cannot be turned on once the session is running, and get_session only links to them when they were.",
      "Credentials belong in the Authorization header, never inside bstack:options: capabilities are echoed back in session-not-created errors.",
-     "resolution takes one of a fixed set of values per operating system, not any width and height: an unsupported pair is refused outright rather than rounded to the nearest one. The browser window is well short of the screen it sits on \u2014 1920x1080 gives a viewport around 930x860 \u2014 so measure it rather than assuming the request was honoured."
+     "resolution takes one of a fixed set of values per operating system, not any width and height: an unsupported pair is refused outright rather than rounded to the nearest one. The browser window is well short of the screen it sits on \u2014 1920x1080 gives a viewport around 930x860 \u2014 so measure it rather than assuming the request was honoured.",
+     "THIS CALL RETURNS NO LINK \u2014 only value.sessionId. Nothing here can open a browser for the user either: this surface makes HTTP requests, and on a remote server there is no browser to open. So never say a live view was opened. If the user may want to watch, call get_session straight after this and give them browser_url in the same reply, which is the session on the dashboard and needs a BrowserStack login. public_url needs no login but carries an auth token, so offer it only when they ask to share outside the team."
     ],
     "body": [
      {
@@ -499,7 +500,7 @@
     "entity": "browser_session",
     "intent": "Read the page title \u2014 the cheapest way to confirm which page is loaded.",
     "guidance": [
-     "Far cheaper than get_page_source when all that is needed is which page is showing."
+     "The cheapest way to confirm which page is showing, and enough on its own for most navigation checks."
     ],
     "path_params": [
      {
@@ -664,7 +665,8 @@
      "404": {
       "$response": "WebDriverError"
      }
-    }
+    },
+    "disabled": true
    },
    {
     "name": "find_element",
@@ -790,7 +792,7 @@
     "intent": "Click an element \u2014 use this for buttons, links, checkboxes and anything else that responds to a click.",
     "guidance": [
      "Takes no parameters of its own.",
-     "The element must be in view and not covered. A click on something another element overlaps answers \"element click intercepted\" and names the element in the way \u2014 scroll it into view with execute_script, or dismiss the overlay first.",
+     "The element must be in view and not covered. A click on something another element overlaps answers \"element click intercepted\" and names the element in the way \u2014 scroll it into view with scroll_to_element, or dismiss the overlay first.",
      "An element that is not visible answers \"element not interactable\".",
      "Success means the click was dispatched, not that the page has finished reacting: read the page or the URL afterwards to confirm."
     ],
@@ -835,7 +837,7 @@
     "guidance": [
      "APPENDS to whatever the field already holds. Call clear_element first to replace the value rather than adding to it.",
      "Read the result back with get_element_property on \"value\": a field's current contents are a property, not text.",
-     "A \\n at the end submits the form on a desktop browser and on Chrome for Android, and is quicker than finding the submit button. IT DOES NOT SUBMIT ON SAFARI FOR iOS \u2014 the text lands in the field and the page stays where it is, whether the newline is sent with the text or on its own. There, click the form's submit button, or call arguments[0].form.submit() through execute_script with the field as the argument.",
+     "A \\n at the end submits the form on a desktop browser and on Chrome for Android, and is quicker than finding the submit button. IT DOES NOT SUBMIT ON SAFARI FOR iOS \u2014 the text lands in the field and the page stays where it is, whether the newline is sent with the text or on its own. There, click the form's submit button with click_element \u2014 scroll_to_element first if it sits below the fold.",
      "The element must be editable; typing into anything else answers \"element not interactable\".",
      "A site's own autocomplete or dropdown may swallow the keystrokes and require a click on a suggestion instead."
     ],
@@ -962,8 +964,7 @@
      "404": {
       "$response": "WebDriverError"
      }
-    },
-    "disabled": true
+    }
    },
    {
     "name": "get_element_property",
@@ -1061,8 +1062,7 @@
      "404": {
       "$response": "WebDriverError"
      }
-    },
-    "disabled": true
+    }
    },
    {
     "name": "is_element_displayed",
@@ -1103,8 +1103,120 @@
      "404": {
       "$response": "WebDriverError"
      }
-    },
-    "disabled": true
+    }
+   },
+   {
+    "name": "scroll_to_element",
+    "method": "POST",
+    "path": "/wd/hub/session/{session_id}/execute/sync",
+    "mode": "write",
+    "entity": "browser_session",
+    "intent": "Bring an element into view \u2014 use this before clicking or screenshotting something below the fold, since both fail or miss when the target is off screen.",
+    "guidance": [
+     "THE RELIABLE FORM ON EVERY PLATFORM. Prefer this to scrolling the page by a distance: it works out where the element is for you, and it does not depend on the page reporting its height correctly, which scroll_page does.",
+     "The element_id goes in args as {\"element-6066-11e4-a52e-4f735466cecf\": \"<id>\"} and arrives in the script as arguments[0]; find_element gives you the id.",
+     "Returns the element's position after scrolling, so a caller can confirm it really is in view rather than trusting the status.",
+     "A click on a covered element answers \"element click intercepted\" \u2014 scroll it into view with this first."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     }
+    ],
+    "body": [
+     {
+      "name": "script",
+      "type": "string",
+      "required": true,
+      "example": "arguments[0].scrollIntoView({block:'center'}); var r=arguments[0].getBoundingClientRect(); return {top:r.top,bottom:r.bottom,innerHeight:window.innerHeight};",
+      "values": [
+       "arguments[0].scrollIntoView({block:'center'}); var r=arguments[0].getBoundingClientRect(); return {top:r.top,bottom:r.bottom,innerHeight:window.innerHeight};"
+      ]
+     },
+     {
+      "name": "args",
+      "type": "array",
+      "required": true,
+      "description": "Exactly one object holding the element reference.",
+      "example": [
+       {
+        "element-6066-11e4-a52e-4f735466cecf": "<element_id>"
+       }
+      ]
+     }
+    ],
+    "returns": [
+     "value"
+    ],
+    "responses": {
+     "200": {
+      "description": "Whatever the script returned.",
+      "schema": {
+       "$schema": "AnyValueResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     }
+    }
+   },
+   {
+    "name": "scroll_page",
+    "method": "POST",
+    "path": "/wd/hub/session/{session_id}/execute/sync",
+    "mode": "write",
+    "entity": "browser_session",
+    "intent": "Scroll the page itself by a distance or to the bottom \u2014 use this when there is no element to aim at, such as reaching a footer or loading more of an infinite list.",
+    "guidance": [
+     "PREFER scroll_to_element when you have an element: it works out where the target is for you. Use this form only when there is nothing to aim at.",
+     "Choose what it does with args: \"bottom\", \"top\", or a pixel count.",
+     "Returns the scroll position and the page height, so a caller can tell whether it actually reached the end: at rest at the bottom, scrollY + innerHeight equals scrollHeight within a couple of pixels \u2014 a scaled phone screen reports fractional positions, so do not demand exact equality. ON SAFARI THE POSITION IN THE \"bottom\" CALL'S OWN RESPONSE IS WHERE IT WAS ASKED TO GO, NOT WHERE IT STOPPED \u2014 it comes back equal to scrollHeight, which no resting position can be. Call again with args 0 to read the real position; that second reading is the one to check."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     }
+    ],
+    "body": [
+     {
+      "name": "script",
+      "type": "string",
+      "required": true,
+      "example": "var a=arguments[0]; var h=Math.max(document.body.scrollHeight,document.documentElement.scrollHeight); if(a==='bottom'){window.scrollTo(0,h);} else if(a==='top'){window.scrollTo(0,0);} else {window.scrollBy(0,Number(a));} return {scrollY:window.scrollY, innerHeight:window.innerHeight, scrollHeight:Math.max(document.body.scrollHeight,document.documentElement.scrollHeight)};",
+      "values": [
+       "var a=arguments[0]; var h=Math.max(document.body.scrollHeight,document.documentElement.scrollHeight); if(a==='bottom'){window.scrollTo(0,h);} else if(a==='top'){window.scrollTo(0,0);} else {window.scrollBy(0,Number(a));} return {scrollY:window.scrollY, innerHeight:window.innerHeight, scrollHeight:Math.max(document.body.scrollHeight,document.documentElement.scrollHeight)};"
+      ]
+     },
+     {
+      "name": "args",
+      "type": "array",
+      "required": true,
+      "description": "Exactly one value: \"bottom\", \"top\", or a number of pixels to scroll by (negative scrolls up).",
+      "example": [
+       "bottom"
+      ]
+     }
+    ],
+    "returns": [
+     "value"
+    ],
+    "responses": {
+     "200": {
+      "description": "Whatever the script returned.",
+      "schema": {
+       "$schema": "AnyValueResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     }
+    }
    },
    {
     "name": "execute_script",
@@ -1114,7 +1226,8 @@
     "entity": "browser_session",
     "intent": "Run JavaScript in the page \u2014 use this to scroll, read something the element readers cannot reach, or drive a control that resists clicking.",
     "guidance": [
-     "SCROLLING LIVES HERE: window.scrollTo(0, document.body.scrollHeight) goes to the bottom, and arguments[0].scrollIntoView({block:'center'}) brings an element into view before clicking it.",
+     "SCROLLING LIVES HERE, and the reliable form is the ELEMENT one: pass the element in args and call arguments[0].scrollIntoView({block:'center'}). window.scrollTo(0, document.body.scrollHeight) reaches the bottom on a desktop browser, but on Chrome for Android it can stop short and leave a footer off screen while still reporting success \u2014 so scroll the thing you actually want rather than the page, and confirm with a screenshot or the page source.",
+     "READING THE PAGE'S MARKUP LIVES HERE TOO: 'return document.documentElement.outerHTML' for the whole document, or 'return arguments[0].outerHTML' with an element in args for one part of it. Prefer the element form \u2014 a real page runs to tens of kilobytes and the whole document is rarely what is wanted. This is also how to discover a selector on a page you have not seen: read the markup around the area you care about rather than guessing a selector, which fails silently when it matches nothing.",
      "`return` is required to get a value back; without it the answer is null.",
      "An element id can be passed in args as {\"element-6066-11e4-a52e-4f735466cecf\": \"<id>\"} and arrives as a real element in arguments.",
      "It runs with the page's own privileges and can change anything, so a script that alters state is as consequential as a click.",
@@ -1157,7 +1270,8 @@
      "404": {
       "$response": "WebDriverError"
      }
-    }
+    },
+    "disabled": true
    },
    {
     "name": "take_screenshot",
@@ -1168,7 +1282,7 @@
     "intent": "Take a screenshot of the browser's viewport, as a base64 PNG \u2014 use this to see the page as a user would.",
     "guidance": [
      "Returned inline as base64 and typically tens of kilobytes, so take one when the picture is needed rather than after every step.",
-     "The VIEWPORT only, not the whole page: anything below the fold needs scrolling into view first with execute_script.",
+     "The VIEWPORT only, not the whole page: anything below the fold needs scrolling into view first with scroll_to_element.",
      "get_title and get_element_property answer most checks far more cheaply than reading an image."
     ],
     "path_params": [
@@ -1563,13 +1677,14 @@
      }
     ],
     "returns": [
+     "state",
      "value"
     ],
     "responses": {
      "200": {
-      "description": "Null on success.",
+      "description": "state is \"success\" and value an empty string; the body is the hub's own, not the W3C null.",
       "schema": {
-       "$schema": "NullValueResponse"
+       "$schema": "SessionDeletedResponse"
       }
      },
      "404": {
@@ -1955,6 +2070,24 @@
       }
      }
     }
+   },
+   "SessionDeletedResponse": {
+    "type": "object",
+    "description": "What the hub returns when a session is closed. Not the W3C null: state says whether it closed and value is an empty string.",
+    "properties": {
+     "state": {
+      "type": "string",
+      "description": "\"success\" when the session was closed."
+     },
+     "status": {
+      "type": "integer",
+      "description": "The hub's own legacy status code; 0 on success."
+     },
+     "value": {
+      "type": "string",
+      "description": "Always empty on success."
+     }
+    }
    }
   },
   "responses": {
@@ -2024,7 +2157,9 @@
      "open_new_window",
      "switch_to_frame",
      "get_cookies",
-     "delete_session"
+     "delete_session",
+     "scroll_to_element",
+     "scroll_page"
     ]
    },
    "browser": {