[lexical-website] Documentation Update: Rewrite testing guide#8811
Conversation
mayrang
requested review from
acywatson,
etrepum,
fantactuka,
ivailop7,
potatowagon and
zurfyx
as code owners
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
meta-cla
Bot
added
the
CLA Signed
etrepum
left a comment
etrepum
left a comment
There was a problem hiding this comment.
It might be worth adding some vitest browser tests to one of the examples (maybe one of the more modern ones) so that people have a demo that can be extracted
|
|
||
| :::info | ||
|
|
||
| jsdom does not implement `contentEditable` editing. In a real browser, a keystroke inside a `contentEditable` element goes through the browser's native editing engine, which modifies the DOM and fires `beforeinput`/`input` events that Lexical observes. jsdom has no such engine, so dispatching synthetic `InputEvent`s does nothing — there is nothing to actually insert the text into the DOM. |
There was a problem hiding this comment.
It would be a great idea, once the input handling is refactored, to put together some more precise documentation for how this all works (on another page)
There was a problem hiding this comment.
Will do — I'll plan a dedicated input handling page once the refactoring settles.
| ### What you cannot test in jsdom | ||
|
|
||
| We use [Playwright](https://playwright.dev/) for running E2E tests in Chromium, Firefox and WebKit. Before running these tests, make sure to install the necessary browsers using the following command: | ||
| - Typing by dispatching `KeyboardEvent` or `InputEvent` on the DOM |
There was a problem hiding this comment.
the caveat to this is that we probably do want a KeyboardEvent for the "non-text-input" events that get processed as KEY_ENTER_COMMAND, KEY_TAB_COMMAND, the arrow keys, shortcuts, etc. Whether they start as DOM dispatch or editor.dispatchCommand.
There was a problem hiding this comment.
Added a paragraph after the "cannot test" list clarifying that KeyboardEvent dispatch works for non-text-input events (KEY_ENTER_COMMAND, KEY_TAB_COMMAND, KEY_ARROW_* commands, shortcuts).
|
|
||
| ### Editor cleanup with `using` | ||
|
|
||
| `buildEditorFromExtensions` returns an editor with a `dispose()` method and `Symbol.dispose` support. Declaring it with `using` automatically cleans up registrations at the end of the block: |
There was a problem hiding this comment.
may be worth noting that this is only applicable to unit tests, anything that runs in a browser can not use this syntax yet because it's not available in all of the supported engines
There was a problem hiding this comment.
Updated — the section now says using only works in unit tests (jsdom) and points to editor.dispose() / onTestFinished for browser tests.
…sting guide - Add KeyboardEvent caveat for non-text-input commands in jsdom - Note that `using` syntax is browser-limited; recommend onTestFinished - Add vitest browser test setup to website-toolbar example - Fix npx → pnpm exec for playwright install - Trim redundant catch-all bullet and formulaic closer
|
Added vitest browser tests to |
etrepum
dismissed
their stale review
It looks like the integration tests aren’t recognizing that this needs a playwright install now
The website-toolbar example now includes vitest browser tests that require Playwright. The integration test workflow was missing the setup-playwright step, causing CI failure.
|
playwright install needs to be run from the example, there should be some code to do this because other examples have playwright tests. afk so hard for me to look into exactly what the right change is |
2 participants
Description
The existing testing page was a stub with outdated
npm runcommands and no guidance on how to actually write tests. The most common question from contributors — "why doesn'tuserEvent.type()work?" — wasn't addressed anywhere.This rewrites the page to cover the three test tiers (unit/browser/e2e) with working code examples, explains the jsdom
contentEditablelimitation, and documents practical patterns like{discrete: true}, editor cleanup withusing, and thecompose()helper for IME browser tests.Test plan
npx docusaurus build— clean, no errors.localhost:3010/docs/testing— renders correctly, admonition displays, code blocks highlighted, table formatted.compose()call matchesLexicalComposition.test.tsusage.$getRoot().selectEnd()+insertText()andCONTROLLED_TEXT_INSERTION_COMMANDtested in actual vitest runs.