@surea11y/webdriverio 1.4.1 → 1.4.2

package/README.md

@@ -5,12 +5,12 @@ A WebdriverIO binding for [`@surea11y/core`](https://github.com/SureA11y/core)
 ## Install
 
 ```bash
-npm install @surea11y/webdriverio webdriverio
+npm install @surea11y/core @surea11y/webdriverio webdriverio
 ```
 
-`@surea11y/core` 1.12.0 or later, the engine, comes with it as a regular dependency, so the line above is all you need, whatever your package manager.
+`@surea11y/core` 1.12.0 or later, the engine, comes with the binding as a regular dependency, so a project that doesn't list it still works. List it in your own `package.json` too, as the line above does: your project and the binding then share one copy, so whatever you do with core directly, writing a SARIF log or an HTML report (`@surea11y/core/sarif`, `/report`), reading the rule catalogue or keeping a baseline, reads results with the same core that produced them. When your core can't match the binding's range, as with a linked checkout (`file:../core`) or a fork, add `"overrides": { "@surea11y/core": "$@surea11y/core" }` beside it.
 
-If your project uses core directly too, to write a SARIF log or an HTML report (`@surea11y/core/sarif`, `/report`), read the rule catalogue, or keep a baseline, keep one copy of it, so those read results with the same core that produced them. A compatible range in your own `package.json` (`"@surea11y/core": "^1.12.0"`) is enough: npm installs core once. When yours can't match the binding's range, as with a linked checkout (`file:../core`) or a fork, add `"overrides": { "@surea11y/core": "$@surea11y/core" }` beside it, and the binding uses your copy, which needs to be 1.12.0 or later. 1.4.0 made core a peer dependency instead; 1.4.1 undoes that, because Yarn, npm 6 and npm with `legacy-peer-deps` don't install peers, and a project with an older core pinned couldn't install the binding at all.
+**Coming in 2.0:** core becomes a peer dependency, so the binding will no longer install it for you, and the `overrides` entry is no longer needed. Add `@surea11y/core` to your `package.json` now and 2.0 needs no change.
 
 `webdriverio` v9 auto-manages a local `chromedriver` for you the first time it launches Chrome (no separate Selenium server, and no extra browser-download step needed) — so a fresh `npm install` is enough for `npm test` to launch a real headless Chrome on its own.
 
@@ -99,7 +99,7 @@ Rule IDs change rarely, but core 1.10.0 changed two: `label-title-only` is depre
 
 `.exclude(selector)` above excludes globally. Pass a second argument to scope it to specific rule IDs instead: `.exclude('.mat-select', { rules: ['aria-required-children'] })` skips `.mat-select` for that rule only — every other rule still sees it. Global and rule-scoped `.exclude()` calls compose freely.
 
-**Create one builder per scan.** `A11yCoreBuilder` is a mutable object with no reset between `.analyze()` calls — `include()`/`exclude()`/`withRules()`/`disableRules()`/`withTags()`/`disableTags()`/`options()`/`withCustomRules()`/`withPacks()` all push onto or merge into internal state that persists for the instance's lifetime. Calling one of them again before a second `.analyze()` call *accumulates* on top of the first scan's scope rather than replacing it (this is exactly what makes "call `.include()` several times for one scan," above, work — the same accumulation just also applies across separate scans if you reuse an instance). `.reportOnly()`/`.frames()`/`.elementRef()`/`.withWcag()`/`.withBestPractices()`/`.includeMode()`/`.wcagLevel()`/`.logger()` are the exception: each call replaces the previous value instead of merging with it.
+**Create one builder per scan.** `A11yCoreBuilder` is a mutable object with no reset between `.analyze()` calls — `include()`/`exclude()`/`withRules()`/`disableRules()`/`withTags()`/`disableTags()`/`options()`/`withCustomRules()`/`withPacks()` all push onto or merge into internal state that persists for the instance's lifetime. Calling one of them again before a second `.analyze()` call *accumulates* on top of the first scan's scope rather than replacing it (this is exactly what makes "call `.include()` several times for one scan," above, work — the same accumulation just also applies across separate scans if you reuse an instance). `.reportOnly()`/`.frames()`/`.elementRef()`/`.screenshots()`/`.withWcag()`/`.withBestPractices()`/`.includeMode()`/`.wcagLevel()`/`.logger()` are the exception: each call replaces the previous value instead of merging with it.
 
 This binding works against any browser WebdriverIO can drive; the tests and examples use headless Chrome via `chromedriver`, which WebdriverIO manages automatically.
 
@@ -216,6 +216,37 @@ Two WebdriverIO-specific differences from the sibling bindings' `.elementRef(tru
 
 Not every occurrence has one target element — a page-wide finding (some `manual`/`cantTell` rules) can carry `selector: ""`, in which case `occurrence.element` is `null` rather than an element.
 
+### A picture of each failing element
+
+Opt in with `.screenshots()`, and each occurrence the scan flags gets a `screenshot` field: a picture of the element, with a box drawn around it, or the reason there is none.
+
+```js
+const results = await new A11yCoreBuilder({ browser })
+  .screenshots({ dir: 'a11y-shots', padding: 16 })
+  .analyze();
+
+const [first] = results.checksResults.filter((r) => r.outcome === 'fail');
+first.occurrences[0].screenshot;
+// { path: 'a11y-shots/element-3f9a1c07.png', box: { x: 20, y: 20, width: 120, height: 40 } }
+```
+
+| Option | Default | |
+|---|---|---|
+| `dir` | none | Write each picture there. Without it, each comes back as `{ buffer, box }`, a PNG for you to store your own way. |
+| `outcomes` | `['fail']` | Which occurrences to picture. For contrast, `['fail', 'cantTell']` shows the background the engine couldn't judge. |
+| `padding` | `0` | CSS pixels of context around the element. |
+| `highlight` | `true` | Draw a box around the element, over the page; the element itself is never restyled. |
+| `max` | `50` | At most this many pictures per scan, frames included. |
+
+- **One picture per element.** Several rules can flag the same element; it's pictured once, and each of their occurrences carries the same `screenshot`. A file is named after where the element is, so it keeps its name from run to run, and `formatFailures()` names it under each finding (`   screenshot: a11y-shots/element-3f9a1c07.png`).
+- **`box`** is where the element shows in the picture, in CSS pixels; the PNG is larger by the device pixel ratio. `cropped: true` says only part of it shows, as for an element taller than the viewport, which is pictured from its top-left corner.
+- **No picture, and why**: `{ skipped }` with `'no-element'` (no selector, or nothing matches it any more), `'page-level'` (a finding about the whole page, on `<html>`, `<head>` or `<body>`), `'not-rendered'` (such as `display: none`), `'zero-size'`, `'off-screen'` (such as `left: -9999px`), `'max-reached'`, or `'capture-failed'` with the reason. A failed picture never fails the scan.
+- **The page is put back.** Each element is scrolled into view for its picture, and afterwards every scroll position is restored and the box removed, also when a picture fails. Something drawn over the element, such as a sticky header, shows as it does on screen.
+- **Frames.** With `.frames(true)`, an element in an `<iframe>`, cross-origin ones included, is pictured on the page as it shows there, and the browser ends at the top-level page as before. Without it, the scan runs in whatever frame the browser is switched into; pictures are placed from the top-level page, so a scan started inside a frame gives its occurrences `capture-failed` and says why. Scan from the top-level page with `.frames(true)` to picture a frame's elements.
+- **Off by default.** Pictures of real pages can hold personal data, and they end up as CI artifacts.
+
+The pictures are cut out of WebDriver's screenshot of the viewport (`browser.takeScreenshot()`), right after each frame's scan, before `.reportOnly()` trims the result, and combine with `.elementRef(true)`. Focus, hover, animations or content that loads late can still differ from what the scan saw. An option it can't use throws a `TypeError` with `code: 'INVALID_ENGINE_OPTIONS'` at the call, and so does `.analyze()` with `options({ output: { includeSelector: false } })`, since each element is found by its selector. Works over WebDriver classic and BiDi.
+
 ### Web components: the internals hook
 
 Many web components keep their `ElementInternals` in a private field and name themselves, set their states or give themselves a role through it:
@@ -368,6 +399,14 @@ results.engine.profile; // 'en301549-v4.1.1'
 
 A pack brings rules, variants of core's rules, a standard or a checklist, and their profiles and messages, from a package of its own: a national standard such as RGAA, or your organisation's accessibility policy. `@surea11y/core` runs a pack as it runs its own rules and standards, so its results, rollups and report entries look like core's. Packs need `@surea11y/core` 1.11.1 or later.
 
+Install a published pack in your project, beside core and this package:
+
+```bash
+npm install @surea11y/core @surea11y/webdriverio webdriverio @acme/a11y-policy
+```
+
+Your project, this package and the pack then share one copy of core, so the core that checks the pack is the one that runs it. With two copies, a scan can skip the pack (see "When a pack doesn't run" below).
+
 `.withPacks()` registers packs in the page with `browser.execute()`, and in every frame with `.frames(true)`, before the scan; a pack's profile is chosen with `.options({ profile })`:
 
 ```js
@@ -389,7 +428,7 @@ A pack's own rules appear in `checksResults` like core's, with ids that start wi
 
 **Writing a pack.** A pack is an object made with `definePack` from `@surea11y/core/pack`. [`examples/acme-policy-pack.js`](./examples/acme-policy-pack.js) is a small one: a house rule, a checklist profile (WCAG 2.2 A and AA, `region`, and the house rule) and two checklist items. `npm run example:pack` scans a page with it, and [`examples/e2e-test-example.test.js`](./examples/e2e-test-example.test.js) uses it as a test gate. For a pack of your own, `npx surea11y-pack new <folder>` (from `@surea11y/core`) writes a package that works as generated, with its tests, docs and lint; core's [`PACKS.md`](https://github.com/SureA11y/core/blob/main/docs/PACKS.md) is the guide.
 
-**When a pack doesn't run.** `.withPacks()` builds the page's script with the `@surea11y/core` this binding loads, and checks each pack as it does: `.analyze()` throws before scanning for a pack that core can't run, such as one whose `core` range leaves out the installed core, or whose profile names a rule that doesn't exist. A pack the page then doesn't run (one named with a raw `.options({ packs })` and never registered, or a page running another core version, when two copies of core are installed) is listed in `results.skippedPacks` with the reason. `getScanGaps()` reports that as `'pack-skipped'`, and `.analyze()` warns about it, so a test gate that asserts on `getScanGaps(results)` fails rather than passing with the pack's checks never run. Install the pack beside the binding, so npm resolves one core for both.
+**When a pack doesn't run.** `.withPacks()` builds the page's script with the `@surea11y/core` this binding loads, and checks each pack as it does: `.analyze()` throws before scanning for a pack that core can't run, such as one whose `core` range leaves out the installed core, or whose profile names a rule that doesn't exist. A pack the page then doesn't run (one named with a raw `.options({ packs })` and never registered, or a page running another core version, when two copies of core are installed) is listed in `results.skippedPacks` with the reason. `getScanGaps()` reports that as `'pack-skipped'`, and `.analyze()` warns about it, so a test gate that asserts on `getScanGaps(results)` fails rather than passing with the pack's checks never run.
 
 ### Element addressing beyond a CSS selector
 
@@ -399,7 +438,7 @@ An element inside a shadow tree is different: its `selector` holds only inside i
 
 ## TypeScript
 
-`src/A11yCoreBuilder.d.ts` (re-exported from `src/index.d.ts`, wired up via `package.json`'s `types` field) ships types for the whole builder API plus `@surea11y/core`'s native result shapes (`A11yCoreResult`, `CheckResult`, `Occurrence`, `CompositeResult`, etc.). The result shapes are built on the types `@surea11y/core` ships itself, so fields such as `engine.version`, `engine.environment`, `contextMatch`, `skippedCustomRules`, `margin` and `shadowHostSelectors` follow the engine; this package adds `occurrence.element` and the `.frames(true)` shape. `EngineError`, `EngineErrorCode`, `ScanGap` and `ScanNote` come from `@surea11y/binding-base`, and so do the types of `withWcag()` and `wcagLevel()` (`WcagVersion`, `WcagLevelInput`), `plannedChecks()`/`plannedCriteria()` (`PlannedCheck`, `PlannedCriterion`), and `withPacks()`, which takes a pack made with `definePack` (`PackLike`). The static `installInternalsHook()` and `getScanNotes()` are typed too. Code that handles every `ScanGap` kind it knows and treats the rest in an `else` branch needs a branch for `'pack-skipped'`, which carries `pack` rather than `selectors`. `analyze()` is typed `Promise<A11yCoreResult | A11yCoreMultiFrameResult>` — narrow on `'topFrame' in results` (or cast, if you already know which mode you called) to get the specific shape back, since a fluent builder can't statically track that `.frames(true)` was called earlier in the chain. `occurrence.element` is typed `WebdriverIO.Element | null`. `webdriverio` is a `peerDependencies` entry (not just `devDependencies`) since the class's `browser` argument and `Occurrence#element` both come from its global `WebdriverIO` type namespace — consumers need their own `webdriverio` install for the types to resolve, same as they already do to construct a `browser` in the first place.
+`src/A11yCoreBuilder.d.ts` (re-exported from `src/index.d.ts`, wired up via `package.json`'s `types` field) ships types for the whole builder API plus `@surea11y/core`'s native result shapes (`A11yCoreResult`, `CheckResult`, `Occurrence`, `CompositeResult`, etc.). The result shapes are built on the types `@surea11y/core` ships itself, so fields such as `engine.version`, `engine.environment`, `contextMatch`, `skippedCustomRules`, `margin` and `shadowHostSelectors` follow the engine; this package adds `occurrence.element` and the `.frames(true)` shape. `EngineError`, `EngineErrorCode`, `ScanGap` and `ScanNote` come from `@surea11y/binding-base`, and so do the types of `withWcag()` and `wcagLevel()` (`WcagVersion`, `WcagLevelInput`), `plannedChecks()`/`plannedCriteria()` (`PlannedCheck`, `PlannedCriterion`), `withPacks()`, which takes a pack made with `definePack` (`PackLike`), and `.screenshots()` (`ScreenshotOptions`, and `OccurrenceScreenshot` for an occurrence's `screenshot`). The static `installInternalsHook()` and `getScanNotes()` are typed too. Code that handles every `ScanGap` kind it knows and treats the rest in an `else` branch needs a branch for `'pack-skipped'`, which carries `pack` rather than `selectors`. `analyze()` is typed `Promise<A11yCoreResult | A11yCoreMultiFrameResult>` — narrow on `'topFrame' in results` (or cast, if you already know which mode you called) to get the specific shape back, since a fluent builder can't statically track that `.frames(true)` was called earlier in the chain. `occurrence.element` is typed `WebdriverIO.Element | null`. `webdriverio` is a `peerDependencies` entry (not just `devDependencies`) since the class's `browser` argument and `Occurrence#element` both come from its global `WebdriverIO` type namespace — consumers need their own `webdriverio` install for the types to resolve, same as they already do to construct a `browser` in the first place.
 
 ## What changes with `@surea11y/core` 1.12
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surea11y/webdriverio",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "Accessibility (a11y, WCAG) checks for WebdriverIO tests: scan the live page with new A11yCoreBuilder({ browser }).analyze() and get only proven violations, with findings that need human review listed separately.",
   "keywords": [
     "accessibility",
@@ -47,7 +47,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@surea11y/binding-base": "^1.4.0",
+    "@surea11y/binding-base": "^1.5.0",
     "@surea11y/core": "^1.12.0"
   },
   "peerDependencies": {

package/src/A11yCoreBuilder.d.ts

@@ -10,8 +10,8 @@ import type {} from 'webdriverio';
 // { topFrame, frames } shape of .frames(true). The names below are the ones
 // this file has always exported.
 import type * as Core from '@surea11y/core';
-import type { PackLike, WcagVersion, WcagLevelInput, ScanGap, ScanNote, PlannedCheck, PlannedCriterion } from '@surea11y/binding-base';
-export type { PackLike, WcagVersion, WcagLevel } from '@surea11y/binding-base';
+import type { PackLike, WcagVersion, WcagLevelInput, ScanGap, ScanNote, PlannedCheck, PlannedCriterion, ScreenshotOptions, OccurrenceScreenshot } from '@surea11y/binding-base';
+export type { PackLike, WcagVersion, WcagLevel, ScreenshotOptions, ScreenshotSkip, ScreenshotBox, OccurrenceScreenshot } from '@surea11y/binding-base';
 
 export type Outcome = Core.Outcome;
 export type OutcomeNormalized = Core.OutcomeNormalized;
@@ -53,6 +53,12 @@ export interface Occurrence extends Core.Occurrence {
    * switched into that frame.
    */
   element?: WebdriverIO.Element | null;
+  /**
+   * Only present when `.screenshots()` was used and this occurrence's own
+   * outcome is one it pictures: the picture, or why there is none. The
+   * occurrences about the same element share one object.
+   */
+  screenshot?: OccurrenceScreenshot;
 }
 
 export interface CheckResult extends Omit<Core.CheckResult, 'occurrences'> {
@@ -190,6 +196,13 @@ export class A11yCoreBuilder {
   frames(enabled?: boolean): this;
   /** Opt in to resolving each fail/cantTell occurrence's selector to a live WebdriverIO.Element. */
   elementRef(enabled?: boolean): this;
+  /**
+   * Opt in to a picture of each element the scan flags, on its occurrences'
+   * `screenshot` field: a Buffer, or a file in `dir`. `false` turns them
+   * off. Throws a TypeError with code 'INVALID_ENGINE_OPTIONS' for an option
+   * it can't use.
+   */
+  screenshots(options?: ScreenshotOptions | boolean): this;
   /** The rules this scan will run, worked out in Node with no page (@surea11y/core 1.12.0 and later). */
   plannedChecks(): PlannedCheck[];
   /** The criteria this scan will report in rulesResults, worked out in Node with no page. */

package/src/A11yCoreBuilder.js

@@ -5,7 +5,9 @@ const {
   A11yCoreBuilderBase,
   createInPageScan,
   rethrowEngineError,
-  queryOccurrenceElement
+  queryOccurrenceElement,
+  planScreenshots,
+  cropViewportScreenshot
 } = require('@surea11y/binding-base');
 
 // core's runa11yCoreInPage, wrapped so an engine error (INVALID_RUN_ONLY,
@@ -112,6 +114,19 @@ const inPageScan = createInPageScan(runa11yCoreInPage);
  * than `.evaluate(el => el.id)`, `.saveScreenshot(path)` rather than
  * `.screenshot({ path })`). See the README.
  *
+ * Or let the scan take a picture of each element it flags, with
+ * `.screenshots()` (@surea11y/binding-base's, see its README): each
+ * occurrence gets a `screenshot` field, the picture (a Buffer, or a file in
+ * `dir`) or why there is none. The element is scrolled into view and marked
+ * with a box drawn over the page, and the page is put back afterwards; in
+ * every frame with `.frames(true)`, including cross-origin ones:
+ *
+ * const results = await new A11yCoreBuilder({ browser })
+ *   .screenshots({ dir: 'a11y-shots', padding: 16 })
+ *   .analyze();
+ * // results.checksResults[i].occurrences[j].screenshot
+ * //   -> { path: 'a11y-shots/element-3f9a1c07.png', box: { x, y, width, height } }
+ *
  * Register your own rule(s) for just this scan with
  * `.withCustomRules([...])` (@surea11y/core's `engineOptions.customRules`
  * escape hatch -- see ../core/docs/ENGINE_OPTIONS.md). Pass a real,
@@ -141,8 +156,9 @@ const inPageScan = createInPageScan(runa11yCoreInPage);
  * top of the first scan's scope rather than replacing it (intentional for
  * "call include() several times for one scan" -- see above -- but a footgun
  * if you hold one instance across multiple assertions).
- * reportOnly()/frames()/elementRef()/withWcag()/withBestPractices() are the
- * exception: each call replaces the previous value rather than merging with it.
+ * reportOnly()/frames()/elementRef()/screenshots()/withWcag()/withBestPractices()
+ * are the exception: each call replaces the previous value rather than
+ * merging with it.
  */
 class A11yCoreBuilder extends A11yCoreBuilderBase {
   /**
@@ -236,28 +252,38 @@ class A11yCoreBuilder extends A11yCoreBuilderBase {
     // scan names in engineOptions.packs; null without packs. execute() runs
     // a string as a function body, so the script runs as written.
     const packScript = this._packScript();
-    const scanCurrent = async (scope) => {
+    // `path` is the frame being scanned, as _scanChildFrames addresses it
+    // ([] for the top-level page); the screenshots step needs it to reach
+    // the frame again, and its parents.
+    const scanCurrent = async (scope, path) => {
       const frameUrl = this._url || (await this._browser.execute(() => document.location.href));
       if (packScript) await this._browser.execute(packScript);
       const result = rethrowEngineError(
         await this._browser.execute(inPageScan, frameUrl, scope, engineOptions, runOnly)
       );
       this._warnScanGaps(result, '@surea11y/webdriverio');
-      return this._elementRef ? this._attachElementRefs(result) : result;
+      // Element references first: they are resolved in the current frame,
+      // which the screenshots step switches away from.
+      if (this._elementRef) await this._attachElementRefs(result);
+      if (this._screenshots) await this._screenshotFrame(result, path);
+      return result;
     };
 
     if (!this._scanFrames) {
-      return this._applyReportOnly(await scanCurrent(contextSelector));
+      // Whatever frame the caller left the browser in; the screenshots step
+      // can place pictures only from the top-level page (see
+      // _screenshotFrame), and null says so.
+      return this._applyReportOnly(await scanCurrent(contextSelector, null));
     }
 
     // The top frame is scanned first, so an INVALID_RUN_ONLY or
     // INVALID_CONTEXT_SELECTOR error is thrown from it, before any sub-frame.
-    const topFrame = this._applyReportOnly(await scanCurrent(contextSelector));
+    const topFrame = this._applyReportOnly(await scanCurrent(contextSelector, []));
 
     // Sub-frames are scanned whole: the include() scope belongs to the top
     // frame's document (see the class comment).
     const frames = [];
-    await this._scanChildFrames([], () => scanCurrent(null), frames);
+    await this._scanChildFrames([], (childPath) => scanCurrent(null, childPath), frames);
 
     // Leave the browser back at the top-level frame regardless of how the
     // traversal ended, so a caller's next command isn't silently running in
@@ -315,7 +341,7 @@ class A11yCoreBuilder extends A11yCoreBuilderBase {
       }
 
       try {
-        out.push(this._applyReportOnly(await scanCurrent()));
+        out.push(this._applyReportOnly(await scanCurrent(path.concat(i))));
       } catch (e) {
         out.push({ url: frameUrl, error: (e && e.message) || String(e) });
       }
@@ -339,6 +365,58 @@ class A11yCoreBuilder extends A11yCoreBuilderBase {
     }
   }
 
+  /**
+   * binding-base's screenshots step for the frame at `path` (child <iframe>
+   * indices from the top, as _scanChildFrames walks them), with the
+   * <iframe>s leading to it given by index among `$$('iframe')`, the way
+   * this binding counts frames: element references don't survive switching
+   * away and back under BiDi. The step switches between frames as it goes,
+   * so the browser is switched back into the scanned frame afterwards, where
+   * the traversal goes on.
+   *
+   * `path` is null for a scan without .frames(true), which runs in whatever
+   * frame the caller left the browser in. From the top-level page that is
+   * `[]`; from inside a frame, nothing says how it sits on the page, so its
+   * occurrences get `capture-failed` rather than misplaced pictures.
+   */
+  async _screenshotFrame(result, path) {
+    if (path === null) {
+      const atTop = await this._browser.execute(() => window === window.top).catch(() => false);
+      if (!atTop) {
+        const error = 'the browser was switched into a frame when analyze() ran; pictures are placed from the top-level page, so scan from there, with .frames(true) to include the frame';
+        const { elements, unlocated } = planScreenshots(result, { outcomes: this._screenshots.outcomes });
+        for (const element of elements) {
+          const shot = { skipped: 'capture-failed', error };
+          for (const occurrence of element.occurrences) occurrence.screenshot = shot;
+        }
+        for (const occurrence of unlocated) occurrence.screenshot = { skipped: 'no-element' };
+        return;
+      }
+      path = [];
+    }
+    const framePath = path.map((index, depth) => ({ frame: path.slice(0, depth), iframe: { selector: 'iframe', index } }));
+    try {
+      await this._captureScreenshots(result, path, framePath);
+    } finally {
+      await this._switchToPath(path).catch(() => {});
+    }
+  }
+
+  /** For binding-base's screenshots step: runs `fn(...args)` in the frame at `path`. */
+  async _evaluateInFrame(path, fn, args) {
+    await this._switchToPath(path);
+    return this._browser.execute(fn, ...args);
+  }
+
+  /**
+   * For binding-base's screenshots step: a PNG of `box`, CSS pixels in the
+   * top-level viewport, cut out of WebDriver's screenshot of that viewport,
+   * which it takes whatever frame the browser is switched into.
+   */
+  async _captureBox(box, view) {
+    return cropViewportScreenshot(await this._browser.takeScreenshot(), box, view);
+  }
+
   /**
    * Resolves each occurrence to a live WebdriverIO.Element, scoped to
    * whatever frame the browser is currently switched into (execute() is