Write Unit Tests Agent Skill

Writing unit and integration tests for the tldraw SDK. Use when creating new tests, adding test coverage, or fixing failing tests in packages/editor or packages/tldraw. Covers Vitest patterns, TestEditor usage, and test file organization.

2k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

49579

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/tldraw/tldraw --skill write-unit-tests

The instruction itself

24 sections, as written by the author

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()

Pointer event options

editor.pointerDown(100, 100, {
	target: 'shape', // 'canvas' | 'shape' | 'handle' | 'selection'
	shape: editor.getShape(id),
})

editor.pointerDown(150, 300, {
	target: 'selection',
	handle: 'bottom', // 'top' | 'bottom' | 'left' | 'right' | corners
})

editor.doubleClick(550, 550, {
	target: 'selection',
	handle: 'bottom_right',
})

Setup patterns

Standard setup with shape IDs

const ids = {
	box1: createShapeId('box1'),
	box2: createShapeId('box2'),
	arrow1: createShapeId('arrow1'),
}

vi.useFakeTimers()

beforeEach(() => {
	editor = new TestEditor()
	editor.selectAll().deleteShapes(editor.getSelectedShapeIds())
	editor.createShapes([
		{ id: ids.box1, type: 'geo', x: 100, y: 100, props: { w: 100, h: 100 } },
		{ id: ids.box2, type: 'geo', x: 300, y: 300, props: { w: 100, h: 100 } },
	])
})

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

Reusable props

const imageProps = {
	assetId: null,
	playing: true,
	url: '',
	w: 1200,
	h: 800,
}

editor.createShapes([
	{ id: ids.imageA, type: 'image', x: 100, y: 100, props: imageProps },
	{ id: ids.imageB, type: 'image', x: 500, y: 500, props: { ...imageProps, w: 600, h: 400 } },
])

Helper functions

function arrow(id = ids.arrow1) {
	return editor.getShape(id) as TLArrowShape
}

function bindings(id = ids.arrow1) {
	return getArrowBindings(editor, arrow(id))
}

Mocking with vi.spyOn

// Mock return value
vi.spyOn(editor, 'getIsReadonly').mockReturnValue(true)

// Mock implementation
const isHiddenSpy = vi.spyOn(editor, 'isShapeHidden')
isHiddenSpy.mockImplementation((shape) => shape.id === ids.hiddenShape)

// Verify calls
const spy = vi.spyOn(editor, 'setSelectedShapes')
editor.selectAll()
expect(spy).toHaveBeenCalled()
expect(spy).not.toHaveBeenCalled()

// Always restore
isHiddenSpy.mockRestore()

Fake timers

vi.useFakeTimers()

// Mock animation frame
window.requestAnimationFrame = (cb) => setTimeout(cb, 1000 / 60)
window.cancelAnimationFrame = (id) => clearTimeout(id)

it('handles animation', () => {
	editor.alignShapes(editor.getSelectedShapeIds(), 'right')
	vi.advanceTimersByTime(1000)
	// Assert after animation completes
})

Assertions

Shape matching

// Partial matching (most common)
expect(editor.getShape(id)).toMatchObject({
	type: 'geo',
	x: 100,
	props: { w: 100 },
})

editor.expectShapeToMatch({
	id: ids.box1,
	x: 350,
	y: 350,
})

// Floating point matching (custom matcher)
expect(result).toCloselyMatchObject({
	props: { normalizedAnchor: { x: 0.5, y: 0.75 } },
})

Array assertions

expect(editor.getSelectedShapeIds()).toMatchObject([ids.box1])
expect(Array.from(selectedIds).sort()).toEqual([id1, id2, id3].sort())
expect(shapes).toContain('geo')
expect(shapes).not.toContain(ids.lockedShape)

State assertions

editor.expectToBeIn('select.idle')
editor.expectToBeIn('select.brushing')
editor.expectToBeIn('select.crop.idle')

Testing undo/redo

it('handles undo/redo', () => {
	editor.doubleClick(550, 550, ids.image)
	editor.expectToBeIn('select.crop.idle')

	editor.updateShape({ id: ids.image, type: 'image', props: { crop: newCrop } })

	editor.undo()
	editor.expectToBeIn('select.crop.idle')
	expect(editor.getShape(ids.image)!.props.crop).toMatchObject(originalCrop)

	editor.redo()
	expect(editor.getShape(ids.image)!.props.crop).toMatchObject(newCrop)
})

