0
# Jest Canvas Mock
1
2
Jest Canvas Mock is a comprehensive canvas mocking library designed specifically for Jest testing environments. It provides a complete mock implementation of the HTML5 Canvas API that enables developers to test canvas-dependent code without running in a browser. The library implements all standard canvas functions with proper parameter validation, error handling that matches browser behavior, and provides additional testing utilities for snapshot testing and test assertions.
3
4
## Package Information
5
6
- **Package Name**: jest-canvas-mock
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev jest-canvas-mock`
10
11
## Core Imports
12
13
```javascript
14
import 'jest-canvas-mock';
15
```
16
17
CommonJS:
18
19
```javascript
20
require('jest-canvas-mock');
21
```
22
23
For manual setup:
24
25
```javascript
26
import { setupJestCanvasMock } from 'jest-canvas-mock';
27
```
28
29
## Basic Usage
30
31
### Automatic Setup
32
33
Add to your `package.json` Jest configuration:
34
35
```json
36
{
37
"jest": {
38
"setupFiles": ["jest-canvas-mock"]
39
}
40
}
41
```
42
43
### Manual Setup
44
45
```javascript
46
import { setupJestCanvasMock } from 'jest-canvas-mock';
47
48
beforeEach(() => {
49
jest.resetAllMocks();
50
setupJestCanvasMock();
51
});
52
```
53
54
### Testing Canvas Operations
55
56
```javascript
57
// Create canvas element
58
const canvas = document.createElement('canvas');
59
const ctx = canvas.getContext('2d');
60
61
// Perform canvas operations
62
ctx.fillStyle = '#ff0000';
63
ctx.fillRect(10, 10, 100, 100);
64
ctx.strokeStyle = '#00ff00';
65
ctx.strokeRect(20, 20, 80, 80);
66
67
// Test with snapshots
68
expect(ctx.__getEvents()).toMatchSnapshot();
69
expect(ctx.__getDrawCalls()).toMatchSnapshot();
70
```
71
72
## Architecture
73
74
Jest Canvas Mock is built around several key components:
75
76
- **Canvas API Mock**: Complete implementation of CanvasRenderingContext2D with all standard methods and properties
77
- **Error Simulation**: Matches browser error behavior for invalid inputs (TypeError, DOMException, RangeError)
78
- **Event Tracking**: Records all canvas operations for testing and debugging
79
- **Draw Call Tracking**: Separates actual drawing operations from state changes
80
- **Path Tracking**: Monitors path construction and modification
81
- **Browser APIs**: Mocks related browser APIs like Path2D, ImageData, createImageBitmap
82
- **Jest Integration**: All methods are Jest mock functions with full spy capabilities
83
84
## Capabilities
85
86
### Setup and Configuration
87
88
Manual setup and configuration functions for controlling the mock behavior.
89
90
```javascript { .api }
91
function setupJestCanvasMock(window?: Window): void;
92
const ver: string;
93
```
94
95
[Setup and Configuration](./setup.md)
96
97
### Canvas Context Mock
98
99
Complete implementation of CanvasRenderingContext2D with all standard drawing methods, transformations, and properties. Includes comprehensive error handling that matches browser behavior.
100
101
```javascript { .api }
102
interface CanvasRenderingContext2D {
103
// Drawing methods
104
fillRect(x: number, y: number, width: number, height: number): void;
105
strokeRect(x: number, y: number, width: number, height: number): void;
106
clearRect(x: number, y: number, width: number, height: number): void;
107
108
// Path methods
109
beginPath(): void;
110
closePath(): void;
111
moveTo(x: number, y: number): void;
112
lineTo(x: number, y: number): void;
113
arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void;
114
115
// Fill and stroke
116
fill(fillRule?: CanvasFillRule): void;
117
fill(path: Path2D, fillRule?: CanvasFillRule): void;
118
stroke(): void;
119
stroke(path: Path2D): void;
120
121
// Text
122
fillText(text: string, x: number, y: number, maxWidth?: number): void;
123
strokeText(text: string, x: number, y: number, maxWidth?: number): void;
124
measureText(text: string): TextMetrics;
125
126
// Images
127
drawImage(image: CanvasImageSource, dx: number, dy: number): void;
128
drawImage(image: CanvasImageSource, dx: number, dy: number, dw: number, dh: number): void;
129
drawImage(image: CanvasImageSource, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void;
130
131
// Transformations
132
scale(x: number, y: number): void;
133
rotate(angle: number): void;
134
translate(x: number, y: number): void;
135
transform(a: number, b: number, c: number, d: number, e: number, f: number): void;
136
setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void;
137
setTransform(transform?: DOMMatrix2DInit): void;
138
resetTransform(): void;
139
140
// State
141
save(): void;
142
restore(): void;
143
144
// Properties (getters/setters)
145
fillStyle: string | CanvasGradient | CanvasPattern;
146
strokeStyle: string | CanvasGradient | CanvasPattern;
147
lineWidth: number;
148
font: string;
149
textAlign: CanvasTextAlign;
150
textBaseline: CanvasTextBaseline;
151
// ... many more properties
152
}
153
```
154
155
[Canvas Context Mock](./canvas-context.md)
156
157
### Test Utilities
158
159
Special testing methods added to CanvasRenderingContext2D for Jest testing. These methods track canvas operations and provide utilities for snapshot testing and assertions.
160
161
```javascript { .api }
162
interface CanvasRenderingContext2D {
163
__getEvents(): CanvasRenderingContext2DEvent[];
164
__clearEvents(): void;
165
__getDrawCalls(): CanvasRenderingContext2DEvent[];
166
__clearDrawCalls(): void;
167
__getPath(): CanvasRenderingContext2DEvent[];
168
__clearPath(): void;
169
__getClippingRegion(): CanvasRenderingContext2DEvent[];
170
}
171
172
interface CanvasRenderingContext2DEvent {
173
type: string;
174
transform: [number, number, number, number, number, number];
175
props: { [key: string]: any };
176
}
177
```
178
179
[Test Utilities](./test-utilities.md)
180
181
### Browser API Mocks
182
183
Mock implementations of browser APIs related to canvas functionality including Path2D, ImageData, TextMetrics, and other canvas-related classes.
184
185
```javascript { .api }
186
class Path2D {
187
constructor(path?: Path2D | string);
188
addPath(path: Path2D, transform?: DOMMatrix2DInit): void;
189
closePath(): void;
190
moveTo(x: number, y: number): void;
191
lineTo(x: number, y: number): void;
192
arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void;
193
// ... more path methods
194
}
195
196
class ImageData {
197
constructor(width: number, height: number);
198
constructor(data: Uint8ClampedArray, width: number, height?: number);
199
readonly width: number;
200
readonly height: number;
201
readonly data: Uint8ClampedArray;
202
}
203
204
function createImageBitmap(
205
image: ImageBitmapSource,
206
options?: ImageBitmapOptions
207
): Promise<ImageBitmap>;
208
209
function createImageBitmap(
210
image: ImageBitmapSource,
211
sx: number, sy: number, sw: number, sh: number,
212
options?: ImageBitmapOptions
213
): Promise<ImageBitmap>;
214
```
215
216
[Browser API Mocks](./browser-apis.md)
217
218
## Types
219
220
```javascript { .api }
221
type CanvasImageSource = HTMLImageElement | SVGImageElement | HTMLVideoElement | HTMLCanvasElement | ImageBitmap | OffscreenCanvas;
222
223
type CanvasFillRule = "nonzero" | "evenodd";
224
225
type CanvasTextAlign = "start" | "end" | "left" | "right" | "center";
226
227
type CanvasTextBaseline = "top" | "hanging" | "middle" | "alphabetic" | "ideographic" | "bottom";
228
229
interface ImageBitmapOptions {
230
imageOrientation?: "none" | "flipY";
231
premultiplyAlpha?: "none" | "premultiply" | "default";
232
colorSpaceConversion?: "none" | "default";
233
resizeWidth?: number;
234
resizeHeight?: number;
235
resizeQuality?: "pixelated" | "low" | "medium" | "high";
236
}
237
238
interface DOMMatrix2DInit {
239
a?: number;
240
b?: number;
241
c?: number;
242
d?: number;
243
e?: number;
244
f?: number;
245
m11?: number;
246
m12?: number;
247
m21?: number;
248
m22?: number;
249
m41?: number;
250
m42?: number;
251
}
252
```