--- 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, `