Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/skills/playwright-cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*)

## BlockNote test conventions

When authoring or changing tests in this repository, follow [testing-skill](../testing-skill/SKILL.md). Colocated component/accessibility tests use Vitest browser mode, one `*.test.ts` file with separate describe groups, and the shared Docker e2e runner. Read its [accessibility reference](../testing-skill/references/accessibility-tests.md) for assertion scopes, navigation helpers, and native-only screen-reader tests. These repository conventions take precedence over the generic Playwright test-generation examples below and in the references: do not introduce a standalone Playwright runner, one `.spec.ts` per scenario, or native browser-suite runs.
When authoring or changing tests in this repository, follow [testing-skill](../testing-skill/SKILL.md). Colocated component tests use Vitest browser mode, one `*.browser.test.{ts,tsx}` file with separate describe groups, and the shared Docker e2e runner. Read its [React component testing reference](../testing-skill/references/component-testing.md) for component testing conventions. These repository conventions take precedence over the generic Playwright test-generation examples below and in the references: do not introduce a standalone Playwright runner, one `.spec.ts` per scenario, or native browser-suite runs.

## Quick start

Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Spec-driven testing (plan → generate → heal)

For BlockNote repository tests, use [testing-skill](../../testing-skill/SKILL.md) and its [accessibility conventions](../../testing-skill/references/accessibility-tests.md). The generic runner setup and one-test-per-file instructions here do not apply to BlockNote's Vitest browser suite.
For BlockNote repository tests, use [testing-skill](../../testing-skill/SKILL.md) and its [React component testing conventions](../../testing-skill/references/component-testing.md). The generic runner setup and one-test-per-file instructions here do not apply to BlockNote's Vitest browser suite.

End-to-end workflow for authoring and maintaining Playwright tests using `playwright-cli`. The three sections below can be used independently:

Expand Down
123 changes: 63 additions & 60 deletions .claude/skills/testing-skill/SKILL.md

Large diffs are not rendered by default.

79 changes: 0 additions & 79 deletions .claude/skills/testing-skill/references/accessibility-tests.md

This file was deleted.

68 changes: 68 additions & 0 deletions .claude/skills/testing-skill/references/component-testing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# React component testing

Use a browser for rendered component interactions, actual keyboard traversal/focus, or other rendering-dependent behavior. Test editor keyboard shortcut handlers in Node/jsdom: set state and selection with editor APIs, then dispatch the event. This avoids brittle layout-dependent navigation; use a browser only when browser behavior is the contract. A shared shortcut-event helper is planned.

## Component structure

Keep behavior and accessibility in one colocated `<Owner>.browser.test.{ts,tsx}` file. Use an owner-named outer `describe`, then applicable groups in order:

| Group | Assert |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `unit` | The owner's decisions: visibility, schema support, composition, callbacks. |
| `integration` | Subsystems working together: an actual control updates the editor correctly. |
| `keyboard` | Activation, traversal, dismissal, focus destination, visible focus. |
| `a11y` | Names, roles, relationships, pressed/expanded/checked state; axe scans in relevant states, including open menus/dialogs. |

Cover relevant categories reasonably, not every possible combination. A child owns its interaction and focus indicator; a container owns composition, traversal, and exit. ARIA assertions and axe scans share `a11y`.

## Setup

Destructure typed helpers from the test context. Find the current listing in [`tests/src/commands/index.ts`](../../../../tests/src/commands/index.ts) and usage documentation beside each implementation. The browser setup supplies the extended global `it`.

```tsx
const { editor } = await setupEditor({
initialContent: [{ type: "paragraph", content: "Selected text" }],
props: { formattingToolbar: false },
children: <BasicTextStyleButton basicTextStyle="bold" />,
});
selectText(editor, "Selected text");
```

Render the component directly with unrelated default UI disabled, rather than navigating a parent merely to reach it. Use the actual control for the action under test; editor APIs may establish the initial state.

Use BlockNote APIs for that setup instead of equivalent ProseMirror operations. Do not access `editor._tiptapEditor`; use `editor.prosemirrorView` when necessary and prefer `editor.transact` over `editor.prosemirrorState` for reads and transactions. See the [editor setup rules](../SKILL.md#editor-setup) for block-to-node conversion.

Shared rendering handles StrictMode, initial commit, fonts, and cleanup. Wait for later selection-driven UI explicitly. Skin selection defaults to Mantine and loads lazily; loaded CSS remains, so prefer one skin per file.

Prefer accessible locators using dictionary labels. Direct focus is valid setup; use real Tab input when traversal is the contract. Wait for observable readiness: a menu can be visible before it receives focus.

Stop navigation as soon as its target is reached and bound repeated keypresses explicitly; fail with the target and limit rather than waiting for a test timeout. `focusUntil` also detects cycles, stalled focus, and document boundaries.

Browser and screen-reader files enforce focused-test, assertion, awaited-poll, floating-promise, command-import, accessible-locator, and explicit-sleep safeguards. The component examples additionally enforce the scoped structure and timer conventions; do not weaken the shared safeguards when extending those rules.

## Accessibility assertions

- Assert focus with `toHaveFocus()` and check each owned control's indicator independently.
- Scope accessible-state assertions to the control/popup. Use built-in `toMatchAriaInlineSnapshot` / `toMatchAriaSnapshot` for standalone trees.
- For container traversal, an ordered sequence of focused controls' trees can detect skipped controls or changed order. Assert that focus can leave the container without prescribing an unrelated next destination.
- Scan closed triggers and open UI as applicable. Assert returned axe `violations`; for known issues, match their precise violation/check shapes with an issue link so additional violations fail. Do not mark a whole axe journey `it.fails`.
- ARIA trees, axe, keyboard checks, and visual checks complement each other; none proves actual reader speech.

## Native screen readers

Use colocated `*.screen-reader.test.ts` for real speech/navigation that browser assertions cannot establish. `const { getTranscript, pressKey } = await setupScreenReader(locator)` starts a session with automatic cleanup, including on failure. The locator is optional when focus is already established. Use the session's `pressKey` to capture speech, not the ordinary keyboard fixture.

This operates the real desktop using VoiceOver/NVDA and GuidePup permissions. Run only as intentional native verification, outside browser CI:

```bash
vp run test:screen-reader FormattingToolbar.screen-reader.test.ts
```

Configuration: `tests/src/screen-reader/vite.config.screen-reader.ts`.

## Mobile and visual checks

- Mobile-emulated tests cover mobile-specific behavior, not duplicate desktop contracts. Do not use `screenshotFull` in Android-instance tests: its iframe resize drops touch emulation for subsequent tests.
- State the limit when emulation cannot reproduce the OS behavior. Real-device suite is parked on `mobile/emulator-layer` (PR #3034).
- Tall screenshots need `tests/src/utils/screenshotFull.ts`: ordinary iframe screenshots can silently clip below the fold; viewport resizing alone can scale the capture.
- Screenshot baselines are browser/Linux-specific. Update in Docker with `--update=true`. Changes within pixel tolerance may leave a stale baseline; remove the specific baseline first when a fresh capture is required.
3 changes: 2 additions & 1 deletion .vscode/settings.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@
"packages/website/docs/.vitepress": false,
"**/.*": false
},
"typescript.tsdk": "node_modules/typescript/lib",
"js/ts.experimental.useTsgo": true,
"js/ts.tsdk.path": "./node_modules/typescript",
"[xml]": {
"editor.defaultFormatter": "redhat.vscode-xml"
},
Expand Down

This file was deleted.

Loading
Loading