playwright-clipboard-testing 0.1.0 → 0.3.0

package/README.md

@@ -2,11 +2,23 @@
 
 # Playwright Clipboard Testing
 
-Custom Playwright fixture and matchers for testing clipboard functionality in your web applications.
+Effortless clipboard testing for Playwright. Features custom fixtures, smart polling matchers, and auto-managed permissions.
 
+[![Tests](https://github.com/sergoleksenko/playwright-clipboard-testing/actions/workflows/tests.yml/badge.svg)](https://github.com/sergoleksenko/playwright-clipboard-testing/actions/workflows/tests.yml)
+[![npm version](https://img.shields.io/npm/v/playwright-clipboard-testing.svg?style=flat&color=blue)](https://www.npmjs.com/package/playwright-clipboard-testing)
+[![npm downloads](https://img.shields.io/npm/dw/playwright-clipboard-testing.svg?color=blue)](https://www.npmjs.com/package/playwright-clipboard-testing)
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg?style=flat&color=blue)](LICENSE)
 
+## Why?
+Testing the Clipboard API in Playwright usually requires boilerplate code to manually grant `clipboard-read` and `clipboard-write` permissions for every context, write custom page functions, or deal with tricky async polling issues.
+
+**playwright-clipboard-testing** simplifies this with:
+- 🔌 **Zero configuration** — Chromium permissions are granted automatically under the hood (Firefox requires a 1-line config setup).
+- 🔄 **Built-in Auto-retries & Polling** — Uses Playwright's native `expect` polling to wait until the clipboard updates asynchronously.
+- 📦 **TypeScript Ready** — Full type safety for JSON objects with `readJSON<T>()`.
+
 ## Table of Contents
+- [Why?](#why)
 - [Installation](#installation)
 - [Browser Support](#browser-support)
 - [Usage](#usage)
@@ -14,6 +26,8 @@ Custom Playwright fixture and matchers for testing clipboard functionality in yo
   - [Extended Usage](#extended-usage)
 - [API](#api)
   - [Clipboard Fixture](#clipboard-fixture)
+  - [toHaveText Matcher](#tohavetext-matcher)
+  - [toHaveJSON Matcher](#tohavejson-matcher)
   - [toHaveData Matcher](#tohavedata-matcher)
 - [Author](#author)
 - [License](#license)
@@ -25,17 +39,39 @@ npm install --save-dev playwright-clipboard-testing
 ```
 
 ## Browser Support
-![NOTE](https://img.shields.io/badge/NOTE-Only%20supported%20in%20Chromium%20browsers-yellow)
+![NOTE](https://img.shields.io/badge/NOTE-WebKit%20browser%20does%20not%20support%20the%20Clipboard%20API-yellow)
+
+Clipboard API testing is currently supported in Chromium-based and Firefox browsers.
+
+> **Note:** Permissions are auto-managed out of the box for Chromium. Firefox requires a one-time preference setup in your config.
 
-The Web Clipboard Permissions API is currently only supported in Chromium-based browsers.
-If your Playwright setup runs tests across multiple browsers, skip non-Chromium runs in tests that use the clipboard:
+If your Playwright setup runs tests in WebKit, you can skip clipboard tests for that browser:
 ```ts
 test('should copy text to clipboard', async ({ page, clipboard, browserName }) => {
-  test.skip(browserName !== 'chromium', 'Clipboard API is only supported in Chromium');
+  test.skip(browserName === 'webkit', 'Clipboard API is only supported in Chromium and Firefox');
 
   // test logic...
 });
 ```
+If your Playwright setup runs tests in Firefox, manually configure `firefoxUserPrefs` in your Playwright config:
+```ts
+import { defineConfig, devices } from '@playwright/test';
+import { firefoxClipboardPrefs } from 'playwright-clipboard-testing';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'firefox',
+      use: {
+        ...devices['Desktop Firefox'],
+        launchOptions: {
+          firefoxUserPrefs: firefoxClipboardPrefs,
+        },
+      },
+    },
+  ],
+});
+```
 
 ## Usage
 ### Direct Usage
@@ -46,7 +82,7 @@ import { test, expect } from 'playwright-clipboard-testing';
 
 test('should copy text to clipboard', async ({ page, clipboard }) => {
   await page.goto('https://example.com');
-  await page.click('#copy-button');
+  await page.locator('#copy-button').click();
   
   await expect(clipboard).toHaveData('Hello, World!');
 });
@@ -57,13 +93,18 @@ test('should copy text to clipboard', async ({ page, clipboard }) => {
 If you already have a custom test fixture file, extend Playwright's `test` and `expect` with `clipboardFixture` and `clipboardMatchers`:
 ```ts
 import { expect as baseExpect, test as baseTest } from '@playwright/test';
-import { type ClipboardHandler, clipboardFixture, clipboardMatchers } from 'playwright-clipboard-testing';
+import {
+  type ClipboardHandler,
+  clipboardFixture,
+  clipboardMatchers,
+} from 'playwright-clipboard-testing';
 
 export const test = baseTest.extend<{ clipboard: ClipboardHandler }>({
   clipboard: clipboardFixture,
 });
 
 export const expect = baseExpect.extend(clipboardMatchers);
+
 ```
 
 ## API
@@ -72,9 +113,40 @@ The `clipboard` fixture provides direct access to the browser clipboard during t
 - `clipboard.read(): Promise<string>` - reads the current plain text content from the clipboard.
 - `clipboard.readJSON<T>(): Promise<T>` - reads the current clipboard content and parses it as a JSON object of type `T`. Throws an error if the content is not valid JSON.
 
-![NOTE](https://img.shields.io/badge/NOTE-For%20your%20tests%20we%20recommend%20using%20the%20toHaveData%20matcher-yellow)
+![NOTE](https://img.shields.io/badge/NOTE-For%20your%20tests%20we%20recommend%20using%20existing%20matchers%20to%20assert%20clipboard%20content-yellow)
+
+### toHaveText Matcher
+`expect(clipboard).toHaveText(expected, options?)`
+
+Asserts that the clipboard content matches the expected string. Uses Playwright's smart polling mechanism to wait for the clipboard to update.
+- `expected: string` — Expected text to compare against.
+- `options.timeout: number (optional, default: 10000ms)` — Time in milliseconds to wait for the clipboard content to match.
+```ts
+// assert that the clipboard contains the expected text
+await expect(clipboard).toHaveText('Hello, World!');
+```
+```ts
+// Custom timeout
+await expect(clipboard).toHaveText('Async copied value', { timeout: 5000 });
+```
+
+### toHaveJSON Matcher
+`expect(clipboard).toHaveJSON(expected, options?)`
+Asserts that the clipboard content matches the expected JSON value. Uses Playwright's smart polling mechanism to wait for the clipboard to update.
+- `expected: unknown` — Expected JSON value to compare against.
+- `options.timeout: number (optional, default: 10000ms)` — Time in milliseconds to wait for the clipboard content to match.
+```ts
+// assert that the clipboard contains the expected JSON data
+await expect(clipboard).toHaveJSON({ message: 'Hello, World!' });
+```
+```ts
+// Custom timeout
+await expect(clipboard).toHaveJSON({ message: 'Async copied value' }, { timeout: 5000 });
+```
 
 ### toHaveData Matcher
+![NOTE](https://img.shields.io/badge/NOTE-Matcher%20is%20deprecated%20in%20favor%20of%20toHaveText%20and%20toHaveJSON-yellow)
+
 `expect(clipboard).toHaveData(expected, options?)`
 
 Asserts that the clipboard content matches the expected string or JSON object. Uses Playwright's smart polling mechanism to wait for the clipboard to update.
@@ -98,3 +170,6 @@ Sergii Oleksenko <serg.oleksenko@gmail.com>
 
 ## License
 [MIT](LICENSE)
+
+---
+If you find this project useful, give it a ⭐️ on [GitHub](https://github.com/sergoleksenko/playwright-clipboard-testing)!

package/dist/index.cjs

@@ -23,30 +23,43 @@ __export(index_exports, {
   ClipboardHandler: () => ClipboardHandler,
   clipboardFixture: () => clipboardFixture,
   clipboardMatchers: () => clipboardMatchers,
-  expect: () => expect2,
+  expect: () => expect3,
+  firefoxClipboardPrefs: () => firefoxClipboardPrefs,
   test: () => test
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/constants.ts
+var firefoxClipboardPrefs = {
+  "dom.events.testing.asyncClipboard": true,
+  "dom.events.asyncClipboard.readText": true,
+  "dom.events.asyncClipboard.writeText": true,
+  "permissions.default.clipboard-read": 1,
+  "permissions.default.clipboard-write": 1
+};
+
 // src/utils/clipboardHandler.ts
 var ClipboardHandler = class {
-  constructor(page, context) {
+  constructor(page, context, browserName = "chromium") {
     this.page = page;
     this.context = context;
+    this.browserName = browserName;
     this.isPermissionGranted = false;
   }
   page;
   context;
+  browserName;
   isPermissionGranted;
   /**
-   * Grants the necessary clipboard permissions ('clipboard-read' and 'clipboard-write') to the browser context.
-   * This method is called internally before any clipboard read operation to ensure permissions are set.
+   * Grants clipboard permissions to the Chromium browser context if not already granted.
    * @private
    */
   async grantPermissions() {
-    if (!this.isPermissionGranted) {
-      await this.context.grantPermissions(["clipboard-read", "clipboard-write"]);
-      this.isPermissionGranted = true;
+    if (this.browserName === "chromium") {
+      if (!this.isPermissionGranted) {
+        await this.context.grantPermissions(["clipboard-read", "clipboard-write"]);
+        this.isPermissionGranted = true;
+      }
     }
   }
   /**
@@ -80,20 +93,20 @@ var ClipboardHandler = class {
 
 // src/fixtures/clipboardFixture.ts
 var clipboardFixture = async ({ page, context, browserName }, use) => {
-  if (browserName !== "chromium") {
+  if (browserName === "webkit") {
     throw new Error(
-      `[playwright-clipboard] Browser '${browserName}' is not supported. Clipboard Permissions API is currently only supported in Chromium-based browsers.
-Use test.skip(browserName !== 'chromium') in your tests to skip non-Chromium runs.`
+      `[playwright-clipboard] Browser '${browserName}' is not supported. Clipboard API testing is currently supported only in Chromium-based and Firefox browsers.
+Add test.skip(browserName === 'webkit', 'Clipboard API is only supported in Chromium and Firefox'); to your test body.`
     );
   }
-  const handler = new ClipboardHandler(page, context);
+  const handler = new ClipboardHandler(page, context, browserName);
   await use(handler);
 };
 
 // src/fixtures.ts
-var import_test2 = require("@playwright/test");
+var import_test3 = require("@playwright/test");
 
-// src/matchers/toHaveData.ts
+// src/matchers/toHaveJSON.ts
 var import_test = require("@playwright/test");
 
 // src/utils/matcherUtils.ts
@@ -112,23 +125,68 @@ ${error.message}`;
 Received: ${this.utils.printReceived(actual)}`;
 }
 
-// src/matchers/toHaveData.ts
-async function toHaveData(clipboard, expected, options = {}) {
-  const name = "toHaveData";
+// src/matchers/toHaveJSON.ts
+async function toHaveJSON(clipboard, expected, options = {}) {
+  const name = "toHaveJSON";
   let pass;
   let actual;
+  let errorReason = null;
   const { timeout = 1e4 } = options;
   const poll = import_test.expect.poll(
     async () => {
       try {
         actual = await clipboard.readJSON();
-      } catch {
-        actual = await clipboard.read();
+        errorReason = null;
+        return actual;
+      } catch (error) {
+        errorReason = error instanceof Error ? error : new Error(String(error));
+        try {
+          actual = await clipboard.read();
+        } catch {
+          actual = void 0;
+        }
+        throw errorReason;
       }
-      if (typeof expected === "string" && actual !== null && actual !== void 0) {
-        return String(actual);
+    },
+    { timeout }
+  );
+  try {
+    const expectation = this.isNot ? poll.not : poll;
+    await expectation.toEqual(expected);
+    pass = true;
+  } catch {
+    pass = false;
+  }
+  if (this.isNot) pass = !pass;
+  const matcherReturn = {
+    message: getErrorMessage.call(this, name, expected, actual, errorReason),
+    pass,
+    name,
+    expected,
+    actual
+  };
+  return matcherReturn;
+}
+
+// src/matchers/toHaveText.ts
+var import_test2 = require("@playwright/test");
+async function toHaveText(clipboard, expected, options = {}) {
+  const name = "toHaveText";
+  let pass;
+  let actual;
+  let errorReason = null;
+  const { timeout = 1e4 } = options;
+  const poll = import_test2.expect.poll(
+    async () => {
+      try {
+        actual = await clipboard.read();
+        errorReason = null;
+        return actual;
+      } catch (error) {
+        errorReason = error instanceof Error ? error : new Error(String(error));
+        actual = void 0;
+        throw errorReason;
       }
-      return actual;
     },
     { timeout }
   );
@@ -141,7 +199,7 @@ async function toHaveData(clipboard, expected, options = {}) {
   }
   if (this.isNot) pass = !pass;
   const matcherReturn = {
-    message: getErrorMessage.call(this, name, expected, actual),
+    message: getErrorMessage.call(this, name, expected, actual, errorReason),
     pass,
     name,
     expected,
@@ -150,26 +208,48 @@ async function toHaveData(clipboard, expected, options = {}) {
   return matcherReturn;
 }
 
+// src/matchers/toHaveData.ts
+async function toHaveData(clipboard, expected, options = {}) {
+  const name = "toHaveData";
+  let matcherReturn = null;
+  if (typeof expected === "string") {
+    matcherReturn = await toHaveText.call(this, clipboard, expected, options);
+  } else {
+    matcherReturn = await toHaveJSON.call(this, clipboard, expected, options);
+  }
+  return {
+    ...matcherReturn,
+    name,
+    message: () => {
+      const originalMessage = matcherReturn.message();
+      return originalMessage.replace("toHaveText", name).replace("toHaveJSON", name);
+    }
+  };
+}
+
 // src/matchers/clipboardMatchers.ts
 var clipboardMatchers = {
+  toHaveText,
+  toHaveJSON,
   toHaveData
 };
 
 // src/fixtures.ts
-var test = import_test2.test.extend({
+var test = import_test3.test.extend({
   /**
    * A fixture that provides an instance of the Clipboard utility for interacting with the system clipboard.
    * It allows reading from the clipboard during tests.
    */
   clipboard: clipboardFixture
 });
-var expect2 = import_test2.expect.extend({ ...clipboardMatchers });
+var expect3 = import_test3.expect.extend({ ...clipboardMatchers });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ClipboardHandler,
   clipboardFixture,
   clipboardMatchers,
   expect,
+  firefoxClipboardPrefs,
   test
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/utils/clipboardHandler.ts","../src/fixtures/clipboardFixture.ts","../src/fixtures.ts","../src/matchers/toHaveData.ts","../src/utils/matcherUtils.ts","../src/matchers/clipboardMatchers.ts"],"sourcesContent":["export { clipboardFixture } from './fixtures/clipboardFixture.js';\nexport { expect, test } from './fixtures.js';\nexport { clipboardMatchers } from './matchers/clipboardMatchers.js';\nexport { ClipboardHandler } from './utils/clipboardHandler.js';\n","/**\n * Playwright-compatible Clipboard utilities.\n *\n * Core functions for interacting with the browser clipboard within Playwright tests.\n * Provides wrappers for reading plain text and JSON.\n *\n * @remarks\n * These utilities require 'clipboard-read' and 'clipboard-write' permissions\n * to be granted in the browser context.\n */\n\nimport type { BrowserContext, Page } from '@playwright/test';\n\nexport class ClipboardHandler {\n  private isPermissionGranted: boolean;\n\n  constructor(\n    private readonly page: Page,\n    private readonly context: BrowserContext,\n  ) {\n    this.isPermissionGranted = false;\n  }\n\n  /**\n   * Grants the necessary clipboard permissions ('clipboard-read' and 'clipboard-write') to the browser context.\n   * This method is called internally before any clipboard read operation to ensure permissions are set.\n   * @private\n   */\n  private async grantPermissions() {\n    if (!this.isPermissionGranted) {\n      await this.context.grantPermissions(['clipboard-read', 'clipboard-write']);\n      this.isPermissionGranted = true;\n    }\n  }\n\n  /**\n   * Reads the current text content from the browser clipboard.\n   * If the content is a JSON-encoded string (e.g., has extra quotes),\n   * it will be returned as is. Use readJSON for automatic parsing.\n   *\n   * @returns A promise that resolves to the clipboard string content.\n   */\n  async read(): Promise<string> {\n    await this.grantPermissions();\n    return await this.page.evaluate(() => navigator.clipboard.readText());\n  }\n\n  /**\n   * Reads the clipboard content and parses it as JSON.\n   * If the content is a string literal (e.g., '\"value\"'), it returns the unwrapped string ('value').\n   *\n   * @template T - The expected type of the parsed JSON object.\n   * @returns A promise that resolves to the parsed JSON object of type T.\n   * @throws {Error} If the clipboard content is not a valid JSON string.\n   */\n  async readJSON<T = unknown>(): Promise<T> {\n    const text = await this.read();\n    try {\n      return JSON.parse(text);\n    } catch {\n      throw new Error(`Clipboard content is not a valid JSON: ${JSON.stringify(text)}`);\n    }\n  }\n}\n","import type { BrowserContext, Page, TestFixture } from '@playwright/test';\nimport { ClipboardHandler } from '../utils/clipboardHandler.js';\n\n/**\n * A fixture that provides an instance of the Clipboard utility for interacting with the system clipboard.\n * It allows reading from the clipboard during tests.\n */\nexport const clipboardFixture: TestFixture<\n  ClipboardHandler,\n  { page: Page; context: BrowserContext; browserName: string }\n> = async ({ page, context, browserName }, use) => {\n  if (browserName !== 'chromium') {\n    throw new Error(\n      `[playwright-clipboard] Browser '${browserName}' is not supported. ` +\n        'Clipboard Permissions API is currently only supported in Chromium-based browsers.\\n' +\n        `Use test.skip(browserName !== 'chromium') in your tests to skip non-Chromium runs.`,\n    );\n  }\n\n  const handler = new ClipboardHandler(page, context);\n  await use(handler);\n};\n","import { expect as baseExpect, test as baseTest } from '@playwright/test';\nimport { clipboardFixture } from './fixtures/clipboardFixture.js';\nimport { clipboardMatchers } from './matchers/clipboardMatchers.js';\nimport type { ClipboardHandler } from './utils/clipboardHandler.js';\n\nexport const test = baseTest.extend<{\n  clipboard: ClipboardHandler;\n}>({\n  /**\n   * A fixture that provides an instance of the Clipboard utility for interacting with the system clipboard.\n   * It allows reading from the clipboard during tests.\n   */\n  clipboard: clipboardFixture,\n});\n\nexport const expect = baseExpect.extend({ ...clipboardMatchers });\n","import { type ExpectMatcherState, expect, type MatcherReturnType } from '@playwright/test';\nimport type { ClipboardHandler } from '../utils/clipboardHandler.js';\nimport { getErrorMessage } from '../utils/matcherUtils.js';\nimport type { MatcherOptions } from './types.js';\n\n/**\n * Asserts that the clipboard content matches the expected value.\n * Uses smart polling to wait for the clipboard to be updated.\n * If the `expected` value is an object, it attempts to parse the clipboard\n * content as JSON before comparing.\n *\n * @this ExpectMatcherState\n * @param clipboard The Clipboard utility instance.\n * @param expected The string or object to compare against the clipboard content.\n * @param options Optional settings for the matcher, such as timeout.\n * @returns A Promise that resolves to a MatcherReturnType object.\n */\nexport async function toHaveData(\n  this: ExpectMatcherState,\n  clipboard: ClipboardHandler,\n  expected: unknown,\n  options: MatcherOptions = {},\n) {\n  const name = 'toHaveData';\n  let pass: boolean;\n  let actual: unknown;\n\n  const { timeout = 10_000 } = options;\n\n  const poll = expect.poll(\n    async () => {\n      try {\n        actual = await clipboard.readJSON();\n      } catch {\n        actual = await clipboard.read();\n      }\n\n      if (typeof expected === 'string' && actual !== null && actual !== undefined) {\n        return String(actual);\n      }\n\n      return actual;\n    },\n    { timeout },\n  );\n\n  try {\n    const expectation = this.isNot ? poll.not : poll;\n    await expectation.toEqual(expected);\n    pass = true;\n  } catch {\n    pass = false;\n  }\n\n  /**\n   * NOTE ON INVERSION:\n   * In Playwright custom matchers, if `this.isNot` is true, the matcher must return\n   * `pass: false` for the assertion to pass. Since `poll.not.toEqual` resolves\n   * to `true` when the condition is met, we invert it back to align with Playwright's expectations.\n   */\n  if (this.isNot) pass = !pass;\n\n  const matcherReturn: MatcherReturnType = {\n    message: getErrorMessage.call(this, name, expected, actual),\n    pass,\n    name,\n    expected,\n    actual,\n  };\n\n  return matcherReturn;\n}\n","import type { ExpectMatcherState } from '@playwright/test';\n\n/**\n * Generates an error message for a custom matcher.\n *\n * @this ExpectMatcherState\n * @param name The name of the matcher.\n * @param expected The expected value.\n * @param actual The actual value.\n * @param error An optional error object.\n * @param errorMessage An optional error message string.\n * @returns A function that returns the error message string.\n */\nexport function getErrorMessage(\n  this: ExpectMatcherState,\n  name: string,\n  expected: unknown,\n  actual: unknown,\n  error?: Error | null,\n  errorMessage?: string | undefined | null,\n): () => string {\n  const message = `${this.utils.matcherHint(name, undefined, undefined, { isNot: this.isNot })}\\n\\n`;\n\n  if (error) {\n    return () => `${message}An unexpected error occurred:\\n${error.message}`;\n  }\n\n  if (errorMessage) {\n    return () => `${message}${errorMessage}`;\n  }\n\n  return () =>\n    message +\n    `Expected: ${this.isNot ? 'not ' : ''}${this.utils.printExpected(expected)}\\n` +\n    `Received: ${this.utils.printReceived(actual)}`;\n}\n","import { toHaveData } from './toHaveData.js';\n\n/**\n * Export an object containing all the custom clipboard matchers for Playwright.\n */\nexport const clipboardMatchers = {\n  toHaveData,\n};\n"],"mappings":"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","names":["expect","import_test","baseTest","expect","baseExpect"]}
+{"version":3,"sources":["../src/index.ts","../src/constants.ts","../src/utils/clipboardHandler.ts","../src/fixtures/clipboardFixture.ts","../src/fixtures.ts","../src/matchers/toHaveJSON.ts","../src/utils/matcherUtils.ts","../src/matchers/toHaveText.ts","../src/matchers/toHaveData.ts","../src/matchers/clipboardMatchers.ts"],"sourcesContent":["export { firefoxClipboardPrefs } from './constants.js';\nexport { clipboardFixture } from './fixtures/clipboardFixture.js';\nexport { expect, test } from './fixtures.js';\nexport { clipboardMatchers } from './matchers/clipboardMatchers.js';\nexport { ClipboardHandler } from './utils/clipboardHandler.js';\n","export const firefoxClipboardPrefs = {\n  'dom.events.testing.asyncClipboard': true,\n  'dom.events.asyncClipboard.readText': true,\n  'dom.events.asyncClipboard.writeText': true,\n  'permissions.default.clipboard-read': 1,\n  'permissions.default.clipboard-write': 1,\n};\n","/**\n * Playwright-compatible Clipboard utilities.\n *\n * Core functions for interacting with the browser clipboard within Playwright tests.\n * Provides wrappers for reading plain text and JSON.\n *\n * @remarks\n * These utilities require 'clipboard-read' and 'clipboard-write' permissions\n * to be granted in the browser context.\n */\n\nimport type { BrowserContext, Page } from '@playwright/test';\nimport type { BrowserName } from '../types.js';\n\nexport class ClipboardHandler {\n  private readonly browserName: BrowserName;\n  private isPermissionGranted: boolean;\n\n  constructor(\n    private readonly page: Page,\n    private readonly context: BrowserContext,\n    browserName: BrowserName = 'chromium',\n  ) {\n    this.browserName = browserName;\n    this.isPermissionGranted = false;\n  }\n\n  /**\n   * Grants clipboard permissions to the Chromium browser context if not already granted.\n   * @private\n   */\n  private async grantPermissions() {\n    if (this.browserName === 'chromium') {\n      if (!this.isPermissionGranted) {\n        await this.context.grantPermissions(['clipboard-read', 'clipboard-write']);\n        this.isPermissionGranted = true;\n      }\n    }\n  }\n\n  /**\n   * Reads the current text content from the browser clipboard.\n   * If the content is a JSON-encoded string (e.g., has extra quotes),\n   * it will be returned as is. Use readJSON for automatic parsing.\n   *\n   * @returns A promise that resolves to the clipboard string content.\n   */\n  async read(): Promise<string> {\n    await this.grantPermissions();\n    return await this.page.evaluate(() => navigator.clipboard.readText());\n  }\n\n  /**\n   * Reads the clipboard content and parses it as JSON.\n   * If the content is a string literal (e.g., '\"value\"'), it returns the unwrapped string ('value').\n   *\n   * @template T - The expected type of the parsed JSON object.\n   * @returns A promise that resolves to the parsed JSON object of type T.\n   * @throws {Error} If the clipboard content is not a valid JSON string.\n   */\n  async readJSON<T = unknown>(): Promise<T> {\n    const text = await this.read();\n    try {\n      return JSON.parse(text);\n    } catch {\n      throw new Error(`Clipboard content is not a valid JSON: ${JSON.stringify(text)}`);\n    }\n  }\n}\n","import type { BrowserContext, Page, TestFixture } from '@playwright/test';\nimport type { BrowserName } from '../types.js';\nimport { ClipboardHandler } from '../utils/clipboardHandler.js';\n\n/**\n * A fixture that provides an instance of the Clipboard utility for interacting with the system clipboard.\n * It allows reading from the clipboard during tests.\n */\nexport const clipboardFixture: TestFixture<\n  ClipboardHandler,\n  { page: Page; context: BrowserContext; browserName: BrowserName }\n> = async ({ page, context, browserName }, use) => {\n  if (browserName === 'webkit') {\n    throw new Error(\n      `[playwright-clipboard] Browser '${browserName}' is not supported. ` +\n        'Clipboard API testing is currently supported only in Chromium-based and Firefox browsers.\\n' +\n        `Add test.skip(browserName === 'webkit', 'Clipboard API is only supported in Chromium and Firefox'); to your test body.`,\n    );\n  }\n\n  const handler = new ClipboardHandler(page, context, browserName);\n  await use(handler);\n};\n","import { expect as baseExpect, test as baseTest } from '@playwright/test';\nimport { clipboardFixture } from './fixtures/clipboardFixture.js';\nimport { clipboardMatchers } from './matchers/clipboardMatchers.js';\nimport type { ClipboardHandler } from './utils/clipboardHandler.js';\n\nexport const test = baseTest.extend<{\n  clipboard: ClipboardHandler;\n}>({\n  /**\n   * A fixture that provides an instance of the Clipboard utility for interacting with the system clipboard.\n   * It allows reading from the clipboard during tests.\n   */\n  clipboard: clipboardFixture,\n});\n\nexport const expect = baseExpect.extend({ ...clipboardMatchers });\n","import type { ExpectMatcherState, MatcherReturnType } from '@playwright/test';\nimport { expect } from '@playwright/test';\nimport type { ClipboardHandler } from '../utils/clipboardHandler.js';\nimport { getErrorMessage } from '../utils/matcherUtils.js';\nimport type { MatcherOptions } from './types.js';\n\n/**\n * Asserts that the clipboard content matches the expected JSON value.\n *\n * @this ExpectMatcherState\n * @param clipboard The Clipboard utility instance.\n * @param expected The expected JSON value.\n * @param options Matcher options.\n * @returns A Promise that resolves to a MatcherReturnType object.\n */\nexport async function toHaveJSON(\n  this: ExpectMatcherState,\n  clipboard: ClipboardHandler,\n  expected: unknown,\n  options: MatcherOptions = {},\n) {\n  const name = 'toHaveJSON';\n  let pass: boolean;\n  let actual: unknown;\n  let errorReason: Error | null = null;\n\n  const { timeout = 10_000 } = options;\n\n  const poll = expect.poll(\n    async () => {\n      try {\n        actual = await clipboard.readJSON();\n        errorReason = null;\n        return actual;\n      } catch (error) {\n        errorReason = error instanceof Error ? error : new Error(String(error));\n\n        try {\n          actual = await clipboard.read();\n        } catch {\n          actual = undefined;\n        }\n\n        throw errorReason;\n      }\n    },\n    { timeout },\n  );\n\n  try {\n    const expectation = this.isNot ? poll.not : poll;\n    await expectation.toEqual(expected);\n    pass = true;\n  } catch {\n    pass = false;\n  }\n\n  if (this.isNot) pass = !pass;\n\n  const matcherReturn: MatcherReturnType = {\n    message: getErrorMessage.call(this, name, expected, actual, errorReason),\n    pass,\n    name,\n    expected,\n    actual,\n  };\n\n  return matcherReturn;\n}\n","import type { ExpectMatcherState } from '@playwright/test';\n\n/**\n * Generates an error message for a custom matcher.\n *\n * @this ExpectMatcherState\n * @param name The name of the matcher.\n * @param expected The expected value.\n * @param actual The actual value.\n * @param error An optional error object.\n * @param errorMessage An optional error message string.\n * @returns A function that returns the error message string.\n */\nexport function getErrorMessage(\n  this: ExpectMatcherState,\n  name: string,\n  expected: unknown,\n  actual: unknown,\n  error?: Error | null,\n  errorMessage?: string | undefined | null,\n): () => string {\n  const message = `${this.utils.matcherHint(name, undefined, undefined, { isNot: this.isNot })}\\n\\n`;\n\n  if (error) {\n    return () => `${message}An unexpected error occurred:\\n${error.message}`;\n  }\n\n  if (errorMessage) {\n    return () => `${message}${errorMessage}`;\n  }\n\n  return () =>\n    message +\n    `Expected: ${this.isNot ? 'not ' : ''}${this.utils.printExpected(expected)}\\n` +\n    `Received: ${this.utils.printReceived(actual)}`;\n}\n","import { type ExpectMatcherState, expect, type MatcherReturnType } from '@playwright/test';\nimport type { ClipboardHandler } from '../utils/clipboardHandler.js';\nimport { getErrorMessage } from '../utils/matcherUtils.js';\nimport type { MatcherOptions } from './types.js';\n\n/**\n * Asserts that the clipboard content matches the expected text value.\n *\n * @this ExpectMatcherState\n * @param clipboard The Clipboard utility instance.\n * @param expected The expected text value.\n * @param options Matcher options.\n * @returns A Promise that resolves to a MatcherReturnType object.\n */\nexport async function toHaveText(\n  this: ExpectMatcherState,\n  clipboard: ClipboardHandler,\n  expected: string,\n  options: MatcherOptions = {},\n) {\n  const name = 'toHaveText';\n  let pass: boolean;\n  let actual: unknown;\n  let errorReason: Error | null = null;\n\n  const { timeout = 10_000 } = options;\n\n  const poll = expect.poll(\n    async () => {\n      try {\n        actual = await clipboard.read();\n        errorReason = null;\n        return actual;\n      } catch (error) {\n        errorReason = error instanceof Error ? error : new Error(String(error));\n        actual = undefined;\n\n        throw errorReason;\n      }\n    },\n    { timeout },\n  );\n\n  try {\n    const expectation = this.isNot ? poll.not : poll;\n    await expectation.toEqual(expected);\n    pass = true;\n  } catch {\n    pass = false;\n  }\n\n  if (this.isNot) pass = !pass;\n\n  const matcherReturn: MatcherReturnType = {\n    message: getErrorMessage.call(this, name, expected, actual, errorReason),\n    pass,\n    name,\n    expected,\n    actual,\n  };\n\n  return matcherReturn;\n}\n","import type { ExpectMatcherState, MatcherReturnType } from '@playwright/test';\nimport type { ClipboardHandler } from '../utils/clipboardHandler.js';\nimport { toHaveJSON } from './toHaveJSON.js';\nimport { toHaveText } from './toHaveText.js';\nimport type { MatcherOptions } from './types.js';\n\n/**\n * Asserts that the clipboard content matches the expected value.\n * Uses smart polling to wait for the clipboard to be updated.\n * If the `expected` value is an object, it attempts to parse the clipboard\n * content as JSON before comparing.\n *\n * @this ExpectMatcherState\n * @param clipboard The Clipboard utility instance.\n * @param expected The string or object to compare against the clipboard content.\n * @param options Optional settings for the matcher, such as timeout.\n * @returns A Promise that resolves to a MatcherReturnType object.\n */\nexport async function toHaveData(\n  this: ExpectMatcherState,\n  clipboard: ClipboardHandler,\n  expected: unknown,\n  options: MatcherOptions = {},\n) {\n  const name = 'toHaveData';\n  let matcherReturn: MatcherReturnType | null = null;\n\n  if (typeof expected === 'string') {\n    matcherReturn = await toHaveText.call(this, clipboard, expected, options);\n  } else {\n    matcherReturn = await toHaveJSON.call(this, clipboard, expected, options);\n  }\n\n  return {\n    ...matcherReturn,\n    name,\n    message: () => {\n      const originalMessage = matcherReturn.message();\n      return originalMessage.replace('toHaveText', name).replace('toHaveJSON', name);\n    },\n  };\n}\n","import { toHaveData } from './toHaveData.js';\nimport { toHaveJSON } from './toHaveJSON.js';\nimport { toHaveText } from './toHaveText.js';\n\n/**\n * Export an object containing all the custom clipboard matchers for Playwright.\n */\nexport const clipboardMatchers = {\n  toHaveText,\n  toHaveJSON,\n  toHaveData,\n};\n"],"mappings":"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","names":["expect","import_test","import_test","baseTest","expect","baseExpect"]}

package/dist/index.d.cts

@@ -1,6 +1,16 @@
 import * as _playwright_test from '@playwright/test';
 import { Page, BrowserContext, TestFixture, ExpectMatcherState, MatcherReturnType } from '@playwright/test';
 
+declare const firefoxClipboardPrefs: {
+    'dom.events.testing.asyncClipboard': boolean;
+    'dom.events.asyncClipboard.readText': boolean;
+    'dom.events.asyncClipboard.writeText': boolean;
+    'permissions.default.clipboard-read': number;
+    'permissions.default.clipboard-write': number;
+};
+
+type BrowserName = 'chromium' | 'firefox' | 'webkit';
+
 /**
  * Playwright-compatible Clipboard utilities.
  *
@@ -15,11 +25,11 @@ import { Page, BrowserContext, TestFixture, ExpectMatcherState, MatcherReturnTyp
 declare class ClipboardHandler {
     private readonly page;
     private readonly context;
+    private readonly browserName;
     private isPermissionGranted;
-    constructor(page: Page, context: BrowserContext);
+    constructor(page: Page, context: BrowserContext, browserName?: BrowserName);
     /**
-     * Grants the necessary clipboard permissions ('clipboard-read' and 'clipboard-write') to the browser context.
-     * This method is called internally before any clipboard read operation to ensure permissions are set.
+     * Grants clipboard permissions to the Chromium browser context if not already granted.
      * @private
      */
     private grantPermissions;
@@ -49,7 +59,7 @@ declare class ClipboardHandler {
 declare const clipboardFixture: TestFixture<ClipboardHandler, {
     page: Page;
     context: BrowserContext;
-    browserName: string;
+    browserName: BrowserName;
 }>;
 
 type MatcherOptions = {
@@ -58,12 +68,38 @@ type MatcherOptions = {
 declare global {
     namespace PlaywrightTest {
         interface Matchers<R> {
+            /**
+             * Asserts that the clipboard content matches the expected text.
+             * Uses smart polling to wait for the clipboard to be updated.
+             *
+             * @param expected The string to compare against the clipboard content.
+             * @param options Matcher options.
+             * @returns A Promise that resolves when the assertion completes.
+             *
+             * @example
+             * await expect(clipboard).toHaveText('Copied value');
+             */
+            toHaveText(expected: string, options?: MatcherOptions): Promise<R>;
+            /**
+             * Asserts that the clipboard content matches the expected JSON value.
+             * Uses smart polling to wait for the clipboard to be updated.
+             *
+             * @param expected The JSON value to compare against the clipboard content.
+             * @param options Matcher options.
+             * @returns A Promise that resolves when the assertion completes.
+             *
+             * @example
+             * await expect(clipboard).toHaveJSON({ id: 123, status: 'success' });
+             */
+            toHaveJSON(expected: unknown, options?: MatcherOptions): Promise<R>;
             /**
              * Asserts that the clipboard content matches the expected value.
              * Uses smart polling to wait for the clipboard to be updated.
              * If the `expected` value is an object, it attempts to parse the clipboard
              * content as JSON before comparing.
              *
+             * @deprecated Use `toHaveText` or `toHaveJSON` instead. This matcher will be removed in future versions.
+             *
              * @param expected The string or object to compare against the clipboard content.
              * @param options Optional settings for the matcher, such as timeout.
              * @returns A Promise that resolves when the assertion completes.
@@ -89,12 +125,44 @@ declare global {
  * @param options Optional settings for the matcher, such as timeout.
  * @returns A Promise that resolves to a MatcherReturnType object.
  */
-declare function toHaveData(this: ExpectMatcherState, clipboard: ClipboardHandler, expected: unknown, options?: MatcherOptions): Promise<MatcherReturnType>;
+declare function toHaveData(this: ExpectMatcherState, clipboard: ClipboardHandler, expected: unknown, options?: MatcherOptions): Promise<{
+    name: string;
+    message: () => string;
+    pass: boolean;
+    expected?: unknown;
+    actual?: any;
+    log?: string[];
+    timeout?: number;
+}>;
+
+/**
+ * Asserts that the clipboard content matches the expected JSON value.
+ *
+ * @this ExpectMatcherState
+ * @param clipboard The Clipboard utility instance.
+ * @param expected The expected JSON value.
+ * @param options Matcher options.
+ * @returns A Promise that resolves to a MatcherReturnType object.
+ */
+declare function toHaveJSON(this: ExpectMatcherState, clipboard: ClipboardHandler, expected: unknown, options?: MatcherOptions): Promise<MatcherReturnType>;
+
+/**
+ * Asserts that the clipboard content matches the expected text value.
+ *
+ * @this ExpectMatcherState
+ * @param clipboard The Clipboard utility instance.
+ * @param expected The expected text value.
+ * @param options Matcher options.
+ * @returns A Promise that resolves to a MatcherReturnType object.
+ */
+declare function toHaveText(this: ExpectMatcherState, clipboard: ClipboardHandler, expected: string, options?: MatcherOptions): Promise<MatcherReturnType>;
 
 declare const test: _playwright_test.TestType<_playwright_test.PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & {
     clipboard: ClipboardHandler;
 }, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions>;
 declare const expect: _playwright_test.Expect<{
+    toHaveText: typeof toHaveText;
+    toHaveJSON: typeof toHaveJSON;
     toHaveData: typeof toHaveData;
 }>;
 
@@ -102,7 +170,9 @@ declare const expect: _playwright_test.Expect<{
  * Export an object containing all the custom clipboard matchers for Playwright.
  */
 declare const clipboardMatchers: {
+    toHaveText: typeof toHaveText;
+    toHaveJSON: typeof toHaveJSON;
     toHaveData: typeof toHaveData;
 };
 
-export { ClipboardHandler, clipboardFixture, clipboardMatchers, expect, test };
+export { ClipboardHandler, clipboardFixture, clipboardMatchers, expect, firefoxClipboardPrefs, test };

package/dist/index.d.ts

@@ -1,6 +1,16 @@
 import * as _playwright_test from '@playwright/test';
 import { Page, BrowserContext, TestFixture, ExpectMatcherState, MatcherReturnType } from '@playwright/test';
 
+declare const firefoxClipboardPrefs: {
+    'dom.events.testing.asyncClipboard': boolean;
+    'dom.events.asyncClipboard.readText': boolean;
+    'dom.events.asyncClipboard.writeText': boolean;
+    'permissions.default.clipboard-read': number;
+    'permissions.default.clipboard-write': number;
+};
+
+type BrowserName = 'chromium' | 'firefox' | 'webkit';
+
 /**
  * Playwright-compatible Clipboard utilities.
  *
@@ -15,11 +25,11 @@ import { Page, BrowserContext, TestFixture, ExpectMatcherState, MatcherReturnTyp
 declare class ClipboardHandler {
     private readonly page;
     private readonly context;
+    private readonly browserName;
     private isPermissionGranted;
-    constructor(page: Page, context: BrowserContext);
+    constructor(page: Page, context: BrowserContext, browserName?: BrowserName);
     /**
-     * Grants the necessary clipboard permissions ('clipboard-read' and 'clipboard-write') to the browser context.
-     * This method is called internally before any clipboard read operation to ensure permissions are set.
+     * Grants clipboard permissions to the Chromium browser context if not already granted.
      * @private
      */
     private grantPermissions;
@@ -49,7 +59,7 @@ declare class ClipboardHandler {
 declare const clipboardFixture: TestFixture<ClipboardHandler, {
     page: Page;
     context: BrowserContext;
-    browserName: string;
+    browserName: BrowserName;
 }>;
 
 type MatcherOptions = {
@@ -58,12 +68,38 @@ type MatcherOptions = {
 declare global {
     namespace PlaywrightTest {
         interface Matchers<R> {
+            /**
+             * Asserts that the clipboard content matches the expected text.
+             * Uses smart polling to wait for the clipboard to be updated.
+             *
+             * @param expected The string to compare against the clipboard content.
+             * @param options Matcher options.
+             * @returns A Promise that resolves when the assertion completes.
+             *
+             * @example
+             * await expect(clipboard).toHaveText('Copied value');
+             */
+            toHaveText(expected: string, options?: MatcherOptions): Promise<R>;
+            /**
+             * Asserts that the clipboard content matches the expected JSON value.
+             * Uses smart polling to wait for the clipboard to be updated.
+             *
+             * @param expected The JSON value to compare against the clipboard content.
+             * @param options Matcher options.
+             * @returns A Promise that resolves when the assertion completes.
+             *
+             * @example
+             * await expect(clipboard).toHaveJSON({ id: 123, status: 'success' });
+             */
+            toHaveJSON(expected: unknown, options?: MatcherOptions): Promise<R>;
             /**
              * Asserts that the clipboard content matches the expected value.
              * Uses smart polling to wait for the clipboard to be updated.
              * If the `expected` value is an object, it attempts to parse the clipboard
              * content as JSON before comparing.
              *
+             * @deprecated Use `toHaveText` or `toHaveJSON` instead. This matcher will be removed in future versions.
+             *
              * @param expected The string or object to compare against the clipboard content.
              * @param options Optional settings for the matcher, such as timeout.
              * @returns A Promise that resolves when the assertion completes.
@@ -89,12 +125,44 @@ declare global {
  * @param options Optional settings for the matcher, such as timeout.
  * @returns A Promise that resolves to a MatcherReturnType object.
  */
-declare function toHaveData(this: ExpectMatcherState, clipboard: ClipboardHandler, expected: unknown, options?: MatcherOptions): Promise<MatcherReturnType>;
+declare function toHaveData(this: ExpectMatcherState, clipboard: ClipboardHandler, expected: unknown, options?: MatcherOptions): Promise<{
+    name: string;
+    message: () => string;
+    pass: boolean;
+    expected?: unknown;
+    actual?: any;
+    log?: string[];
+    timeout?: number;
+}>;
+
+/**
+ * Asserts that the clipboard content matches the expected JSON value.
+ *
+ * @this ExpectMatcherState
+ * @param clipboard The Clipboard utility instance.
+ * @param expected The expected JSON value.
+ * @param options Matcher options.
+ * @returns A Promise that resolves to a MatcherReturnType object.
+ */
+declare function toHaveJSON(this: ExpectMatcherState, clipboard: ClipboardHandler, expected: unknown, options?: MatcherOptions): Promise<MatcherReturnType>;
+
+/**
+ * Asserts that the clipboard content matches the expected text value.
+ *
+ * @this ExpectMatcherState
+ * @param clipboard The Clipboard utility instance.
+ * @param expected The expected text value.
+ * @param options Matcher options.
+ * @returns A Promise that resolves to a MatcherReturnType object.
+ */
+declare function toHaveText(this: ExpectMatcherState, clipboard: ClipboardHandler, expected: string, options?: MatcherOptions): Promise<MatcherReturnType>;
 
 declare const test: _playwright_test.TestType<_playwright_test.PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & {
     clipboard: ClipboardHandler;
 }, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions>;
 declare const expect: _playwright_test.Expect<{
+    toHaveText: typeof toHaveText;
+    toHaveJSON: typeof toHaveJSON;
     toHaveData: typeof toHaveData;
 }>;
 
@@ -102,7 +170,9 @@ declare const expect: _playwright_test.Expect<{
  * Export an object containing all the custom clipboard matchers for Playwright.
  */
 declare const clipboardMatchers: {
+    toHaveText: typeof toHaveText;
+    toHaveJSON: typeof toHaveJSON;
     toHaveData: typeof toHaveData;
 };
 
-export { ClipboardHandler, clipboardFixture, clipboardMatchers, expect, test };
+export { ClipboardHandler, clipboardFixture, clipboardMatchers, expect, firefoxClipboardPrefs, test };

package/dist/index.js

@@ -1,22 +1,34 @@
+// src/constants.ts
+var firefoxClipboardPrefs = {
+  "dom.events.testing.asyncClipboard": true,
+  "dom.events.asyncClipboard.readText": true,
+  "dom.events.asyncClipboard.writeText": true,
+  "permissions.default.clipboard-read": 1,
+  "permissions.default.clipboard-write": 1
+};
+
 // src/utils/clipboardHandler.ts
 var ClipboardHandler = class {
-  constructor(page, context) {
+  constructor(page, context, browserName = "chromium") {
     this.page = page;
     this.context = context;
+    this.browserName = browserName;
     this.isPermissionGranted = false;
   }
   page;
   context;
+  browserName;
   isPermissionGranted;
   /**
-   * Grants the necessary clipboard permissions ('clipboard-read' and 'clipboard-write') to the browser context.
-   * This method is called internally before any clipboard read operation to ensure permissions are set.
+   * Grants clipboard permissions to the Chromium browser context if not already granted.
    * @private
    */
   async grantPermissions() {
-    if (!this.isPermissionGranted) {
-      await this.context.grantPermissions(["clipboard-read", "clipboard-write"]);
-      this.isPermissionGranted = true;
+    if (this.browserName === "chromium") {
+      if (!this.isPermissionGranted) {
+        await this.context.grantPermissions(["clipboard-read", "clipboard-write"]);
+        this.isPermissionGranted = true;
+      }
     }
   }
   /**
@@ -50,20 +62,20 @@ var ClipboardHandler = class {
 
 // src/fixtures/clipboardFixture.ts
 var clipboardFixture = async ({ page, context, browserName }, use) => {
-  if (browserName !== "chromium") {
+  if (browserName === "webkit") {
     throw new Error(
-      `[playwright-clipboard] Browser '${browserName}' is not supported. Clipboard Permissions API is currently only supported in Chromium-based browsers.
-Use test.skip(browserName !== 'chromium') in your tests to skip non-Chromium runs.`
+      `[playwright-clipboard] Browser '${browserName}' is not supported. Clipboard API testing is currently supported only in Chromium-based and Firefox browsers.
+Add test.skip(browserName === 'webkit', 'Clipboard API is only supported in Chromium and Firefox'); to your test body.`
     );
   }
-  const handler = new ClipboardHandler(page, context);
+  const handler = new ClipboardHandler(page, context, browserName);
   await use(handler);
 };
 
 // src/fixtures.ts
 import { expect as baseExpect, test as baseTest } from "@playwright/test";
 
-// src/matchers/toHaveData.ts
+// src/matchers/toHaveJSON.ts
 import { expect } from "@playwright/test";
 
 // src/utils/matcherUtils.ts
@@ -82,23 +94,68 @@ ${error.message}`;
 Received: ${this.utils.printReceived(actual)}`;
 }
 
-// src/matchers/toHaveData.ts
-async function toHaveData(clipboard, expected, options = {}) {
-  const name = "toHaveData";
+// src/matchers/toHaveJSON.ts
+async function toHaveJSON(clipboard, expected, options = {}) {
+  const name = "toHaveJSON";
   let pass;
   let actual;
+  let errorReason = null;
   const { timeout = 1e4 } = options;
   const poll = expect.poll(
     async () => {
       try {
         actual = await clipboard.readJSON();
-      } catch {
-        actual = await clipboard.read();
+        errorReason = null;
+        return actual;
+      } catch (error) {
+        errorReason = error instanceof Error ? error : new Error(String(error));
+        try {
+          actual = await clipboard.read();
+        } catch {
+          actual = void 0;
+        }
+        throw errorReason;
       }
-      if (typeof expected === "string" && actual !== null && actual !== void 0) {
-        return String(actual);
+    },
+    { timeout }
+  );
+  try {
+    const expectation = this.isNot ? poll.not : poll;
+    await expectation.toEqual(expected);
+    pass = true;
+  } catch {
+    pass = false;
+  }
+  if (this.isNot) pass = !pass;
+  const matcherReturn = {
+    message: getErrorMessage.call(this, name, expected, actual, errorReason),
+    pass,
+    name,
+    expected,
+    actual
+  };
+  return matcherReturn;
+}
+
+// src/matchers/toHaveText.ts
+import { expect as expect2 } from "@playwright/test";
+async function toHaveText(clipboard, expected, options = {}) {
+  const name = "toHaveText";
+  let pass;
+  let actual;
+  let errorReason = null;
+  const { timeout = 1e4 } = options;
+  const poll = expect2.poll(
+    async () => {
+      try {
+        actual = await clipboard.read();
+        errorReason = null;
+        return actual;
+      } catch (error) {
+        errorReason = error instanceof Error ? error : new Error(String(error));
+        actual = void 0;
+        throw errorReason;
       }
-      return actual;
     },
     { timeout }
   );
@@ -111,7 +168,7 @@ async function toHaveData(clipboard, expected, options = {}) {
   }
   if (this.isNot) pass = !pass;
   const matcherReturn = {
-    message: getErrorMessage.call(this, name, expected, actual),
+    message: getErrorMessage.call(this, name, expected, actual, errorReason),
     pass,
     name,
     expected,
@@ -120,8 +177,29 @@ async function toHaveData(clipboard, expected, options = {}) {
   return matcherReturn;
 }
 
+// src/matchers/toHaveData.ts
+async function toHaveData(clipboard, expected, options = {}) {
+  const name = "toHaveData";
+  let matcherReturn = null;
+  if (typeof expected === "string") {
+    matcherReturn = await toHaveText.call(this, clipboard, expected, options);
+  } else {
+    matcherReturn = await toHaveJSON.call(this, clipboard, expected, options);
+  }
+  return {
+    ...matcherReturn,
+    name,
+    message: () => {
+      const originalMessage = matcherReturn.message();
+      return originalMessage.replace("toHaveText", name).replace("toHaveJSON", name);
+    }
+  };
+}
+
 // src/matchers/clipboardMatchers.ts
 var clipboardMatchers = {
+  toHaveText,
+  toHaveJSON,
   toHaveData
 };
 
@@ -133,12 +211,13 @@ var test = baseTest.extend({
    */
   clipboard: clipboardFixture
 });
-var expect2 = baseExpect.extend({ ...clipboardMatchers });
+var expect3 = baseExpect.extend({ ...clipboardMatchers });
 export {
   ClipboardHandler,
   clipboardFixture,
   clipboardMatchers,
-  expect2 as expect,
+  expect3 as expect,
+  firefoxClipboardPrefs,
   test
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/utils/clipboardHandler.ts","../src/fixtures/clipboardFixture.ts","../src/fixtures.ts","../src/matchers/toHaveData.ts","../src/utils/matcherUtils.ts","../src/matchers/clipboardMatchers.ts"],"sourcesContent":["/**\n * Playwright-compatible Clipboard utilities.\n *\n * Core functions for interacting with the browser clipboard within Playwright tests.\n * Provides wrappers for reading plain text and JSON.\n *\n * @remarks\n * These utilities require 'clipboard-read' and 'clipboard-write' permissions\n * to be granted in the browser context.\n */\n\nimport type { BrowserContext, Page } from '@playwright/test';\n\nexport class ClipboardHandler {\n  private isPermissionGranted: boolean;\n\n  constructor(\n    private readonly page: Page,\n    private readonly context: BrowserContext,\n  ) {\n    this.isPermissionGranted = false;\n  }\n\n  /**\n   * Grants the necessary clipboard permissions ('clipboard-read' and 'clipboard-write') to the browser context.\n   * This method is called internally before any clipboard read operation to ensure permissions are set.\n   * @private\n   */\n  private async grantPermissions() {\n    if (!this.isPermissionGranted) {\n      await this.context.grantPermissions(['clipboard-read', 'clipboard-write']);\n      this.isPermissionGranted = true;\n    }\n  }\n\n  /**\n   * Reads the current text content from the browser clipboard.\n   * If the content is a JSON-encoded string (e.g., has extra quotes),\n   * it will be returned as is. Use readJSON for automatic parsing.\n   *\n   * @returns A promise that resolves to the clipboard string content.\n   */\n  async read(): Promise<string> {\n    await this.grantPermissions();\n    return await this.page.evaluate(() => navigator.clipboard.readText());\n  }\n\n  /**\n   * Reads the clipboard content and parses it as JSON.\n   * If the content is a string literal (e.g., '\"value\"'), it returns the unwrapped string ('value').\n   *\n   * @template T - The expected type of the parsed JSON object.\n   * @returns A promise that resolves to the parsed JSON object of type T.\n   * @throws {Error} If the clipboard content is not a valid JSON string.\n   */\n  async readJSON<T = unknown>(): Promise<T> {\n    const text = await this.read();\n    try {\n      return JSON.parse(text);\n    } catch {\n      throw new Error(`Clipboard content is not a valid JSON: ${JSON.stringify(text)}`);\n    }\n  }\n}\n","import type { BrowserContext, Page, TestFixture } from '@playwright/test';\nimport { ClipboardHandler } from '../utils/clipboardHandler.js';\n\n/**\n * A fixture that provides an instance of the Clipboard utility for interacting with the system clipboard.\n * It allows reading from the clipboard during tests.\n */\nexport const clipboardFixture: TestFixture<\n  ClipboardHandler,\n  { page: Page; context: BrowserContext; browserName: string }\n> = async ({ page, context, browserName }, use) => {\n  if (browserName !== 'chromium') {\n    throw new Error(\n      `[playwright-clipboard] Browser '${browserName}' is not supported. ` +\n        'Clipboard Permissions API is currently only supported in Chromium-based browsers.\\n' +\n        `Use test.skip(browserName !== 'chromium') in your tests to skip non-Chromium runs.`,\n    );\n  }\n\n  const handler = new ClipboardHandler(page, context);\n  await use(handler);\n};\n","import { expect as baseExpect, test as baseTest } from '@playwright/test';\nimport { clipboardFixture } from './fixtures/clipboardFixture.js';\nimport { clipboardMatchers } from './matchers/clipboardMatchers.js';\nimport type { ClipboardHandler } from './utils/clipboardHandler.js';\n\nexport const test = baseTest.extend<{\n  clipboard: ClipboardHandler;\n}>({\n  /**\n   * A fixture that provides an instance of the Clipboard utility for interacting with the system clipboard.\n   * It allows reading from the clipboard during tests.\n   */\n  clipboard: clipboardFixture,\n});\n\nexport const expect = baseExpect.extend({ ...clipboardMatchers });\n","import { type ExpectMatcherState, expect, type MatcherReturnType } from '@playwright/test';\nimport type { ClipboardHandler } from '../utils/clipboardHandler.js';\nimport { getErrorMessage } from '../utils/matcherUtils.js';\nimport type { MatcherOptions } from './types.js';\n\n/**\n * Asserts that the clipboard content matches the expected value.\n * Uses smart polling to wait for the clipboard to be updated.\n * If the `expected` value is an object, it attempts to parse the clipboard\n * content as JSON before comparing.\n *\n * @this ExpectMatcherState\n * @param clipboard The Clipboard utility instance.\n * @param expected The string or object to compare against the clipboard content.\n * @param options Optional settings for the matcher, such as timeout.\n * @returns A Promise that resolves to a MatcherReturnType object.\n */\nexport async function toHaveData(\n  this: ExpectMatcherState,\n  clipboard: ClipboardHandler,\n  expected: unknown,\n  options: MatcherOptions = {},\n) {\n  const name = 'toHaveData';\n  let pass: boolean;\n  let actual: unknown;\n\n  const { timeout = 10_000 } = options;\n\n  const poll = expect.poll(\n    async () => {\n      try {\n        actual = await clipboard.readJSON();\n      } catch {\n        actual = await clipboard.read();\n      }\n\n      if (typeof expected === 'string' && actual !== null && actual !== undefined) {\n        return String(actual);\n      }\n\n      return actual;\n    },\n    { timeout },\n  );\n\n  try {\n    const expectation = this.isNot ? poll.not : poll;\n    await expectation.toEqual(expected);\n    pass = true;\n  } catch {\n    pass = false;\n  }\n\n  /**\n   * NOTE ON INVERSION:\n   * In Playwright custom matchers, if `this.isNot` is true, the matcher must return\n   * `pass: false` for the assertion to pass. Since `poll.not.toEqual` resolves\n   * to `true` when the condition is met, we invert it back to align with Playwright's expectations.\n   */\n  if (this.isNot) pass = !pass;\n\n  const matcherReturn: MatcherReturnType = {\n    message: getErrorMessage.call(this, name, expected, actual),\n    pass,\n    name,\n    expected,\n    actual,\n  };\n\n  return matcherReturn;\n}\n","import type { ExpectMatcherState } from '@playwright/test';\n\n/**\n * Generates an error message for a custom matcher.\n *\n * @this ExpectMatcherState\n * @param name The name of the matcher.\n * @param expected The expected value.\n * @param actual The actual value.\n * @param error An optional error object.\n * @param errorMessage An optional error message string.\n * @returns A function that returns the error message string.\n */\nexport function getErrorMessage(\n  this: ExpectMatcherState,\n  name: string,\n  expected: unknown,\n  actual: unknown,\n  error?: Error | null,\n  errorMessage?: string | undefined | null,\n): () => string {\n  const message = `${this.utils.matcherHint(name, undefined, undefined, { isNot: this.isNot })}\\n\\n`;\n\n  if (error) {\n    return () => `${message}An unexpected error occurred:\\n${error.message}`;\n  }\n\n  if (errorMessage) {\n    return () => `${message}${errorMessage}`;\n  }\n\n  return () =>\n    message +\n    `Expected: ${this.isNot ? 'not ' : ''}${this.utils.printExpected(expected)}\\n` +\n    `Received: ${this.utils.printReceived(actual)}`;\n}\n","import { toHaveData } from './toHaveData.js';\n\n/**\n * Export an object containing all the custom clipboard matchers for Playwright.\n */\nexport const clipboardMatchers = {\n  toHaveData,\n};\n"],"mappings":"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","names":["expect"]}
+{"version":3,"sources":["../src/constants.ts","../src/utils/clipboardHandler.ts","../src/fixtures/clipboardFixture.ts","../src/fixtures.ts","../src/matchers/toHaveJSON.ts","../src/utils/matcherUtils.ts","../src/matchers/toHaveText.ts","../src/matchers/toHaveData.ts","../src/matchers/clipboardMatchers.ts"],"sourcesContent":["export const firefoxClipboardPrefs = {\n  'dom.events.testing.asyncClipboard': true,\n  'dom.events.asyncClipboard.readText': true,\n  'dom.events.asyncClipboard.writeText': true,\n  'permissions.default.clipboard-read': 1,\n  'permissions.default.clipboard-write': 1,\n};\n","/**\n * Playwright-compatible Clipboard utilities.\n *\n * Core functions for interacting with the browser clipboard within Playwright tests.\n * Provides wrappers for reading plain text and JSON.\n *\n * @remarks\n * These utilities require 'clipboard-read' and 'clipboard-write' permissions\n * to be granted in the browser context.\n */\n\nimport type { BrowserContext, Page } from '@playwright/test';\nimport type { BrowserName } from '../types.js';\n\nexport class ClipboardHandler {\n  private readonly browserName: BrowserName;\n  private isPermissionGranted: boolean;\n\n  constructor(\n    private readonly page: Page,\n    private readonly context: BrowserContext,\n    browserName: BrowserName = 'chromium',\n  ) {\n    this.browserName = browserName;\n    this.isPermissionGranted = false;\n  }\n\n  /**\n   * Grants clipboard permissions to the Chromium browser context if not already granted.\n   * @private\n   */\n  private async grantPermissions() {\n    if (this.browserName === 'chromium') {\n      if (!this.isPermissionGranted) {\n        await this.context.grantPermissions(['clipboard-read', 'clipboard-write']);\n        this.isPermissionGranted = true;\n      }\n    }\n  }\n\n  /**\n   * Reads the current text content from the browser clipboard.\n   * If the content is a JSON-encoded string (e.g., has extra quotes),\n   * it will be returned as is. Use readJSON for automatic parsing.\n   *\n   * @returns A promise that resolves to the clipboard string content.\n   */\n  async read(): Promise<string> {\n    await this.grantPermissions();\n    return await this.page.evaluate(() => navigator.clipboard.readText());\n  }\n\n  /**\n   * Reads the clipboard content and parses it as JSON.\n   * If the content is a string literal (e.g., '\"value\"'), it returns the unwrapped string ('value').\n   *\n   * @template T - The expected type of the parsed JSON object.\n   * @returns A promise that resolves to the parsed JSON object of type T.\n   * @throws {Error} If the clipboard content is not a valid JSON string.\n   */\n  async readJSON<T = unknown>(): Promise<T> {\n    const text = await this.read();\n    try {\n      return JSON.parse(text);\n    } catch {\n      throw new Error(`Clipboard content is not a valid JSON: ${JSON.stringify(text)}`);\n    }\n  }\n}\n","import type { BrowserContext, Page, TestFixture } from '@playwright/test';\nimport type { BrowserName } from '../types.js';\nimport { ClipboardHandler } from '../utils/clipboardHandler.js';\n\n/**\n * A fixture that provides an instance of the Clipboard utility for interacting with the system clipboard.\n * It allows reading from the clipboard during tests.\n */\nexport const clipboardFixture: TestFixture<\n  ClipboardHandler,\n  { page: Page; context: BrowserContext; browserName: BrowserName }\n> = async ({ page, context, browserName }, use) => {\n  if (browserName === 'webkit') {\n    throw new Error(\n      `[playwright-clipboard] Browser '${browserName}' is not supported. ` +\n        'Clipboard API testing is currently supported only in Chromium-based and Firefox browsers.\\n' +\n        `Add test.skip(browserName === 'webkit', 'Clipboard API is only supported in Chromium and Firefox'); to your test body.`,\n    );\n  }\n\n  const handler = new ClipboardHandler(page, context, browserName);\n  await use(handler);\n};\n","import { expect as baseExpect, test as baseTest } from '@playwright/test';\nimport { clipboardFixture } from './fixtures/clipboardFixture.js';\nimport { clipboardMatchers } from './matchers/clipboardMatchers.js';\nimport type { ClipboardHandler } from './utils/clipboardHandler.js';\n\nexport const test = baseTest.extend<{\n  clipboard: ClipboardHandler;\n}>({\n  /**\n   * A fixture that provides an instance of the Clipboard utility for interacting with the system clipboard.\n   * It allows reading from the clipboard during tests.\n   */\n  clipboard: clipboardFixture,\n});\n\nexport const expect = baseExpect.extend({ ...clipboardMatchers });\n","import type { ExpectMatcherState, MatcherReturnType } from '@playwright/test';\nimport { expect } from '@playwright/test';\nimport type { ClipboardHandler } from '../utils/clipboardHandler.js';\nimport { getErrorMessage } from '../utils/matcherUtils.js';\nimport type { MatcherOptions } from './types.js';\n\n/**\n * Asserts that the clipboard content matches the expected JSON value.\n *\n * @this ExpectMatcherState\n * @param clipboard The Clipboard utility instance.\n * @param expected The expected JSON value.\n * @param options Matcher options.\n * @returns A Promise that resolves to a MatcherReturnType object.\n */\nexport async function toHaveJSON(\n  this: ExpectMatcherState,\n  clipboard: ClipboardHandler,\n  expected: unknown,\n  options: MatcherOptions = {},\n) {\n  const name = 'toHaveJSON';\n  let pass: boolean;\n  let actual: unknown;\n  let errorReason: Error | null = null;\n\n  const { timeout = 10_000 } = options;\n\n  const poll = expect.poll(\n    async () => {\n      try {\n        actual = await clipboard.readJSON();\n        errorReason = null;\n        return actual;\n      } catch (error) {\n        errorReason = error instanceof Error ? error : new Error(String(error));\n\n        try {\n          actual = await clipboard.read();\n        } catch {\n          actual = undefined;\n        }\n\n        throw errorReason;\n      }\n    },\n    { timeout },\n  );\n\n  try {\n    const expectation = this.isNot ? poll.not : poll;\n    await expectation.toEqual(expected);\n    pass = true;\n  } catch {\n    pass = false;\n  }\n\n  if (this.isNot) pass = !pass;\n\n  const matcherReturn: MatcherReturnType = {\n    message: getErrorMessage.call(this, name, expected, actual, errorReason),\n    pass,\n    name,\n    expected,\n    actual,\n  };\n\n  return matcherReturn;\n}\n","import type { ExpectMatcherState } from '@playwright/test';\n\n/**\n * Generates an error message for a custom matcher.\n *\n * @this ExpectMatcherState\n * @param name The name of the matcher.\n * @param expected The expected value.\n * @param actual The actual value.\n * @param error An optional error object.\n * @param errorMessage An optional error message string.\n * @returns A function that returns the error message string.\n */\nexport function getErrorMessage(\n  this: ExpectMatcherState,\n  name: string,\n  expected: unknown,\n  actual: unknown,\n  error?: Error | null,\n  errorMessage?: string | undefined | null,\n): () => string {\n  const message = `${this.utils.matcherHint(name, undefined, undefined, { isNot: this.isNot })}\\n\\n`;\n\n  if (error) {\n    return () => `${message}An unexpected error occurred:\\n${error.message}`;\n  }\n\n  if (errorMessage) {\n    return () => `${message}${errorMessage}`;\n  }\n\n  return () =>\n    message +\n    `Expected: ${this.isNot ? 'not ' : ''}${this.utils.printExpected(expected)}\\n` +\n    `Received: ${this.utils.printReceived(actual)}`;\n}\n","import { type ExpectMatcherState, expect, type MatcherReturnType } from '@playwright/test';\nimport type { ClipboardHandler } from '../utils/clipboardHandler.js';\nimport { getErrorMessage } from '../utils/matcherUtils.js';\nimport type { MatcherOptions } from './types.js';\n\n/**\n * Asserts that the clipboard content matches the expected text value.\n *\n * @this ExpectMatcherState\n * @param clipboard The Clipboard utility instance.\n * @param expected The expected text value.\n * @param options Matcher options.\n * @returns A Promise that resolves to a MatcherReturnType object.\n */\nexport async function toHaveText(\n  this: ExpectMatcherState,\n  clipboard: ClipboardHandler,\n  expected: string,\n  options: MatcherOptions = {},\n) {\n  const name = 'toHaveText';\n  let pass: boolean;\n  let actual: unknown;\n  let errorReason: Error | null = null;\n\n  const { timeout = 10_000 } = options;\n\n  const poll = expect.poll(\n    async () => {\n      try {\n        actual = await clipboard.read();\n        errorReason = null;\n        return actual;\n      } catch (error) {\n        errorReason = error instanceof Error ? error : new Error(String(error));\n        actual = undefined;\n\n        throw errorReason;\n      }\n    },\n    { timeout },\n  );\n\n  try {\n    const expectation = this.isNot ? poll.not : poll;\n    await expectation.toEqual(expected);\n    pass = true;\n  } catch {\n    pass = false;\n  }\n\n  if (this.isNot) pass = !pass;\n\n  const matcherReturn: MatcherReturnType = {\n    message: getErrorMessage.call(this, name, expected, actual, errorReason),\n    pass,\n    name,\n    expected,\n    actual,\n  };\n\n  return matcherReturn;\n}\n","import type { ExpectMatcherState, MatcherReturnType } from '@playwright/test';\nimport type { ClipboardHandler } from '../utils/clipboardHandler.js';\nimport { toHaveJSON } from './toHaveJSON.js';\nimport { toHaveText } from './toHaveText.js';\nimport type { MatcherOptions } from './types.js';\n\n/**\n * Asserts that the clipboard content matches the expected value.\n * Uses smart polling to wait for the clipboard to be updated.\n * If the `expected` value is an object, it attempts to parse the clipboard\n * content as JSON before comparing.\n *\n * @this ExpectMatcherState\n * @param clipboard The Clipboard utility instance.\n * @param expected The string or object to compare against the clipboard content.\n * @param options Optional settings for the matcher, such as timeout.\n * @returns A Promise that resolves to a MatcherReturnType object.\n */\nexport async function toHaveData(\n  this: ExpectMatcherState,\n  clipboard: ClipboardHandler,\n  expected: unknown,\n  options: MatcherOptions = {},\n) {\n  const name = 'toHaveData';\n  let matcherReturn: MatcherReturnType | null = null;\n\n  if (typeof expected === 'string') {\n    matcherReturn = await toHaveText.call(this, clipboard, expected, options);\n  } else {\n    matcherReturn = await toHaveJSON.call(this, clipboard, expected, options);\n  }\n\n  return {\n    ...matcherReturn,\n    name,\n    message: () => {\n      const originalMessage = matcherReturn.message();\n      return originalMessage.replace('toHaveText', name).replace('toHaveJSON', name);\n    },\n  };\n}\n","import { toHaveData } from './toHaveData.js';\nimport { toHaveJSON } from './toHaveJSON.js';\nimport { toHaveText } from './toHaveText.js';\n\n/**\n * Export an object containing all the custom clipboard matchers for Playwright.\n */\nexport const clipboardMatchers = {\n  toHaveText,\n  toHaveJSON,\n  toHaveData,\n};\n"],"mappings":"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","names":["expect","expect","expect"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-clipboard-testing",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Playwright fixture and custom matchers for clipboard testing and assertions.",
   "author": "Sergii Oleksenko <serg.oleksenko@gmail.com>",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "sideEffects": false,
   "scripts": {
@@ -50,13 +50,15 @@
     "lint:fix": "biome check --write .",
     "typecheck": "tsc --noEmit",
     "format": "biome format --write .",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.10",
     "@playwright/test": "1.62.1",
     "tsup": "^8.5.1",
-    "typescript": "5.8.3"
+    "typescript": "5.8.3",
+    "vitest": "^4.1.11"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.40.0"