Skip to content

Commit 3268a82

Browse files
committed
docs: slightly stricter rules
1 parent d4e6534 commit 3268a82

2 files changed

Lines changed: 23 additions & 2 deletions

File tree

‎.claude/skills/testing-skill/SKILL.md‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Test behavior beside its owner, at the lowest reasonable rung of the test ladder
1818
| 5. Mobile-emulated | `end-to-end/mobile/**`, Android browser instance; touch, viewport, emulated IME differences. |
1919
| 6. Real device | Only behavior emulation cannot establish; device suite is parked on `mobile/emulator-layer` (PR #3034). |
2020

21-
The ladder guides placement, not a requirement to try every environment. Use a real browser, not jsdom, for clicking, keyboard navigation, focus, or rendered component behavior. Editor/document logic stays in faster Node tests, where `setupEditor` mounts the core editor in jsdom. Rungs 2 and 3 distinguish ownership/location, not strictly runtime cost.
21+
The ladder guides placement, not a requirement to try every environment. Use a real browser for rendered component interactions, actual focus/traversal, and browser-dependent input behavior. Prefer Node/jsdom for editor keyboard shortcut handlers: establish editor state and selection directly, then dispatch a keyboard event, avoiding layout-dependent browser navigation. Editor/document logic also stays in faster Node tests, where `setupEditor` mounts the core editor in jsdom. Rungs 2 and 3 distinguish ownership/location, not strictly runtime cost.
2222

2323
Integrations verify boundaries, not repeat dependencies' tests. A parent assumes its children work: test toolbar composition/traversal at the toolbar, button activation at the button, and detailed document operations at their editor commands.
2424

@@ -27,6 +27,8 @@ Integrations verify boundaries, not repeat dependencies' tests. A parent assumes
2727
- **Cover user-important behavior and applicable categories**, not every branch or state combination. Low-value defensive branches need not be exercised merely for coverage.
2828
- **Reported bugs generally warrant regression tests.** Prove regressions red-first against the bug, then green with the fix. Follow TDD for new behavior; modifying existing tests does not require manufacturing another red run. Styling fixes may reasonably lack regression tests when automation is cumbersome or implementation-coupled.
2929
- **Use real internal dependencies.** Mock/fake only when necessary, such as external services. Observation-only spies are fine.
30+
- **Use public editor APIs.** Do not reach into `editor._tiptapEditor`. Use `editor.prosemirrorView` when the view is needed; prefer `editor.transact` for current document/selection reads and transactions over `editor.prosemirrorState`.
31+
- **Prefer BlockNote operations over ProseMirror equivalents.** Establish documents with `initialContent`, `insertBlocks`, `updateBlock`, and other BlockNote APIs rather than hand-building internal nodes or mutating transactions when an equivalent exists. Convert blocks to ProseMirror nodes only when the test needs them.
3032
- **Distinguish unit from integration by scope.** A function changing block color is a unit contract; clicking a button and checking the editor/UI color change crosses subsystems.
3133
- **Arrange → Act → Assert.** Name the outcome, establish the case, exercise the real entry point, and assert its relevant behavior. Repeated act/assert pairs are fine when clearer. Setup APIs must not perform the action the test claims to verify.
3234
- **Share understandable conventions.** Prefer `setupEditor` and common mechanics to bespoke setup. Abstract repeated patterns when they improve understanding. Choose inline cases versus `it.for` for readability, not minimum line count.
@@ -60,6 +62,23 @@ Use these as patterns, not templates to copy mechanically. For testing a React c
6062

6163
Use `const { editor } = await setupEditor({ ...editorOptions })` in either environment. Browser tests receive it from the shared fixture; it renders a view and additionally accepts `skin`, `props`, `children`, and `outside`, returning `rerender` too. Node tests import `test` from `tests/src/fixtures/editor.node.ts` and use the jsdom environment; their helper mounts the core editor without React or skin styles. Both preserve custom-schema types and clean up after the test. For headless logic, use `BlockNoteEditor.create` directly.
6264

65+
`insertBlocks` returns an array of inserted BlockNote blocks. The conversion to a ProseMirror node is `blockToNode`:
66+
67+
```ts
68+
import { blockToNode } from "@blocknote/core";
69+
70+
const [block] = editor.insertBlocks(
71+
[{ type: "paragraph", content: "Inserted text" }],
72+
"existing-block-id",
73+
"after",
74+
);
75+
const node = editor.transact((tr) =>
76+
blockToNode(block, tr.doc.type.schema, editor.schema.styleSchema),
77+
);
78+
```
79+
80+
For shortcut-handler tests, set up the desired state/selection with editor APIs, then simulate the keyboard event in jsdom. A shared event helper is planned; do not invent a browser navigation journey just to reach the shortcut's starting position. Use a browser when layout, native shortcut handling, or real focus movement is itself the contract.
81+
6382
## Run
6483

6584
Use `vite-plus/test` imports and repository commands:

‎.claude/skills/testing-skill/references/component-testing.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# React component testing
22

3-
Use a browser when testing clicks, keyboard navigation, focus, or other rendering-dependent behavior. Keep logic that does not need rendering in faster Node tests.
3+
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.
44

55
## Component structure
66

@@ -30,6 +30,8 @@ selectText(editor, "Selected text");
3030

3131
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.
3232

33+
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.
34+
3335
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.
3436

3537
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.

0 commit comments

Comments
 (0)