fix(percy): restore Percy capture on WebdriverIO (v8) (SDK-7756)

.changeset/pr-231.md

@@ -0,0 +1,5 @@
+---
+"@wdio/browserstack-service": patch
+---
+
+- Fixed Percy visual testing on WebdriverIO: screenshots (Percy on Automate) and web snapshots are captured again. No config or code changes needed.

packages/browserstack-service/README.md

@@ -249,6 +249,38 @@ 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.
+
+### 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

@@ -50,7 +50,8 @@
     "@bufbuild/protobuf": "^2.5.2",
     "@grpc/grpc-js": "1.13.3",
     "@percy/appium-app": "^2.0.1",
-    "@percy/selenium-webdriver": "^2.0.3",
+    "@percy/selenium-webdriver": "^2.2.8",
+    "@percy/webdriverio": "^3.3.4",
     "@types/gitconfiglocal": "^2.0.1",
     "browserstack-local": "^1.5.1",
     "chalk": "^5.3.0",

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

@@ -2,25 +2,67 @@ import InsightsHandler from '../insights-handler.js'
 import TestReporter from '../reporter.js'
 import { PercyLogger } from './PercyLogger.js'
 import { isUndefined } from '../util.js'
+import { createRequire } from 'node:module'
 
-const tryRequire = async function (pkg: string, fallback: any) {
+const require = createRequire(import.meta.url)
+
+const tryRequire = function (pkg: string, fallback: unknown) {
     try {
-        return (await import(pkg)).default
-    } catch {
+        const mod = require(pkg)
+        if (mod && typeof mod === 'object' && 'default' in mod) {
+            return (mod as { default: unknown }).default
+        }
+        return mod
+    } catch (err) {
+        PercyLogger.debug(`Percy: could not load ${pkg} - ${(err as Error)?.message}`)
         return fallback
     }
 }
 
-const percySnapshot = await tryRequire('@percy/selenium-webdriver', null)
+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 = await tryRequire('@percy/appium-app', {})
+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: any[]) => {
+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]: any }) => {
+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)) {
@@ -31,7 +73,7 @@ if (percySnapshot) {
                 ...options,
                 testCase: name || ''
             }
-            return percySnapshot(browser, snapshotName, options)
+            return await runPercy(`snapshot "${snapshotName}"`, () => webSnapshot(browser, snapshotName, options))
         }
     }
 }
@@ -41,7 +83,7 @@ export const snapshot = snapshotHandler
 This is a helper method which appends some internal fields
 to the options object being sent to Percy methods
 */
-const screenshotHelper = (type: string, driverOrName: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser | string, nameOrOptions?: string | { [key: string]: any }, options?: { [key: string]: any }) => {
+const screenshotHelper = (type: string, driverOrName: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser | string, nameOrOptions?: string | { [key: string]: unknown }, options?: { [key: string]: unknown }) => {
     let { name, uuid } = InsightsHandler.currentTest
     if (isUndefined(name)) {
         ({ name, uuid } = TestReporter.currentTest)
@@ -68,23 +110,25 @@ const screenshotHelper = (type: string, driverOrName: WebdriverIO.Browser | Webd
 }
 
 /* eslint-disable @typescript-eslint/no-unused-vars */
-let screenshotHandler = async (...args: any[]) => {
+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]: any }, options?: { [key: string]: any }) => {
-        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: any[]) => {
+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]: any }, options?: { [key: string]: any }) => {
-        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
+export const screenshotApp = screenshotAppHandler