write-unit-tests

Writing tests

Unit and integration tests use Vitest. Tests run from workspace directories, not the repo root.

Test file locations

Unit tests - alongside source files:

packages/editor/src/lib/primitives/Vec.ts
packages/editor/src/lib/primitives/Vec.test.ts  # Same directory

Integration tests - in src/test/ directory:

packages/tldraw/src/test/SelectTool.test.ts
packages/tldraw/src/test/commands/createShape.test.ts

Shape/tool tests - alongside the implementation:

packages/tldraw/src/lib/shapes/arrow/ArrowShapeUtil.test.ts
packages/tldraw/src/lib/shapes/arrow/ArrowShapeTool.test.ts

Which workspace to test in

• packages/editor: Core primitives, geometry, managers, base editor functionality
• packages/tldraw: Anything needing default shapes/tools (most integration tests)

cd packages/tldraw && yarn test run
cd packages/tldraw && yarn test run --grep "SelectTool"

TestEditor vs Editor

Use TestEditor for integration tests (includes default shapes/tools):

import { createShapeId } from '@tldraw/editor'
import { TestEditor } from './TestEditor'

let editor: TestEditor

beforeEach(() => {
	editor = new TestEditor()
	editor.selectAll().deleteShapes(editor.getSelectedShapeIds())
})

afterEach(() => {
	editor?.dispose()
})

Use raw Editor when testing editor setup or custom configurations:

import { Editor, createTLStore } from '@tldraw/editor'

beforeEach(() => {
	editor = new Editor({
		shapeUtils: [CustomShape],
		bindingUtils: [],
		tools: [CustomTool],
		store: createTLStore({ shapeUtils: [CustomShape], bindingUtils: [] }),
		getContainer: () => document.body,
	})
})

Common TestEditor methods

// Pointer simulation
editor.pointerDown(x, y, options?)
editor.pointerMove(x, y, options?)
editor.pointerUp(x, y, options?)
editor.click(x, y, shapeId?)
editor.doubleClick(x, y, shapeId?)

// Keyboard simulation
editor.keyDown(key, options?)
editor.keyUp(key, options?)

// State assertions
editor.expectToBeIn('select.idle')
editor.expectToBeIn('select.crop.idle')

// Shape assertions
editor.expectShapeToMatch({ id, x, y, props: { ... } })

// Shape operations
editor.createShapes([{ id, type, x, y, props }])
editor.updateShapes([{ id, type, props }])
editor.getShape(id)
editor.select(id1, id2)
editor.selectAll()
editor.selectNone()
editor.getSelectedShapeIds()
editor.getOnlySelectedShape()

// Tool operations
editor.setCurrentTool('arrow')
editor.getCurrentToolId()

// Undo/redo
editor.undo()
editor.redo()