Test workflows in gitbook-x

An overview of the different types of tests we have and how you can run them.

💻 Browser tests

End-to-end browser tests are simulations of real user workflows like authentication, content editing, and collaboration.

• uses Playwright with Docker for consistent cross-environment testing

• integrates with Argos CI for visual regression screenshots (as seen in PR CI's)

Make sure you don't have the app running locally before starting

1

Start Docker

• Open the Docker app, then run:

docker compose up

• Leave this process running in the background

2

Generate tests

In a new terminal, run:

pnpm generate-tests

Only once that's finished, continue.

3

Start test server

In a new terminal:

pnpm --filter @tests/playwright test:run-test-server

Leave this running (serves on :5000).

4

Run tests

In a new terminal, you can either cd into the /packages/tests/playwright folder, or you can run it from the root gitbook-x repository and use --filter.

The latter is used below:

## Run all browser tests
pnpm --filter @tests/playwright test:browser

## Run a specific suite of tests
pnpm --filter @tests/playwright test:browser specs/blocks/content.spec.ts

## Add --headed to watch along how Playwright executes the tests in a browser
pnpm --filter @tests/playwright test:browser --headed --debug

## Add --debug to also allow debugging at every step of the code
pnpm --filter @tests/playwright test:browser --headed --debug

5

View Report

This will give you the report of all tests incl. any screenshots.

pnpm --filter @tests/playwright exec playwright show-report

You may need to run pnpm exec playwright install if Playwright browsers aren't set up.

---

📃 Tests in `doc-core`

These are unit tests for the core document schema and manipulation library. Uses fixture-driven testing to cover:

• document block types (images, tables, code, headings)

• document diffing algorithms

• three-way merge operations and conflict resolution

1

Navigate to package

cd packages/doc-core

2

Run tests

# Run all tests
pnpm run test

# Run only image tests
pnpm run test images

# Run a specific test file with verbose output
pnpm run test schema.tsx -- --reporter=verbose

---

📝 Tests in `doc-format`

Doc-format (and its tests) makes sure we can import and export documents without breaking them. It tests converting to/from Markdown and HTML using hundreds of example/mocked documents.

In doc-format, you need to NODE_ENV=test infront of the runners (see snippets below)

1

Navigate to package

Either navigate to the package:

cd packages/doc-format

Or use the --filter approach from root:

pnpm --filter @gitbook/doc-format ...

2

Run tests

# Run all spec tests
NODE_ENV=test pnpm run test "spec.test.ts"

# Run tests matching a pattern
NODE_ENV=test pnpm run test "spec.test.ts" -t "^updates"

# Run a specific test case
NODE_ENV=test pnpm run test -- spec.test.ts -t heading-offset-cases

# Run tests for a specific fixture folder
NODE_ENV=test pnpm run test -- src/tests/spec.test.ts --testNamePattern badge-inline

---

🌐 Running tests in react-app

In the react app (frontend) we mainly have component and utility tests for the web editor UI, testing:

• text formatting

• syntax highlighting

• block interactions (e.g. on tables, columns, steppers etc)

• link generation

• and more

1

Navigate to package

cd packages/react-app

2

Run tests

If you want to run all tests within react-app, run:

pnpm run test

But more likely you'll want to select a test file, then just run:

pnpm run test src/Components/ContentEditor/common/layout/__tests__/heights.nem.tsx

Tip: right-click the test file in your IDE (e.g. VSCode, Cursor) and copy the path

Extra info on test runners

Most packages are migrated over from Jest to Vitest

Package	Command	Runner
doc-core	pnpm run test	Vitest
doc-format	NODE_ENV=test pnpm run test	Vitest
react-app	pnpm run test	Vitest
hive-core	pnpm run test	Vitest
playwright	pnpm test:browser	Playwright

Note about running tests from root

You can run most package tests from root using --filter:

pnpm --filter @gitbook/doc-core test
pnpm --filter @gitbook/react-app test