Merge pull request #46 from webdriverio/feature/browserstack-provider

feat: Introduce BrowserStack provider and tools

Author: Winify

.gitignore

@@ -6,3 +6,6 @@ lib
 
 settings.local.json
 *.tgz
+
+.mcp.json
+.env

CLAUDE.md

@@ -15,65 +15,22 @@ npm start         # Run built server from lib/server.js
 
 ```
 src/
-├── server.ts                    # MCP server entry, registers all tools + MCP resources
-├── session/
-│   ├── state.ts                 # Session state maps, getBrowser(), getState(), SessionMetadata
-│   └── lifecycle.ts             # registerSession(), handleSessionTransition(), closeSession()
-├── providers/
-│   ├── types.ts                 # SessionProvider interface, ConnectionConfig
-│   ├── local-browser.provider.ts  # Chrome/Firefox/Edge/Safari capability building
-│   └── local-appium.provider.ts   # iOS/Android via appium.config.ts
-├── tools/
-│   ├── session.tool.ts          # start_session (browser+mobile), close_session
-│   ├── tabs.tool.ts             # switch_tab
-│   ├── launch-chrome.tool.ts    # launch_chrome (remote debugging)
-│   ├── navigate.tool.ts         # navigateAction() + navigateTool
-│   ├── click.tool.ts            # clickAction() + clickTool
-│   ├── set-value.tool.ts        # setValueAction() + setValueTool
-│   ├── scroll.tool.ts           # scrollAction() + scrollTool
-│   ├── gestures.tool.ts         # tapAction(), swipeAction(), dragAndDropAction()
-│   ├── context.tool.ts          # switch_context (native/webview)
-│   ├── device.tool.ts           # rotate_device, hide_keyboard
-│   ├── emulate-device.tool.ts   # emulate_device (viewport/UA)
-│   ├── cookies.tool.ts          # set_cookie, delete_cookies
-│   ├── execute-script.tool.ts   # execute_script
-│   ├── get-elements.tool.ts     # get_elements (all elements, incl. below fold)
-│   └── ...                      # Other tools follow same pattern
-├── resources/
-│   ├── index.ts                 # ResourceDefinition exports
-│   ├── sessions.resource.ts     # wdio://sessions, wdio://session/*/steps, wdio://session/*/code
-│   ├── elements.resource.ts     # wdio://session/current/elements
-│   ├── accessibility.resource.ts# wdio://session/current/accessibility
-│   ├── screenshot.resource.ts   # wdio://session/current/screenshot
-│   ├── cookies.resource.ts      # wdio://session/current/cookies
-│   ├── tabs.resource.ts         # wdio://session/current/tabs
-│   ├── contexts.resource.ts     # wdio://session/current/contexts
-│   ├── app-state.resource.ts    # wdio://session/current/app-state
-│   └── geolocation.resource.ts  # wdio://session/current/geolocation
-├── recording/
-│   ├── step-recorder.ts         # withRecording HOF, appendStep, session history access
-│   └── code-generator.ts        # SessionHistory → WebdriverIO JS code
-├── scripts/
-│   ├── get-interactable-browser-elements.ts  # Browser-context element detection
-│   ├── get-browser-accessibility-tree.ts     # Browser-context accessibility tree
-│   ├── get-visible-mobile-elements.ts        # Mobile visible element detection
-│   └── get-elements.ts                       # Filter + paginate elements (used by tool + resource)
-├── locators/
-│   ├── element-filter.ts        # Platform-specific element classification
-│   ├── locator-generation.ts    # Multi-strategy selector generation
-│   ├── xml-parsing.ts           # XML page source parsing for mobile
-│   ├── constants.ts             # Shared locator constants
-│   ├── types.ts                 # Locator type definitions
-│   └── index.ts                 # Public exports
-├── config/
-│   └── appium.config.ts         # iOS/Android capability builders (used by local-appium.provider)
-├── utils/
-│   ├── parse-variables.ts       # URI template variable parsing (parseBool, parseNumber, etc.)
-│   └── zod-helpers.ts           # coerceBoolean and other Zod utilities
-└── types/
-    ├── tool.ts                  # ToolDefinition interface
-    ├── resource.ts              # ResourceDefinition interface
-    └── recording.ts             # RecordedStep, SessionHistory interfaces
+├── server.ts          # MCP server entry — registers all tools + resources
+├── session/           # Session state (state.ts) + lifecycle (lifecycle.ts)
+├── providers/         # SessionProvider implementations
+│   ├── registry.ts    # getProvider() — routes to local or cloud provider
+│   ├── local-browser.provider.ts  # Chrome/Firefox/Edge/Safari
+│   ├── local-appium.provider.ts   # iOS/Android via Appium
+│   └── cloud/
+│       └── browserstack.provider.ts  # BrowserStack (browser + App Automate)
+├── tools/             # One file per MCP tool (see Tool Pattern below)
+├── resources/         # One file per MCP resource (see Recording below)
+├── recording/         # step-recorder.ts (withRecording HOF) + code-generator.ts
+├── scripts/           # Browser/mobile scripts executed via browser.execute() — no try/catch, raw data only
+├── locators/          # Element detection, selector generation, XML parsing (mobile)
+├── config/            # appium.config.ts — iOS/Android capability builders
+├── utils/             # parse-variables.ts, zod-helpers.ts (coerceBoolean)
+└── types/             # ToolDefinition, ResourceDefinition, RecordedStep interfaces
 ```
 
 ### Session State
