---
category: framework-contributing
meta-title: Testing environment | CKEditor 5 Framework Documentation
meta-description: Test CKEditor 5 using the official testing environment. Run unit and manual tests effectively.
order: 30
modified_at: 2026-07-30
---
# Testing environment
The CKEditor 5 testing environment lets you run the project's automated (unit) and manual tests. This article explains how to run them.
Before reading this article we recommend getting familiar with the CKEditor 5 {@link framework/contributing/development-environment development environment}.
## Introduction
The CKEditor 5 testing environment uses [Vitest](https://vitest.dev/) running automated tests in real browsers (the [browser mode](https://vitest.dev/guide/browser/)), while manual tests are served by a [Vite](https://vite.dev/)-based server. We created some [npm scripts](https://docs.npmjs.com/cli/v11/using-npm/scripts) which glue all these pieces and special requirements for CKEditor together.
Each CKEditor 5 package has its own tests suite (see for example the [engine's tests](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-engine/tests)) together with its own Vitest configuration and `test` script. Automated tests are executed directly with [pnpm](https://pnpm.io/), without any custom test runner. The custom Vitest matchers are implemented in the [`@ckeditor/ckeditor5-dev-tests`](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-tests) package, and the Vite plugins powering the manual test server are implemented in the [`@ckeditor/ckeditor5-dev-manual-server`](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-manual-server) package. Both can be reused outside of `ckeditor5`.
Automated tests support TypeScript, and manual tests require it. Simply use the `.ts` extension.
## Running automated tests
Automated tests are executed with the packages' own `test` scripts, run directly via pnpm. There is no dedicated test runner binary.
The root `pnpm run test` script is a thin wrapper that translates a shorthand package selection into [pnpm filters](https://pnpm.io/filtering). It accepts the following options:
* `--filter` (alias `-f`) – Comma-separated short package names selecting the packages to test. Globs are allowed, for example `-f editor-*`.
* `--coverage` (alias `-c`) – Runs the `coverage` script of the selected packages instead of `test`.
* `--attempts` – The number of attempts for each package's test run. Failed runs are retried per package. It is meant for continuous integration environments and defaults to `1`.
All remaining arguments are passed to Vitest. Positional arguments are treated by Vitest as test file filters (they match a part of the test file path). You can also pass any other [Vitest CLI option](https://vitest.dev/guide/cli.html).
You can run the automated tests for the whole repository, a single package, a directory, or a single file:
| Scope |
Command |
| The whole repository |
pnpm run test (it sequentially runs the test script of every package) |
| A single package |
pnpm run test -f engine or natively: pnpm --filter ckeditor5-engine run test |
| Multiple packages |
pnpm run test -f editor-*,core |
| A directory inside a package |
pnpm run test -f engine tests/view |
| A single file |
pnpm run test -f basic-styles tests/bold.js |
Apart from the `test` and `coverage` scripts, each package provides the following scripts:
* `test:browser` – Runs the tests in a visible (non-headless) browser.
* `test:debug` – Runs the tests in a visible browser in the watch mode. Useful for debugging with the browser developer tools.
### Examples
Run all tests of the [`ckeditor5-core`](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-core/tests) package with the code coverage check:
```bash
pnpm run test -c -f core
```
Run the [engine's `view` namespace tests](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-engine/tests/view):
```bash
pnpm run test -f engine tests/view
```
Run and debug the `bold.js` tests in the [`ckeditor5-basic-styles`](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-basic-styles/tests) package in a visible browser:
```bash
pnpm --filter ckeditor5-basic-styles run test:debug tests/bold.js
```
### Custom Vitest matchers
The testing environment registers some custom [Vitest matchers](https://vitest.dev/guide/extending-matchers.html). There is no need to import them, as they are registered by default inside all tests.
#### `toEqualMarkup`
Tests whether two given strings containing markup language are equal. Unlike `expect().toEqual()`, this matcher formats the markup before showing a diff. It can be used to test HTML strings and strings containing a serialized model.
This assertion will pass:
```js
expect( `foo` ).toEqualMarkup( `foo` )
```
This assertion will throw an error:
```js
expect(
'foo bXXX[]r baz'
).toEqualMarkup(
'foo bYYY[]r baz'
);
```
## Running manual tests
To start the manual tests server, use the `pnpm run manual` task. It starts a [Vite](https://vite.dev/) development server available at [http://localhost:8125](http://localhost:8125).
The task accepts the standard [Vite CLI options](https://vite.dev/guide/cli.html), for example `--port`.
Debug flags are controlled with the `CK_DEBUG` environment variable. The base set of debug logs (`// @if CK_DEBUG //`) is always enabled. To uncomment additional debug code, pass a comma-separated list of flags, for example `CK_DEBUG=engine pnpm run manual` to enable the `// @if CK_DEBUG_ENGINE //` lines in the code.
### Creating a manual test
A manual test consists of 2 files:
* A `.manual.html` file – a complete HTML document (with the DOCTYPE, ``, and ``) that you fully own. You can freely add a Content Security Policy `` tag, external scripts, `