Ckeditor5 Testing

CKEditor 5 testing (Trilium)

Testing CKEditor 5 plugins in the Trilium (TriliumNext Notes) monorepo. Nearly everything lives in one package, packages/ckeditor5, with tests co-located as *.spec.ts next to the source — including every plugin under src/plugins/. It gates src/** at 100% coverage on all four metrics, so every code change must ship with a test.

Scope & sources

This skill covers testing CKEditor 5 plugins in the Trilium (TriliumNext Notes) monorepo (packages/ckeditor5). The CKEditor 5 library is 48 or later. For general (non-CKEditor) Trilium testing, see the writing-unit-tests skill.

On versions: these skills name major versions only ("48 or later"). Trilium tracks CKEditor 5 closely, so an exact pin written here would be stale within weeks — read the current one from packages/ckeditor5/package.json.

When to use this skill

Adding/reviewing unit tests for a plugin, debugging a failing test, or configuring a package's runner. For writing the feature itself, use the ckeditor5-plugin-development skill. For general Trilium testing (Preact components, jQuery widgets, server routes), use writing-unit-tests.

The current setup at a glance

• Runner: Vitest 4 or later. No shared factory — each package has its own vitest.config.ts built with defineConfig directly.
• One environment: Playwright browser mode (@vitest/browser-playwright, headless Chromium), used by ckeditor5. Real DOM and real layout, so getBoundingClientRect(), elementFromPoint() and pointer events behave as in a browser. Gates src/** coverage at 100% (lines/functions/branches/statements).
  • Trilium used to run some plugins on happy-dom; that is gone. If you are porting an old test, note the two differences that bite: happy-dom returned zeros from layout APIs (so measurement-dependent code silently "passed"), and it fired some DOM events synchronously where a real browser defers them — <details> fires toggle on a later task, for one. Synthetic events also need cancelable: true before preventDefault() means anything.
• Real editor, no test-editor factories. Tests create a real ClassicEditor against a real DOM element (see below). There is no ModelTestEditor/VirtualTestEditor/ClassicTestEditor in Trilium — those live only in the upstream ckeditor5 monorepo's tests/_utils.
• Helpers from 'ckeditor5': _setModelData, _getModelData, _getViewData are imported from the ckeditor5 package.
• Test-file location: co-located *.spec.ts next to the source, including inside plugin folders (src/plugins/<name>/<name>.spec.ts), with vitest include: ['src/**/*.spec.ts']. globals: true. Coverage provider v8, include: src/** (test files themselves excluded from coverage). The aggregate keeps allowExternal: false so an imported sibling package cannot bleed into its report (see references/running-and-config.md).
• Imports from 'ckeditor5'; in-package source imports use a file extension.
• License key: tests pass licenseKey: 'GPL' in the editor config.
• Every plugin folded into the aggregate carries its own tests, and the 100% gate keeps it that way. Unreachable code is the usual reason the gate cannot be met — see references/test-conventions.md for how Trilium handles it.

Running tests

pnpm --filter @triliumnext/ckeditor5 test     # the whole suite (from anywhere)
# or, from the package dir:
vitest run

Debug a browser-mode package with a visible browser:

vitest --inspect-brk --no-file-parallelism --browser.headless=false

Root orchestration — what CI runs, not what you run. pnpm test:parallel runs the light packages in parallel; pnpm test:sequential runs ckeditor5 sequentially (browser resource limits), alongside the server. pnpm test:all runs both. All three take minutes; during development run a filtered package suite instead (pnpm --filter @triliumnext/ckeditor5 test <pattern>), and leave the aggregates to CI. Each package exposes "test": "vitest" and "test:debug": "vitest --inspect-brk --no-file-parallelism --browser.headless=false".

Playwright downloads its own Chromium on demand; install it once with pnpm exec playwright install chromium from the repo root.

When that build cannot run — on NixOS it is linked against libraries no store path provides and dies on a missing libxcb.so.1 — point the suite at a system browser instead:

CHROME_BIN=/path/to/chromium pnpm --filter @triliumnext/ckeditor5 test

CHROME_BIN is read by the package's vitest.config.ts and passed to the provider as launchOptions.executablePath. nix develop sets it from pkgs.chromium, so inside the dev shell the plain command works — don't write a local override config.

Failed browser tests dump PNGs into a gitignored __screenshots__ beside the spec; delete them afterwards.

Anatomy of a test

In the aggregate (packages/ckeditor5), use the shared editor kit — createTestEditor() from test/editor-kit.ts builds a real ClassicEditor (licenseKey: 'GPL', auto-tracked) and the global afterEach in test/setup.ts (wired via setupFiles) destroys every tracked editor, so specs don't write their own editor-teardown afterEach:

import { ClassicEditor, Essentials, Paragraph, _setModelData } from 'ckeditor5';
import { describe, it, expect, beforeEach } from 'vitest';

import { createTestEditor } from '../../test/editor-kit.js';
import MyPlugin from './myplugin.js';

describe( 'MyPlugin', () => {
	let editor: ClassicEditor;

	beforeEach( async () => {
		editor = await createTestEditor( [ Essentials, Paragraph, MyPlugin ] );
	} );

	it( 'loads the plugin', () => {
		expect( editor.plugins.get( MyPlugin ) ).toBeInstanceOf( MyPlugin );
	} );

	it( 'keeps the selection in a paragraph', () => {
		_setModelData( editor.model, '<paragraph>foo[]bar</paragraph>' );
		expect( editor.model.document.getRoot().getChild( 0 ).name ).toBe( 'paragraph' );
	} );
} );

Need the host element? It's editor.sourceElement (or getEditorElement( editor ) from the kit). Some legacy specs still hand-roll the create/destroy scaffold (document.createElement('div') + ClassicEditor.create(...) + a teardown afterEach) — those are being migrated to createTestEditor.

Conventions visible here and across the suite:

• One top-level describe named after the unit, nested describes for areas (isEnabled, execute(), …), small focused its.
• Create the editor in beforeEach (return the Promise or use async/await — Vitest awaits it).
• Pass licenseKey: 'GPL' (the kit does this for you). List only the plugins the test needs (commands can also be instantiated directly, e.g. new InsertMermaidCommand( editor )).