Release 9.37.0

.changeset/pr-191.md

@@ -0,0 +1,7 @@
+---
+"@wdio/browserstack-service": minor
+---
+
+- WebdriverIO + CucumberJS now runs on the BrowserStack CLI flow, the same path Mocha already uses. Reporting, accessibility, Percy and session naming behave as before — no config change is needed.
+- Fixed: sessions were left unmarked pass/fail when setSessionName: false was set. Naming and status are independent options again.
+- Fixed: the accessibility extension was not applied on non-BrowserStack infrastructure, leaving scans empty on otherwise green runs.

.changeset/pr-210.md

@@ -0,0 +1,8 @@
+---
+"@wdio/browserstack-service": patch
+---
+
+- Fixed Percy capture on WebdriverIO. Runs with `percy: true` logged "Unsupported driver for percy" and produced no screenshots, while the tests themselves continued to pass.
+- Fixed Percy web snapshots, which previously captured nothing on WebdriverIO.
+- Percy errors are now logged instead of failing the test. Set `PERCY_RAISE_ERROR=true` to fail the build on Percy errors instead.
+- Added Percy documentation to the README, including how to use a Percy web project alongside this service.

.changeset/pr-214.md

@@ -0,0 +1,5 @@
+---
+"@wdio/browserstack-service": patch
+---
+
+- Fixed test tags not being reported to Test Observability for Mocha and Jasmine. Tags written as `@tag` tokens in suite or test titles are now sent with each test.

packages/browserstack-service/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @wdio/browserstack-service
 
+## 9.37.0
+
+### Minor Changes
+
+- 6844406: - WebdriverIO + CucumberJS now runs on the BrowserStack CLI flow, the same path Mocha already uses. Reporting, accessibility, Percy and session naming behave as before — no config change is needed.
+  - Fixed: sessions were left unmarked pass/fail when setSessionName: false was set. Naming and status are independent options again.
+  - Fixed: the accessibility extension was not applied on non-BrowserStack infrastructure, leaving scans empty on otherwise green runs.
+
+### Patch Changes
+
+- 4bc51b5: - Fixed test tags not being reported to Test Observability for Mocha and Jasmine. Tags written as `@tag` tokens in suite or test titles are now sent with each test.
+- e9cfe6e: - Fixed Percy capture on WebdriverIO. Runs with `percy: true` logged "Unsupported driver for percy" and produced no screenshots, while the tests themselves continued to pass.
+  - Fixed Percy web snapshots, which previously captured nothing on WebdriverIO.
+  - Percy errors are now logged instead of failing the test. Set `PERCY_RAISE_ERROR=true` to fail the build on Percy errors instead.
+  - Added Percy documentation to the README, including how to use a Percy web project alongside this service.
+
 ## 9.36.2
 
 ### Patch Changes

packages/browserstack-service/README.md

@@ -224,6 +224,40 @@ Automatically set the BrowserStack Automate session status (passed/failed).
 Type: `Boolean`<br />
 Default: `true`
 
