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