@@ -157,12 +114,12 @@ MCP resources expose live session data — all at fixed URIs discoverable via Li
 | `src/server.ts`                                    | MCP server init, tool + resource registration |
 | `src/session/state.ts`                             | Session state maps, `getBrowser()`, `getState()` |
 | `src/session/lifecycle.ts`                         | `registerSession()`, `closeSession()`, session transitions |
+| `src/providers/registry.ts`                        | `getProvider()` — routes to local or cloud provider |
+| `src/providers/cloud/browserstack.provider.ts`     | BrowserStack session provider                 |
 | `src/tools/session.tool.ts`                        | `start_session` (browser + mobile), `close_session` |
-| `src/tools/tabs.tool.ts`                           | `switch_tab`                                  |
 | `src/tools/get-elements.tool.ts`                   | `get_elements` — all elements with filtering + pagination |
-| `src/resources/`                                   | All MCP resource definitions (10 files)       |
-| `src/providers/local-browser.provider.ts`          | Chrome/Firefox/Edge/Safari capability building |
-| `src/providers/local-appium.provider.ts`           | iOS/Android capabilities via appium.config.ts |
+| `src/tools/browserstack.tool.ts`                   | `list_apps`, `upload_app` — BrowserStack App Automate |
+| `src/resources/`                                   | All MCP resource definitions (12 files)       |
 | `src/scripts/get-interactable-browser-elements.ts` | Browser-context element detection             |
 | `src/locators/`                                    | Mobile element detection + locator generation |
 | `src/recording/step-recorder.ts`                   | `withRecording(toolName, cb)` HOF — wraps tools for step logging |
