feat: support WebdriverIO 10 and keep WebdriverIO 9 support

.changeset/wdio-v10-support.md

@@ -0,0 +1,15 @@
+---
+"@wdio/browserstack-service": minor
+---
+
+Support WebdriverIO 10. WebdriverIO 9 stays supported.
+
+- The `@wdio/cli` peer range is now `^9.0.0 || ^10.0.0`. It allowed WebdriverIO 5 to 8, but the service needs WebdriverIO 9 or 10. WebdriverIO 7 and 8 users use the `v7` and `v8` release lines of the service.
+- Multiremote sessions use `isMultiRemote` (v10) or `isMultiremote` (v9), and get each instance with `getInstance()`.
+- Accessibility command wrapping passes `{ attachToElement: true }` to `overwriteCommand`, which works in v9 and v10.
+- The CLI accessibility scripts run through `execute()`, because v10 removed `executeAsync()`.
+- The BiDi `browserstack_executor` routing patches `executeAsync` only when the command exists (v9).
+- On WebdriverIO 10 with Mocha, the tests that a failed `before` or `beforeEach` hook skipped are reported as failed with the hook error, as WebdriverIO 10 reports them. With `mochaOpts.failHookAffectedTests: false`, they stay skipped.
+- On WebdriverIO 10, `execute` on a browsing context (from `browser.url()` or `browser.newWindow()`) also sends `browserstack_executor` scripts through the classic endpoint, and the accessibility auto-scan also runs before the browser commands of a browsing context, on that context.
+- The CLI accessibility command wrapper no longer runs a failed command a second time. The error (for example a WebdriverIO 10 `StrictSelectorError`) goes to the test, and the service does not log it as its own error.
+- On WebdriverIO 10, App Automate sessions that do not set an Appium version get `bstack:options.appiumVersion: '3.3.0'` (`browserstack.appium_version` for capabilities in the legacy format). App Automate uses Appium 1.22.0 by default, and WebdriverIO 10 supports Appium 3 only.

.github/scripts/check-wdio-major.mjs

@@ -0,0 +1,27 @@
+// Confirms that a CI job tests the WebdriverIO major version that it claims to test.
+//
+// The service supports WebdriverIO 9 and 10, and ci.yml runs the tests once for each major.
+// `npm ci` installs the WebdriverIO 10 dev dependencies from the lockfile. The WebdriverIO 9 job then
+// replaces them with `npm install --no-save ...@^9`. If that install keeps a v10 copy, or leaves a
+// mix of v9 and v10 packages, the job still passes, but it tests the wrong version. This script
+// fails the job in that case, so a green WebdriverIO 9 job means that the tests pass on WebdriverIO 9.
+//
+// It reads the `npm ls` output of the service, prints each installed version, and fails when a
+// package is not on <major>, or when `npm ls` did not list exactly <count> packages (for example,
+// a package is missing from the tree).
+//
+// Usage: npm ls -w @wdio/browserstack-service <packages> --depth=0 --json | node check-wdio-major.mjs <major> <count>
+import { readFileSync } from 'node:fs'
+
+const [major, count] = process.argv.slice(2)
+const tree = JSON.parse(readFileSync(0, 'utf8'))
+const deps = tree.dependencies['@wdio/browserstack-service'].dependencies ?? {}
+
+for (const [name, { version }] of Object.entries(deps)) {
+    console.log(`${name}@${version}`)
+}
+const wrong = Object.values(deps).filter(({ version }) => !version?.startsWith(`${major}.`))
+if (wrong.length > 0 || Object.keys(deps).length !== Number(count)) {
+    console.error(`Expected ${count} packages on WebdriverIO ${major}`)
+    process.exit(1)
+}

.github/workflows/ci.yml

@@ -31,12 +31,15 @@ jobs:
         run: npm run lint
 
   build-test:
-    name: Build & test (node ${{ matrix.node-version }})
+    name: Build & test (wdio ${{ matrix.wdio }}, node ${{ matrix.node-version }})
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        node-version: ['18.20', '20', '22']
+        include:
+          - { wdio: 10, node-version: '24' }
+          # WebdriverIO 9 compatibility: the service supports both majors
+          - { wdio: 9, node-version: '22' }
     steps:
       - name: Checkout
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -50,8 +53,24 @@ jobs:
       - name: Install
         run: npm ci
 
+      # The published build uses the WebdriverIO 10 types. Every job builds before it installs another
+      # WebdriverIO major, because the build also generates the gRPC client that the tests import.
       - name: Build
         run: npm run build
 
+      - name: Install WebdriverIO ${{ matrix.wdio }}
+        if: matrix.wdio != 10
+        run: >-
+          npm install --no-save -w @wdio/browserstack-service
+          webdriverio@^${{ matrix.wdio }} @wdio/cli@^${{ matrix.wdio }} @wdio/globals@^${{ matrix.wdio }}
+          @wdio/logger@^${{ matrix.wdio }} @wdio/reporter@^${{ matrix.wdio }} @wdio/types@^${{ matrix.wdio }}
+
+      - name: Check WebdriverIO version
+        run: >-
+          npm ls -w @wdio/browserstack-service webdriverio @wdio/types @wdio/reporter @wdio/logger --depth=0 --json
+          | node .github/scripts/check-wdio-major.mjs ${{ matrix.wdio }} 4
+
       - name: Test
+        env:
+          WDIO_MAJOR: ${{ matrix.wdio }}
         run: npm test