4f:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/3j06ow7w40nxu.js","/_next/static/immutable/chunks/31nn7jwsjvqii.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"FilesView"] 50:T2251,--- title: Playwright Testing description: Learn how to write Playwright tests that integrate with Plate. --- [Playwright](https://playwright.dev/) enables end-to-end testing in headless browsers. This guide covers integrating Playwright with Plate using `@platejs/playwright`. ## Setup ### Install Dependencies Follow [Playwright's guide](https://playwright.dev/docs/intro) to install Playwright in your app and ensure that you can write basic end-to-end tests. ```bash npm install @platejs/playwright playwright ``` ### Add PlaywrightPlugin In order for your Playwright tests to access and interact with the editor, you'll need to add `PlaywrightPlugin` to your editor: ```tsx const editor = createPlateEditor({ plugins: [ // other plugins... PlaywrightPlugin.configure({ enabled: process.env.NODE_ENV !== 'production' }), ] }) ``` This exposes various utilities on `window.platePlaywrightAdapter`. ### Get Editor Handle Most Playwright test code runs in a non-browser environment. Interacting with a Plate editor requires running JavaScript inside the browser context using Playwright's `evaluate` and `evaluateHandle` [APIs](https://playwright.dev/docs/evaluating). A [handle](https://playwright.dev/docs/handles) references a JavaScript object within the browser. The editor handle refers to the `editor` instance of your Plate editor (`JSHandle`). In your Playwright test, get the editor handle before interacting with Plate: ```ts const editorHandle = await getEditorHandle(page); ``` For multiple editors, specify the editable element: ```ts const editable = getEditable(page.getByTestId('my-editor-container')); const editorHandle = await getEditorHandle(page, editable); ``` The locator must match exactly one `[data-slate-editor]` element. ### Start Writing Tests With the `editorHandle`, you can now write Playwright tests for your editor. ## Examples ### Get a node handle by its path Use `getNodeByPath` to get a handle referencing the node at a specific path. To make assertions about the value of the node, convert it to JSON using `.jsonValue()`. ```ts const nodeHandle = await getNodeByPath(page, editorHandle, [0]); expect(await nodeHandle.jsonValue()).toBe({ type: 'p', children: [{ text: 'My paragraph' }], }); ``` ### Get the type of a node ```ts const firstNodeType = await getTypeAtPath(page, editorHandle, [0]); expect(firstNodeType).toBe('h1'); ``` ### Get the DOM node for a node Often in Playwright, you'll want to reference a specific DOM element in order to make assertions about its state or perform operations involving it. `getDOMNodeByPath` returns an [ElementHandle](https://playwright.dev/docs/api/class-elementhandle) for the DOM node corresponding to the Plate node at a given path. ```ts const firstNodeEl = await getDOMNodeByPath(page, elementHandle, [0]); await firstNodeEl.hover(); ``` ### Click a node ```ts await clickAtPath(page, elementHandle, [0]); ``` ### Get the selection ```ts const selection = await getSelection(page, editorHandle); expect(selection).toBe({ anchor: { path: [0, 0], offset: 0 }, focus: { path: [0, 0], offset: 7 }, }); ``` ### Select a point or range In order to type at a specific point in the editor, you'll need to select that point using `setSelection`. If you select a single point (consisting of a `path` and an `offset`), the cursor will be placed at that point. If you select a range (consisting of an `anchor` and a `focus`), that range will be selected. If you select a path, the entire node at that path will be selected. Make sure you focus the editor before setting the selection. Focusing the editor using `editable.focus()` may not work correctly in WebKit, so the best way of doing this is with `clickAtPath`. ```ts // Click the first paragraph to focus the editor await clickAtPath(page, editorHandle, [0]); await setSelection(page, editorHandle, { path: [0, 0], offset: 2, }); await page.keyboard.type('Hello world!'); ``` ## Imported queries and transforms You may want to import a query or a transform such as `getBlockAbove` or `insertNodes` into your Playwright test and use it. Unfortunately, this is not possible. You can only interact directly with the `editor` instance inside the browser context (using `evaluate` or `evaluateHandle`), and it isn't possible to pass imported functions from Playwright's scope into the browser. This is because neither the `editor` object nor JavaScript functions can be adequately serialized. The best workaround is to interact with the editor in the same way that a user would, without using any imported queries or transforms. This will make your Playwright tests more likely to catch bugs in your application. If this isn't practical, you can instead call a method on the `editor` object inside an `evaluate` or `evaluateHandle`. (Use `evaluateHandle` if you need to return a reference to a DOM node or a JavaScript object from the browser. Use `evaluate` if you need to return a serialized copy of a JavaScript object, or if you don't need to return any value.) Note that while these queries and transforms can't be directly used in Playwright tests, they are available when working with the editor instance in your application code. For more information on how to use these methods in your application, refer to the [Editor Methods](/docs/editor-methods) documentation. See [Playwright's docs](https://playwright.dev/docs/evaluating) for more information about `evaluate` and `evaluateHandle`. ```ts await editorHandle.evaluate((editor) => { editor.tf.insertNodes(/* ... */); }); ``` See [Playwright's docs](https://playwright.dev/docs/evaluating) for more about `evaluate` and `evaluateHandle`. ## API ### `getEditorHandle` Gets a handle to the Plate editor instance. Playwright page object. Locator for editable element. Defaults to first [data-slate-editor]. Handle to Plate editor instance. ### `getNodeByPath` Retrieves a node at the specified path. Playwright page object. Handle to editor instance. Path to node. Handle to node at path. ### `getDOMNodeByPath` Gets the DOM node for a Plate node at the given path. Playwright page object. Handle to editor instance. Path to node. ElementHandle for corresponding DOM node. ### `clickAtPath` Simulates a click on the node at the specified path. Playwright page object. Handle to editor instance. Path to node to click. ### `getSelection` Retrieves the current editor selection. Playwright page object. Handle to editor instance. Current editor selection. ### `setSelection` Sets the editor selection to the specified range. Playwright page object. Handle to editor instance. Location to set selection. ### `getTypeAtPath` Gets the type of the node at the specified path. Playwright page object. Handle to editor instance. Path to node. Type of node at path. 4e:["$","div",null,{"className":"mt-3 flex min-h-0 min-w-0 flex-1 flex-col gap-3","children":[null,["$","$L4f",null,{"files":[{"path":"../../content/docs/(guides)/playwright.mdx","content":"$50","type":"registry:file","target":"content/docs/plate/(guides)/playwright.mdx"}],"className":"h-[70svh] min-h-80"}]]}]