@@ -234,9 +191,17 @@ catch (e) {
 - iOS Predicate: `-ios predicate string:label == "Login"`
 - XPath: `//XCUIElementTypeButton[@label="Login"]`
 
+## Environment
+
+| Variable | Required for |
+|----------|-------------|
+| `BROWSERSTACK_USERNAME` | BrowserStack sessions + tools |
+| `BROWSERSTACK_ACCESS_KEY` | BrowserStack sessions + tools |
+
 ## Planned Improvements
 
 See `docs/architecture/` for proposals:
 
-- `session-configuration-proposal.md` — Cloud provider pattern (BrowserStack, SauceLabs) — providers/types.ts is the extension point
-- `multi-session-proposal.md` — Parallel sessions for sub-agent coordination
+- `session-configuration-proposal.md` — Cloud provider pattern (SauceLabs etc.) — BrowserStack already implemented; `providers/registry.ts` + `providers/cloud/` is the extension point
+- `multi-session-proposal.md` — Parallel sessions for sub-agent coordination
+- `interaction-sequencing-proposal.md` — Sequencing model for tool interactions

README.md

@@ -216,6 +216,117 @@ appium
 # Server runs at http://127.0.0.1:4723 by default
 ```
 
+## BrowserStack
+
+Run browser and mobile app tests on [BrowserStack](https://www.browserstack.com/) real devices and browsers without any local setup.
+
+### Prerequisites
+
+Set your credentials as environment variables:
+
+```bash
+export BROWSERSTACK_USERNAME=your_username
+export BROWSERSTACK_ACCESS_KEY=your_access_key
+```
+
+Or add them to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "wdio-mcp": {
+      "command": "npx",
+      "args": ["-y", "@wdio/mcp@latest"],
+      "env": {
+        "BROWSERSTACK_USERNAME": "your_username",
+        "BROWSERSTACK_ACCESS_KEY": "your_access_key"
+      }
+    }
+  }
+}
+```
+
+### Browser Sessions
+
+Run a browser on a specific OS/version combination:
+
+```javascript
+start_session({
+  provider: 'browserstack',
+  platform: 'browser',
+  browser: 'chrome',           // chrome | firefox | edge | safari
+  browserVersion: 'latest',    // default: latest
+  os: 'Windows',               // e.g. "Windows", "OS X"
+  osVersion: '11',             // e.g. "11", "Sequoia"
+  reporting: {
+    project: 'My Project',
+    build: 'v1.2.0',
+    session: 'Login flow'
+  }
+})
+```
+
+### Mobile App Sessions
+
+Test on BrowserStack real devices. First upload your app (or use an existing `bs://` URL):
+
+```javascript
+// Upload a local .apk or .ipa (returns a bs:// URL)
+upload_app({ path: '/path/to/app.apk' })
+
+// Start a session with the returned URL
+start_session({
+  provider: 'browserstack',
+  platform: 'android',         // android | ios
+  app: 'bs://abc123...',       // bs:// URL or custom_id from upload
+  deviceName: 'Samsung Galaxy S23',
+  platformVersion: '13.0',
+  reporting: {
+    project: 'My Project',
+    build: 'v1.2.0',
+    session: 'Checkout flow'
+  }
+})
+```
+
+Use `list_apps` to see previously uploaded apps:
+
+```javascript
+list_apps()                               // own uploads, sorted by date
+list_apps({ sortBy: 'app_name' })
+list_apps({ organizationWide: true })     // all uploads in your org
+```
+
+### BrowserStack Local
+
+To test against URLs that are only accessible on your local machine or internal network, enable the BrowserStack Local tunnel:
+
+```javascript
+start_session({
+  provider: 'browserstack',
+  platform: 'browser',
+  browser: 'chrome',
+  browserstackLocal: true      // starts tunnel automatically
+})
+```
+
+### Reporting Labels
+
+All session types support `reporting` labels that appear in the BrowserStack Automate dashboard:
+
+| Field                     | Description                                |
+|---------------------------|--------------------------------------------|
+| `reporting.project`       | Group sessions under a project name        |
+| `reporting.build`         | Tag sessions with a build/version label    |
+| `reporting.session`       | Name for the individual test session       |
+
+### BrowserStack Tools
+
+| Tool          | Description                                                                      |
+|---------------|----------------------------------------------------------------------------------|
+| `upload_app`  | Upload a local `.apk` or `.ipa` to BrowserStack; returns a `bs://` URL          |
+| `list_apps`   | List apps previously uploaded to your BrowserStack account                       |
+
 ## Features
 
 ### Browser Automation

package.json

@@ -37,40 +37,38 @@
     "prebundle": "rimraf lib --glob ./*.tgz",
     "bundle": "tsup && shx chmod +x lib/server.js",
     "postbundle": "npm pack",
-    "lint": "npm run lint:src && npm run lint:tests",
-    "lint:src": "eslint src/ --fix && tsc --noEmit",
-    "lint:tests": "eslint tests/ --fix && tsc -p tsconfig.test.json --noEmit",
+    "lint": "eslint src/ tests/ --fix && tsc --noEmit",
     "start": "node lib/server.js",
     "dev": "tsx --watch src/server.ts",
     "prepare": "husky",
     "test": "vitest run"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.27",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "@toon-format/toon": "^2.1.0",
-    "@wdio/protocols": "^9.16.2",
-    "@xmldom/xmldom": "^0.8.11",
-    "puppeteer-core": "^24.35.0",
+    "@wdio/protocols": "^9.27.0",
+    "@xmldom/xmldom": "^0.8.12",
+    "puppeteer-core": "^24.40.0",
     "sharp": "^0.34.5",
-    "webdriverio": "9.24",
+    "webdriverio": "^9.27.0",
     "xpath": "^0.0.34",
-    "zod": "^4.3.5"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@release-it/conventional-changelog": "^10.0.4",
-    "@types/node": "^20.11.0",
+    "@release-it/conventional-changelog": "^10.0.6",
+    "@types/node": "^20.19.37",
     "@wdio/eslint": "^0.1.3",
-    "@wdio/types": "^9.20.0",
-    "eslint": "^9.39.2",
-    "happy-dom": "^20.7.0",
+    "@wdio/types": "^9.27.0",
+    "eslint": "^9.39.4",
+    "happy-dom": "^20.8.9",
     "husky": "^9.1.7",
-    "release-it": "^19.2.3",
-    "rimraf": "^6.1.2",
+    "release-it": "^19.2.4",
+    "rimraf": "^6.1.3",
     "shx": "^0.4.0",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
-    "typescript": "5.9",
-    "vitest": "^4.0.18"
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.2"
   },
   "packageManager": "[email protected]"
 }