You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .claude/skills/debug-skill/SKILL.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
---
2
2
name: debug-skill
3
-
description: Instructions for navigating and debugging BlockNote in a browser. Shows how to open specific menus & toolbars, as well select content. Should be used when prompted to fix a bug.
3
+
description: Instructions for navigating and debugging BlockNote in a browser. Shows how to open specific menus & toolbars, as well select content. Should be used when prompted to fix a bug that requires inspecting the editor's appearance or rendered HTML.
4
4
---
5
5
6
6
# General loop
@@ -14,7 +14,7 @@ When fixing a bug, the following feedback loop should be used.
14
14
15
15
# Browser environment
16
16
17
-
Before starting up a browser environment, you need to ensure the dev server is running. This can be done by checking if port 5173 is in use. If it isn't, running `vp dev` at the project root will start the server.
17
+
Before starting up a browser environment, you need to ensure the dev server is running. This can be done by checking if port 5173 is in use. If it isn't, running `vp run dev` at the project root will start the server.
18
18
19
19
The Playwright CLI should be used for the browser environment. It can be used to navigate to the dev server and programmatically issue mouse clicks/keyboard inputs. If not installed, stop what you're doing and notify the user to install it.
description: Instructions for writing, running, and updating unit/end-to-end tests. Should be used when prompted specifically to add tests for a given feature, bug, or regression.
4
+
---
5
+
6
+
# Testing
7
+
8
+
In most cases, once a feature, bug fix, or other modification has been written, it will need to have tests added, or existing tests updated.
9
+
10
+
## Test File Locations
11
+
12
+
### Unit Tests
13
+
14
+
`/tests/src/unit`: Contains the bulk of unit tests, mainly relating to interoperability between BlockNote's JSON format and HTML/Markdown. Also includes some miscellaneous tests, like React rendering, selection handling, and NextJS integration.
15
+
16
+
`/packages/core/src/api`: Contains mainly tests for getting, inserting, updating, and removing blocks, etc, under `/blockManipulation/commands`. Also includes tests for intermediary functionality between BlockNote and the underlying TipTap editor, like converting between blocks & nodes, or setting editor event handlers.
17
+
18
+
`/packages/xl-*`: Contain tests for functionality included in a given `xl-*` package.
19
+
20
+
### End-to-End Tests
21
+
22
+
`tests/src/end-to-end`: Any test which interacts with the editor UI or simulates user interaction goes here. New subdirectories can be added if the functionality being tested is not covered by any of the existing ones. Important note about existing E2E tests - many are written poorly and should only loosely be used as reference. We want to avoid abstraction layers and `waitForTimeout` as much as possible.
23
+
24
+
## When & How to Add Tests
25
+
26
+
In general, we expect a change in code to result in failing test cases. If this does not happen, tests should be added and checked to ensure they pass with the code changes while failing without them.
27
+
28
+
However, this may not be true when adding edge case handling or a new feature, where existing tests may all continue to pass. In this case, tests should be added as necessary to cover all of the new functionality. We should still ensure that the new tests pass with the new code changes while failing without them.
29
+
30
+
We want to avoid adding end-to-end tests where it's possible to use unit tests instead.
31
+
32
+
## Running & Updating Tests
33
+
34
+
### Unit Tests
35
+
36
+
Unit tests can be run from the root directory using `vp run test`, which will run all of them across all directories. A specific test file may be targeted by appending its name, i.e. `vp run test fileName`. Individual tests in a file may be disabled using `skip`, i.e. `it.skip("Test name", ...)` (remember to revert this once all tests pass).
37
+
38
+
Updating tests can be done by adding the `-u` argument, i.e. `vp run test -u`. All of the other things you can do to scope which tests to target still apply.
39
+
40
+
### End-to-End Tests
41
+
42
+
End-to-end tests run inside a docker container. While its possible to run them outside of it, we do not have existing snapshots to compare results with, and the results sometimes differ to when they're run within Docker, so it's not worth doing.
43
+
44
+
To run end-to-end tests, you must first build the project and run the preview. You can do this by running `vp start` from the root directory.
45
+
46
+
You can then run the tests from the `/tests` directory using the following command:
47
+
48
+
```
49
+
docker run --rm -e RUN_IN_DOCKER=true --network host -v $(pwd)/..:/work/ -w /work/tests -it mcr.microsoft.com/playwright:v1.51.1-noble npx playwright test
50
+
```
51
+
52
+
A specific test file may be targeted by appending its name, i.e. `... npx playwright test fileName`. Individual tests in a file may be disabled using `skip`, i.e. `test.skip("Test name", ...)` (remember to revert this once all tests pass).
53
+
54
+
Updating tests can be done by adding the `-u` argument, i.e. `... npx playwright test -u`. All of the other things you can do to scope which tests to target still apply.
55
+
56
+
When testing a visual change, prefer writing screenshots to verify that the change is working as expected.
Copy file name to clipboardExpand all lines: AGENTS.md
+14-67Lines changed: 14 additions & 67 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,6 +12,20 @@ Once the task is done and the feature is completed, bug is fixed, etc, the user
12
12
13
13
The GitHub CLI should be used to browse issues and PRs.
14
14
15
+
# Common Commands
16
+
17
+
All commands below are listed under `package.json` in the project root. See `vite.config.ts` for relevant configuration settings.
18
+
19
+
-`vp install`: Installs dependencies.
20
+
-`vp run dev`: Starts the dev server on port 5173.
21
+
-`vp run check`: Checks for linting and formatting issues across the project and attempt resolve issues automatically.
22
+
-`vp run build`: Builds the project.
23
+
-`vp run preview`: Previews the build on port 3000.
24
+
-`vp run test`: Runs unit tests. Append with `-u` to update snapshots. Append with a file name to target only that file.
25
+
-`vp run e2e`: Runs end-to-end tests. Append with a file name to target only that file.
26
+
-`vp run e2e:updateSnaps`: Runs end-to-end tests & updates snapshots. Append with a file name to target only that file.
27
+
-`vp help`: Prints a list of all availabel commands.
28
+
15
29
# Common Entry Points
16
30
17
31
When writing a new feature, bug fix, or other modification, it may not be immediately clear where the code for it should be. There are a few files which are good to start looking in when this is the case:
@@ -21,73 +35,6 @@ When writing a new feature, bug fix, or other modification, it may not be immedi
21
35
-`/packages/mantine/src/BlockNoteView.tsx`: Contains the Mantine version of `BlockNoteView`. This can be thought of as a skin for `BlockNoteViewEditor` that uses the Mantine component library. Therefore, changes in `BlockNoteViewEditor` may also have to be propagted to it.
22
36
- The same applies for `BlockNoteView.tsx` in `/packages/ariakit` and `/packages/shadcn`, though Mantine is the defacto default version of `BlockNoteView`.
23
37
24
-
# Testing
25
-
26
-
In most cases, once a feature, bug fix, or other modification has been written, it will need to have tests added, or existing tests updated.
27
-
28
-
## Test File Locations
29
-
30
-
### Unit Tests
31
-
32
-
`/tests/src/unit`: Contains the bulk of unit tests, mainly relating to interoperability between BlockNote's JSON format and HTML/Markdown. Also includes some miscellaneous tests, like React rendering, selection handling, and NextJS integration.
33
-
34
-
`/packages/core/src/api`: Contains mainly tests for getting, inserting, updating, and removing blocks, etc, under `/blockManipulation/commands`. Also includes tests for intermediary functionality between BlockNote and the underlying TipTap editor, like converting between blocks & nodes, or setting editor event handlers.
35
-
36
-
`/packages/xl-*`: Contain tests for functionality included in a given `xl-*` package.
37
-
38
-
### End-to-End Tests
39
-
40
-
`tests/src/end-to-end`: Any test which interacts with the editor UI or simulates user interaction goes here. New subdirectories can be added if the functionality being tested is not covered by any of the existing ones. Important note about existing E2E tests - many are written poorly and should only loosely be used as reference. We want to avoid abstraction layers and `waitForTimeout` as much as possible.
41
-
42
-
## When & How to Add Tests
43
-
44
-
In general, we expect a change in code to result in failing test cases. If this does not happen, tests should be added and checked to ensure they pass with the code changes while failing without them.
45
-
46
-
However, this may not be true when adding edge case handling or a new feature, where existing tests may all continue to pass. In this case, tests should be added as necessary to cover all of the new functionality. We should still ensure that the new tests pass with the new code changes while failing without them.
47
-
48
-
We want to avoid adding end-to-end tests where it's possible to use unit tests instead.
49
-
50
-
## Running & Updating Tests
51
-
52
-
### Unit Tests
53
-
54
-
Unit tests can be run from the root directory using `vp run test`, which will run all of them across all directories. A specific test file may be targeted by appending its name, i.e. `vp run test fileName`. Individual tests in a file may be disabled using `skip`, i.e. `it.skip("Test name", ...)` (remember to revert this once all tests pass).
55
-
56
-
Updating tests can be done by adding the `-u` argument, i.e. `vp run test -u`. All of the other things you can do to scope which tests to target still apply.
57
-
58
-
### End-to-End Tests
59
-
60
-
End-to-end tests run inside a docker container. While its possible to run them outside of it, we do not have existing snapshots to compare results with, and the results sometimes differ to when they're run within Docker, so it's not worth doing.
61
-
62
-
To run end-to-end tests, you must first build the project and run the preview. You can do this by running `vp start` from the root directory.
63
-
64
-
You can then run the tests from the `/tests` directory using the following command:
65
-
66
-
```
67
-
docker run --rm -e RUN_IN_DOCKER=true --network host -v $(pwd)/..:/work/ -w /work/tests -it mcr.microsoft.com/playwright:v1.51.1-noble npx playwright test
68
-
```
69
-
70
-
A specific test file may be targeted by appending its name, i.e. `... npx playwright test fileName`. Individual tests in a file may be disabled using `skip`, i.e. `test.skip("Test name", ...)` (remember to revert this once all tests pass).
71
-
72
-
Updating tests can be done by adding the `-u` argument, i.e. `... npx playwright test -u`. All of the other things you can do to scope which tests to target still apply.
73
-
74
38
# Additional Notes
75
39
76
40
- Do not create git commits.
77
-
78
-
<!--VITE PLUS START-->
79
-
80
-
# Using Vite+, the Unified Toolchain for the Web
81
-
82
-
This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, and it invokes Vite through `vp dev` and `vp build`. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.
83
-
84
-
Docs are local at `node_modules/vite-plus/docs` or online at https://viteplus.dev/guide/.
85
-
86
-
## Review Checklist
87
-
88
-
-[ ] Run `vp install` after pulling remote changes and before getting started.
89
-
-[ ] Run `vp check` and `vp test` to format, lint, type check and test changes.
90
-
-[ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vp run <script>`.
91
-
-[ ] If setup, runtime, or package-manager behavior looks wrong, run `vp env doctor` and include its output when asking for help.
0 commit comments