Testing TypeScript types

it('Uses typescript generics', () => {
	expect(() => {
		// @ts-expect-error - wrong props type
		editor.createShape({ id, type: 'geo', props: { w: 'OH NO' } })

		// @ts-expect-error - unknown prop
		editor.createShape({ id, type: 'geo', props: { foo: 'bar' } })

		// Valid
		editor.createShape<TLGeoShape>({ id, type: 'geo', props: { w: 100 } })
	}).toThrow()
})

Testing custom shapes

declare module '@tldraw/tlschema' {
	export interface TLGlobalShapePropsMap {
		'my-custom-shape': { w: number; h: number; text: string | undefined }
	}
}

class CustomShape extends ShapeUtil<ICustomShape> {
	static override type = 'my-custom-shape'
	static override props: RecordProps<ICustomShape> = {
		w: T.number,
		h: T.number,
		text: T.string.optional(),
	}
	getDefaultProps() {
		return { w: 200, h: 200, text: '' }
	}
	getGeometry(shape) {
		return new Rectangle2d({ width: shape.props.w, height: shape.props.h })
	}
	indicator() {}
	component() {}
}

Testing side effects

beforeEach(() => {
	editor = new TestEditor()
	editor.sideEffects.registerAfterChangeHandler('instance_page_state', (prev, next) => {
		if (prev.croppingShapeId !== next.croppingShapeId) {
			// Handle state change
		}
	})
})

Testing events

it('emits wheel events', () => {
	const handler = vi.fn()
	editor.on('event', handler)

	editor.dispatch({
		type: 'wheel',
		name: 'wheel',
		delta: { x: 0, y: 10, z: 0 },
		point: { x: 100, y: 100, z: 1 },
		shiftKey: false,
		// ... other modifiers
	})
	editor.emit('tick', 16) // Flush batched events

	expect(handler).toHaveBeenCalledWith(expect.objectContaining({ name: 'wheel' }))
})

Method chaining

editor
	.expectToBeIn('select.idle')
	.select(ids.imageA, ids.imageB)
	.doubleClick(550, 550, { target: 'selection', handle: 'bottom_right' })
	.expectToBeIn('select.idle')

editor.setCurrentTool('arrow').pointerDown(0, 0).pointerMove(100, 100).pointerUp()

Running tests

cd packages/tldraw && yarn test run
cd packages/tldraw && yarn test run --grep "arrow"
cd packages/editor && yarn test run --grep "Vec"

# Watch mode
cd packages/tldraw && yarn test

Key patterns summary

Use createShapeId() for shape IDs
Use vi.useFakeTimers() for time-dependent behavior
Clear shapes in beforeEach, dispose in afterEach
Test in packages/tldraw for shapes/tools
Use expectToBeIn() for state machine assertions
Use toMatchObject() for partial matching
Use toCloselyMatchObject() for floating point values
Mock with vi.spyOn() and always mockRestore()

Other skills for the same job

different authors, same section of the catalogue

Webapp Testing

by anthropics

vendor ×12

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

6k tokens scripts

Finishing A Development Branch

by ZhanlinCui

×7

Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup

1k tokens

Test Driven Development

by w95

×7

Use when implementing any feature or bugfix, before writing implementation code

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

10k tokens scripts

Verification Before Completion

by ZhanlinCui

×6

Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always

Expert guidance for systematic backtesting of trading strategies. Use when developing, testing, stress-testing, or validating quantitative trading strategies. Covers "beating ideas to death" methodology, parameter robustness testing, slippage modeling, bias prevention, and interpreting backtest results. Applicable when user asks about backtesting, strategy validation, robustness testing, avoiding overfitting, or systematic trading development.

Cloud laboratory platform for automated protein testing and validation. Use when designing proteins and needing experimental validation including binding assays, expression testing, thermostability measurements, enzyme activity assays, or protein sequence optimization. Also use for submitting experiments via API, tracking experiment status, downloading results, optimizing protein sequences for better expression using computational tools (NetSolP, SoluProt, SolubleMPNN, ESM), or managing protein design workflows with wet-lab validation.

This skill should be used for time series machine learning tasks including classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search. Use when working with temporal data, sequential patterns, or time-indexed observations requiring specialized algorithms beyond standard ML approaches. Particularly suited for univariate and multivariate time series analysis with scikit-learn compatible APIs.

19k tokens

How to use it

Copy the folder

Take tldraw/write-unit-tests from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.