feat(helpers): add grabFromClipboard, share clipboard scripts

Promotes the private clipboard read to a public `grabFromClipboard()`
action on every browser helper, and moves the in-page clipboard scripts
that were duplicated across four helpers into
`lib/helper/extras/clipboard.js`.

The shared scripts are promise-based and self-contained, so each helper
consumes them the way its engine expects: Playwright and Puppeteer pass
the function to `page.evaluate`, CDPBrowser interpolates it into a
`Runtime.evaluate` expression, and WebDriver wraps it in a W3C async
script body rather than keeping a second callback-style copy.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: DavertMik

docs/webapi/grabFromClipboard.mustache

@@ -0,0 +1,12 @@
+Grabs the text content of the system clipboard and returns it to test.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+
+```js
+I.click('Copy to clipboard');
+let url = await I.grabFromClipboard();
+```
+
+Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+in Chromium-based browsers, where read access is granted automatically.
+
+@returns {Promise<string>} the system clipboard contents.

lib/helper/Appium.js

@@ -1544,8 +1544,13 @@ class Appium extends Webdriver {
     return this.browser.setClipboard('', 'plaintext')
   }
 
-  async _grabClipboard() {
-    if (typeof this.browser.getClipboard !== 'function') return super._grabClipboard()
+  /**
+   * {{> grabFromClipboard }}
+   *
+   * Appium: support both Android and iOS
+   */
+  async grabFromClipboard() {
+    if (typeof this.browser.getClipboard !== 'function') return super.grabFromClipboard()
     const encoded = await this.browser.getClipboard('plaintext')
     const clipboard = Buffer.from(encoded || '', 'base64').toString('utf8')
     this.debugSection('Clipboard', clipboard)

lib/helper/CDPBrowser.js

@@ -18,6 +18,7 @@ import { isColorProperty, convertColorToRGBA } from '../colorUtils.js'
 import WebElement from '../element/WebElement.js'
 import CDPElementHandle from './extras/CDPElementHandle.js'
 import { checkFocusBeforeType, checkFocusBeforePressKey } from './extras/focusCheck.js'
+import { CLIPBOARD_READ_TIMEOUT_MS, readClipboardScript, writeClipboardScript, clipboardExpression } from './extras/clipboard.js'
 import { dontSeeTraffic, seeTraffic, grabRecordedNetworkTraffics, flushNetworkTraffics } from './network/actions.js'
 import { assembleApng, isPng } from './extras/apngAssembler.js'
 
@@ -73,8 +74,6 @@ const PAGE_LOAD_GRACE_MS = 300
 // (common) non-navigating case, not a guess at how long a real navigation takes.
 const ACTION_SETTLE_GRACE_MS = 20
 
-const CLIPBOARD_READ_TIMEOUT_MS = 5000
-
 /**
  * CDPBrowser drives a browser directly over the raw Chrome DevTools Protocol, without depending
  * on Puppeteer, Playwright, or WebDriver. It opens its own WebSocket connection (via `CDPConnection`),
@@ -1956,7 +1955,7 @@ class CDPBrowser extends Helper {
    * @returns {Promise<void>}
    */
   async seeInClipboard(text) {
-    const clipboard = await this._grabClipboard()
+    const clipboard = await this.grabFromClipboard()
     return stringIncludes('clipboard').assert(text, clipboard)
   }
 
@@ -1974,7 +1973,7 @@ class CDPBrowser extends Helper {
    * @returns {Promise<void>}
    */
   async seeClipboardEquals(text) {
-    const clipboard = await this._grabClipboard()
+    const clipboard = await this.grabFromClipboard()
     return equals('clipboard').assert(clipboard, text)
   }
 
@@ -1990,18 +1989,23 @@ class CDPBrowser extends Helper {
    */
   async clearClipboard() {
     await this._grantClipboardAccess()
-    await this._evaluate(`(${writeClipboardScript.toString()})('')`)
+    await this._evaluate(clipboardExpression(writeClipboardScript, ''))
   }
 
   /**
-   * Reads the system clipboard through `navigator.clipboard`, granting read access first.
+   * Grabs the text content of the system clipboard.
+   * Resumes test execution, so **should be used inside async function with `await`** operator.
    *
-   * @returns {Promise<string>} the current clipboard contents.
-   * @protected
+   * ```js
+   * I.click('Copy to clipboard');
+   * const url = await I.grabFromClipboard();
+   * ```
+   *
+   * @returns {Promise<string>} the system clipboard contents.
    */
-  async _grabClipboard() {
+  async grabFromClipboard() {
     await this._grantClipboardAccess()
-    const clipboard = await this._evaluate(`(${readClipboardScript.toString()})(${CLIPBOARD_READ_TIMEOUT_MS})`)
+    const clipboard = await this._evaluate(clipboardExpression(readClipboardScript, CLIPBOARD_READ_TIMEOUT_MS))
     this.debugSection('Clipboard', clipboard)
     return clipboard
   }
@@ -3083,18 +3087,4 @@ class CDPBrowser extends Helper {
   }
 }
 
-function readClipboardScript(timeout) {
-  if (!navigator.clipboard || !navigator.clipboard.readText) {
-    throw new Error('Clipboard API is not available on this page, it requires a secure context (https or localhost)')
-  }
-  return Promise.race([navigator.clipboard.readText(), new Promise((resolve, reject) => setTimeout(() => reject(new Error('timed out while reading the clipboard')), timeout))])
-}
-
-function writeClipboardScript(text) {
-  if (!navigator.clipboard || !navigator.clipboard.writeText) {
-    throw new Error('Clipboard API is not available on this page, it requires a secure context (https or localhost)')
-  }
-  return navigator.clipboard.writeText(text)
-}
-
 export default CDPBrowser

lib/helper/Playwright.js

@@ -8,6 +8,7 @@ import Locator from '../locator.js'
 import recorder from '../recorder.js'
 import store from '../store.js'
 import { checkFocusBeforeType, checkFocusBeforePressKey } from './extras/focusCheck.js'
+import { CLIPBOARD_READ_TIMEOUT_MS, readClipboardScript, writeClipboardScript } from './extras/clipboard.js'
 import { includes as stringIncludes } from '../assert/include.js'
 import { urlEquals, equals } from '../assert/equal.js'
 import { empty } from '../assert/empty.js'
@@ -2663,31 +2664,34 @@ class Playwright extends Helper {
    * {{> seeInClipboard }}
    */
   async seeInClipboard(text) {
-    const clipboard = await this._grabClipboard()
+    const clipboard = await this.grabFromClipboard()
     stringIncludes('clipboard').assert(text, clipboard)
   }
 
   /**
    * {{> seeClipboardEquals }}
    */
   async seeClipboardEquals(text) {
-    const clipboard = await this._grabClipboard()
+    const clipboard = await this.grabFromClipboard()
     return equals('clipboard').assert(clipboard, text)
   }
 
   /**
-   * {{> clearClipboard }}
+   * {{> grabFromClipboard }}
    */
-  async clearClipboard() {
+  async grabFromClipboard() {
     await this._grantClipboardAccess()
-    return this.page.evaluate(writeClipboardScript, '')
+    const clipboard = await this.page.evaluate(readClipboardScript, CLIPBOARD_READ_TIMEOUT_MS)
+    this.debugSection('Clipboard', clipboard)
+    return clipboard
   }
 
-  async _grabClipboard() {
+  /**
+   * {{> clearClipboard }}
+   */
+  async clearClipboard() {
     await this._grantClipboardAccess()
-    const clipboard = await this.page.evaluate(readClipboardScript, CLIPBOARD_TIMEOUT)
-    this.debugSection('Clipboard', clipboard)
-    return clipboard
+    return this.page.evaluate(writeClipboardScript, '')
   }
 
   async _grantClipboardAccess() {
@@ -4942,19 +4946,3 @@ async function elToString(el, numberOfElements) {
       .trim() + '...'
   )
 }
-
-const CLIPBOARD_TIMEOUT = 5000
-
-function readClipboardScript(timeout) {
-  if (!navigator.clipboard || !navigator.clipboard.readText) {
-    throw new Error('Clipboard API is not available on this page, it requires a secure context (https or localhost)')
-  }
-  return Promise.race([navigator.clipboard.readText(), new Promise((resolve, reject) => setTimeout(() => reject(new Error('timed out while reading the clipboard')), timeout))])
-}
-
-function writeClipboardScript(text) {
-  if (!navigator.clipboard || !navigator.clipboard.writeText) {
-    throw new Error('Clipboard API is not available on this page, it requires a secure context (https or localhost)')
-  }
-  return navigator.clipboard.writeText(text)
-}

lib/helper/Puppeteer.js

@@ -9,6 +9,7 @@ import Locator from '../locator.js'
 import recorder from '../recorder.js'
 import store from '../store.js'
 import { checkFocusBeforeType, checkFocusBeforePressKey } from './extras/focusCheck.js'
+import { CLIPBOARD_READ_TIMEOUT_MS, readClipboardScript, writeClipboardScript } from './extras/clipboard.js'
 import { includes as stringIncludes } from '../assert/include.js'
 import { urlEquals, equals } from '../assert/equal.js'
 import { empty } from '../assert/empty.js'
@@ -1964,31 +1965,34 @@ class Puppeteer extends Helper {
    * {{> seeInClipboard }}
    */
   async seeInClipboard(text) {
-    const clipboard = await this._grabClipboard()
+    const clipboard = await this.grabFromClipboard()
     stringIncludes('clipboard').assert(text, clipboard)
   }
 
   /**
    * {{> seeClipboardEquals }}
    */
   async seeClipboardEquals(text) {
-    const clipboard = await this._grabClipboard()
+    const clipboard = await this.grabFromClipboard()
     return equals('clipboard').assert(clipboard, text)
   }
 
   /**
-   * {{> clearClipboard }}
+   * {{> grabFromClipboard }}
    */
-  async clearClipboard() {
+  async grabFromClipboard() {
     await this._grantClipboardAccess()
-    return this.page.evaluate(writeClipboardScript, '')
+    const clipboard = await this.page.evaluate(readClipboardScript, CLIPBOARD_READ_TIMEOUT_MS)
+    this.debugSection('Clipboard', clipboard)
+    return clipboard
   }
 
-  async _grabClipboard() {
+  /**
+   * {{> clearClipboard }}
+   */
+  async clearClipboard() {
     await this._grantClipboardAccess()
-    const clipboard = await this.page.evaluate(readClipboardScript, CLIPBOARD_TIMEOUT)
-    this.debugSection('Clipboard', clipboard)
-    return clipboard
+    return this.page.evaluate(writeClipboardScript, '')
   }
 
   async _grantClipboardAccess() {
@@ -3755,19 +3759,3 @@ async function proceedSelect(context, el, option) {
 
   return this._waitForAction()
 }
-
-const CLIPBOARD_TIMEOUT = 5000
-
-function readClipboardScript(timeout) {
-  if (!navigator.clipboard || !navigator.clipboard.readText) {
-    throw new Error('Clipboard API is not available on this page, it requires a secure context (https or localhost)')
-  }
-  return Promise.race([navigator.clipboard.readText(), new Promise((resolve, reject) => setTimeout(() => reject(new Error('timed out while reading the clipboard')), timeout))])
-}
-
-function writeClipboardScript(text) {
-  if (!navigator.clipboard || !navigator.clipboard.writeText) {
-    throw new Error('Clipboard API is not available on this page, it requires a secure context (https or localhost)')
-  }
-  return navigator.clipboard.writeText(text)
-}

lib/helper/WebDriver.js

@@ -11,6 +11,7 @@ import { includes as stringIncludes } from '../assert/include.js'
 import { urlEquals, equals } from '../assert/equal.js'
 import store from '../store.js'
 import { checkFocusBeforeType, checkFocusBeforePressKey } from './extras/focusCheck.js'
+import { CLIPBOARD_READ_TIMEOUT_MS, readClipboardScript, writeClipboardScript, clipboardAsyncScript } from './extras/clipboard.js'
 import output from '../output.js'
 const { debug } = output
 import { empty } from '../assert/empty.js'
@@ -2095,35 +2096,38 @@ class WebDriver extends Helper {
    * {{> seeInClipboard }}
    */
   async seeInClipboard(text) {
-    const clipboard = await this._grabClipboard()
+    const clipboard = await this.grabFromClipboard()
     return stringIncludes('clipboard').assert(text, clipboard)
   }
 
   /**
    * {{> seeClipboardEquals }}
    */
   async seeClipboardEquals(text) {
-    const clipboard = await this._grabClipboard()
+    const clipboard = await this.grabFromClipboard()
     return equals('clipboard').assert(clipboard, text)
   }
 
   /**
-   * {{> clearClipboard }}
+   * {{> grabFromClipboard }}
    */
-  async clearClipboard() {
-    await this._grantClipboardAccess()
-    const result = (await this.browser.executeAsync(writeClipboardScript, '')) || {}
-    if (result.error) throw new Error(`Could not write to the clipboard: ${result.error}`)
-  }
-
-  async _grabClipboard() {
+  async grabFromClipboard() {
     await this._grantClipboardAccess()
-    const result = (await this.browser.executeAsync(readClipboardScript, CLIPBOARD_TIMEOUT)) || {}
+    const result = (await this.browser.executeAsync(clipboardAsyncScript(readClipboardScript), CLIPBOARD_READ_TIMEOUT_MS)) || {}
     if (result.error) throw new Error(`Could not read the clipboard: ${result.error}`)
     this.debugSection('Clipboard', result.value)
     return result.value
   }
 
+  /**
+   * {{> clearClipboard }}
+   */
+  async clearClipboard() {
+    await this._grantClipboardAccess()
+    const result = (await this.browser.executeAsync(clipboardAsyncScript(writeClipboardScript), '')) || {}
+    if (result.error) throw new Error(`Could not write to the clipboard: ${result.error}`)
+  }
+
   async _grantClipboardAccess() {
     if (typeof this.browser.setPermissions !== 'function') return
     await this.browser.setPermissions({ name: 'clipboard-read' }, 'granted').catch(() => {})
@@ -3649,35 +3653,4 @@ async function proceedSelectOption(elem, option) {
   return forEachAsync(els, clickOptionFn)
 }
 
-const CLIPBOARD_TIMEOUT = 5000
-
-function readClipboardScript(timeout, done) {
-  let finished = false
-  const finish = result => {
-    if (finished) return
-    finished = true
-    done(result)
-  }
-  if (!navigator.clipboard || !navigator.clipboard.readText) {
-    finish({ error: 'Clipboard API is not available on this page, it requires a secure context (https or localhost)' })
-    return
-  }
-  setTimeout(() => finish({ error: 'timed out while reading the clipboard' }), timeout)
-  navigator.clipboard.readText().then(
-    text => finish({ value: text }),
-    err => finish({ error: (err && err.message) || String(err) }),
-  )
-}
-
-function writeClipboardScript(text, done) {
-  if (!navigator.clipboard || !navigator.clipboard.writeText) {
-    done({ error: 'Clipboard API is not available on this page, it requires a secure context (https or localhost)' })
-    return
-  }
-  navigator.clipboard.writeText(text).then(
-    () => done({}),
-    err => done({ error: (err && err.message) || String(err) }),
-  )
-}
-
 export { WebDriver as default }

lib/helper/extras/clipboard.js

@@ -0,0 +1,31 @@
+export const CLIPBOARD_READ_TIMEOUT_MS = 5000
+
+export function readClipboardScript(timeout) {
+  if (!navigator.clipboard || !navigator.clipboard.readText) {
+    throw new Error('Clipboard API is not available on this page, it requires a secure context (https or localhost)')
+  }
+  return Promise.race([navigator.clipboard.readText(), new Promise((resolve, reject) => setTimeout(() => reject(new Error('timed out while reading the clipboard')), timeout))])
+}
+
+export function writeClipboardScript(text) {
+  if (!navigator.clipboard || !navigator.clipboard.writeText) {
+    throw new Error('Clipboard API is not available on this page, it requires a secure context (https or localhost)')
+  }
+  return navigator.clipboard.writeText(text)
+}
+
+export function clipboardExpression(script, arg) {
+  return `(${script.toString()})(${JSON.stringify(arg)})`
+}
+
+export function clipboardAsyncScript(script) {
+  return `
+    var done = arguments[arguments.length - 1]
+    var fail = function (err) { done({ error: (err && err.message) || String(err) }) }
+    try {
+      (${script.toString()})(arguments[0]).then(function (value) { done({ value: value }) }, fail)
+    } catch (err) {
+      fail(err)
+    }
+  `
+}