+### percy
+
+Enable Percy visual testing.
+
+Type: `Boolean`<br />
+Default: `false` — except for App Automate runs, where Percy is enabled automatically when `percy` is left unset and `app` is provided.
+
+This service runs Percy in **Percy on Automate** mode: it provisions the Percy project for you and captures screenshots server-side from the Automate session. Use `percyCaptureMode` to control when captures happen — no code changes are needed.
+
+**Percy web projects.** This service provisions a Percy on Automate project; it does not create web-type Percy projects. To use a Percy **web** project with WebdriverIO, leave `percy` unset in the service options and drive Percy yourself:
+
+```bash
+PERCY_TOKEN=<your web project token> npx percy exec -- npx wdio run wdio.conf.js
+```
+
+calling [`@percy/webdriverio`](https://github.com/percy/percy-webdriverio)'s `percySnapshot` in your specs. BrowserStack Automate and Test Observability continue to work through this service alongside it.
+
+> Pin `@percy/webdriverio` below `3.3.3` — that release omits a file its entry point requires and fails to load.
+
+### percyCaptureMode
+
+When to capture Percy screenshots automatically.
+
+Type: `String`<br />
+Default: `auto`
+
+* `auto` — capture on clicks, screenshots, actions and input changes
+* `click` — capture on clicks only
+* `screenshot` — capture on screenshot commands only
+* `testcase` — capture once at the end of each test
+* `manual` — never capture automatically
+
+Your Percy project's own capture-mode setting takes precedence over this option when one is configured.
+
 ### buildIdentifier
 
 **buildIdentifier** is a unique id to differentiate every execution that gets appended to buildName. Choose your buildIdentifier format from the available expressions:

packages/browserstack-service/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wdio/browserstack-service",
-  "version": "9.36.2",
+  "version": "9.37.0",
   "description": "WebdriverIO service for better Browserstack integration",
   "author": "BrowserStack <support@browserstack.com>",
   "homepage": "https://github.com/browserstack/wdio-browserstack-service",
@@ -58,7 +58,11 @@
     "@grpc/grpc-js": "~1.13.5",
     "@percy/appium-app": "^2.0.9",
     "@percy/selenium-webdriver": "^2.2.2",
+    "@percy/webdriverio": ">=3.3.0 <3.3.3",
     "@types/gitconfiglocal": "^2.0.1",
+    "@wdio/logger": "^9.0.0",
+    "@wdio/reporter": "^9.0.0",
+    "@wdio/types": "^9.0.0",
     "browserstack-local": "^1.5.1",
     "chalk": "^5.3.0",
     "csv-writer": "^1.6.0",
@@ -68,12 +72,9 @@
     "tar": "^7.5.11",
     "undici": "^6.24.0",
     "uuid": "^11.1.0",
+    "webdriverio": "^9.0.0",
     "winston-transport": "^4.5.0",
-    "yauzl": "^3.4.0",
-    "@wdio/logger": "^9.0.0",
-    "@wdio/reporter": "^9.0.0",
-    "@wdio/types": "^9.0.0",
-    "webdriverio": "^9.0.0"
+    "yauzl": "^3.4.0"
   },
   "peerDependencies": {
     "@wdio/cli": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0 || ^9.0.0"

packages/browserstack-service/src/Percy/PercySDK.ts

@@ -13,21 +13,56 @@ const tryRequire = function (pkg: string, fallback: unknown) {
             return (mod as { default: unknown }).default
         }
         return mod
-    } catch {
+    } catch (err) {
+        PercyLogger.debug(`Percy: could not load ${pkg} - ${(err as Error)?.message}`)
         return fallback
     }
 }
 
 const percySnapshot = tryRequire('@percy/selenium-webdriver', null)
 
+/*
+Percy ships two disjoint web SDKs, and the correct one depends on the driver, not the
+product. percySnapshot from @percy/selenium-webdriver drives the browser through Selenium
+client APIs - executeScript(script) with a single argument, By, switchTo() - none of which
+a WebdriverIO browser provides, so it captures nothing and swallows the failure. The
+WebdriverIO-native port lives in @percy/webdriverio and is what `snapshot` binds to.
+
+percyScreenshot (Percy on Automate) deliberately stays on @percy/selenium-webdriver: it is
+driver-agnostic - it reads session metadata and posts, capturing server-side - and carries
+an explicit wdio branch in its DriverMetadata.
+*/
+const percyWebdriverioSnapshot = tryRequire('@percy/webdriverio', null)
+
+const webSnapshot = percyWebdriverioSnapshot || percySnapshot
+
 const percyAppScreenshot = tryRequire('@percy/appium-app', {})
 
