playwright-clipboard-testing 0.2.0 → 0.3.0

package/README.md

@@ -4,6 +4,7 @@
 
 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)
@@ -14,7 +15,7 @@ Testing the Clipboard API in Playwright usually requires boilerplate code to man
 **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** — Out-of-the-box support for JSON objects with full type safety (`readJSON<T>()`).
+- 📦 **TypeScript Ready** — Full type safety for JSON objects with `readJSON<T>()`.
 
 ## Table of Contents
 - [Why?](#why)
@@ -25,6 +26,8 @@ Testing the Clipboard API in Playwright usually requires boilerplate code to man
   - [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)
@@ -110,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.

package/dist/index.cjs

@@ -23,7 +23,7 @@ __export(index_exports, {
   ClipboardHandler: () => ClipboardHandler,
   clipboardFixture: () => clipboardFixture,
   clipboardMatchers: () => clipboardMatchers,
-  expect: () => expect2,
+  expect: () => expect3,
   firefoxClipboardPrefs: () => firefoxClipboardPrefs,
   test: () => test
 });
@@ -104,9 +104,9 @@ Add test.skip(browserName === 'webkit', 'Clipboard API is only supported in Chro
 };
 
 // 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
@@ -125,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 }
   );
@@ -154,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,
@@ -163,20 +208,41 @@ 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,

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/constants.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 { 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, 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 *\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  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

@@ -68,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,6 +115,9 @@ declare global {
 
 /**
  * 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.
  *
  * @this ExpectMatcherState
  * @param clipboard The Clipboard utility instance.
@@ -96,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;
 }>;
 
@@ -109,6 +170,8 @@ 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;
 };
 

package/dist/index.d.ts

@@ -68,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,6 +115,9 @@ declare global {
 
 /**
  * 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.
  *
  * @this ExpectMatcherState
  * @param clipboard The Clipboard utility instance.
@@ -96,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;
 }>;
 
@@ -109,6 +170,8 @@ 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;
 };
 

package/dist/index.js

@@ -75,7 +75,7 @@ Add test.skip(browserName === 'webkit', 'Clipboard API is only supported in Chro
 // 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
@@ -94,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 }
   );
@@ -123,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,
@@ -132,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
 };
 
@@ -145,12 +211,12 @@ 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
 };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/constants.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 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, 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 *\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  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.2.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"