+/*
+Percy's SDKs raise their misuse guards - percySnapshot against a Percy-on-Automate build,
+percyScreenshot against anything else - before their own try/catch, so those rejections
+reach the caller. Every PercySDK entry point is publicly exported, so an unguarded one
+fails the user's test rather than their visual coverage. PERCY_RAISE_ERROR is Percy's own
+opt-in for the opposite behaviour and is honoured.
+*/
+const runPercy = async (label: string, call: () => unknown) => {
+    try {
+        return await call()
+    } catch (err) {
+        if (process.env.PERCY_RAISE_ERROR === 'true') {
+            throw err
+        }
+        PercyLogger.error(`Percy ${label} failed: ${(err as Error)?.message}`)
+    }
+}
+
 /* eslint-disable @typescript-eslint/no-unused-vars */
-let snapshotHandler = (...args: unknown[]) => {
+let snapshotHandler = async (...args: unknown[]): Promise<unknown> => {
     PercyLogger.error('Unsupported driver for percy')
+    return undefined
 }
-if (percySnapshot) {
-    snapshotHandler = (browser: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser, snapshotName: string, options?: { [key: string]: unknown }) => {
+if (webSnapshot) {
+    snapshotHandler = async (browser: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser, snapshotName: string, options?: { [key: string]: unknown }) => {
         if (process.env.PERCY_SNAPSHOT === 'true') {
             let { name, uuid } = InsightsHandler.currentTest
             if (isUndefined(name)) {
@@ -38,7 +73,7 @@ if (percySnapshot) {
                 ...options,
                 testCase: name || ''
             }
-            return percySnapshot(browser, snapshotName, options)
+            return await runPercy(`snapshot "${snapshotName}"`, () => webSnapshot(browser, snapshotName, options))
         }
     }
 }
@@ -75,23 +110,25 @@ const screenshotHelper = (type: string, driverOrName: WebdriverIO.Browser | Webd
 }
 
 /* eslint-disable @typescript-eslint/no-unused-vars */
-let screenshotHandler = async (...args: unknown[]) => {
+let screenshotHandler = async (...args: unknown[]): Promise<unknown> => {
     PercyLogger.error('Unsupported driver for percy')
+    return undefined
 }
 if (percySnapshot && percySnapshot.percyScreenshot) {
-    screenshotHandler = (browser: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser | string, screenshotName?: string | { [key: string]: unknown }, options?: { [key: string]: unknown }) => {
-        return screenshotHelper('web', browser, screenshotName, options)
+    screenshotHandler = async (browser: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser | string, screenshotName?: string | { [key: string]: unknown }, options?: { [key: string]: unknown }) => {
+        return await runPercy('screenshot', () => screenshotHelper('web', browser, screenshotName, options))
     }
 }
 export const screenshot = screenshotHandler
 
 /* eslint-disable @typescript-eslint/no-unused-vars */
-let screenshotAppHandler = async (...args: unknown[]) => {
+let screenshotAppHandler = async (...args: unknown[]): Promise<unknown> => {
     PercyLogger.error('Unsupported driver for percy')
+    return undefined
 }
 if (percyAppScreenshot) {
-    screenshotAppHandler = (driverOrName: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser | string, nameOrOptions?: string | { [key: string]: unknown }, options?: { [key: string]: unknown }) => {
-        return screenshotHelper('app', driverOrName, nameOrOptions, options)
+    screenshotAppHandler = async (driverOrName: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser | string, nameOrOptions?: string | { [key: string]: unknown }, options?: { [key: string]: unknown }) => {
+        return await runPercy('app screenshot', () => screenshotHelper('app', driverOrName, nameOrOptions, options))
     }
 }
 export const screenshotApp = screenshotAppHandler

packages/browserstack-service/src/cli/cliUtils.ts

@@ -47,7 +47,7 @@ const CLI_DOWNLOAD_TMP_SUFFIX = '.zip'
 export class CLIUtils {
     static automationFrameworkDetail = {}
     static testFrameworkDetail = {}
-    static CLISupportedFrameworks = ['mocha']
+    static CLISupportedFrameworks = ['mocha', 'cucumber']
 
     static isDevelopmentEnv() {
         return process.env.BROWSERSTACK_CLI_ENV === 'development'