0
# Setup and Configuration
1

2
Manual setup and configuration functions for controlling the jest-canvas-mock behavior. Use these functions when you need fine-grained control over mock initialization or when working with custom test setups.
3

4
## Capabilities
5

6
### Setup Jest Canvas Mock
7

8
Manually initializes or reinitializes the canvas mock on a specified window object. This is useful when you need to reset mocks during testing or when working with custom window objects.
9

10
```javascript { .api }
11
/**
12
 * Sets up canvas mocking on the specified window object or global.window
13
 * @param window - Optional window object to mock, defaults to global.window
14
 */
15
function setupJestCanvasMock(window?: Window): void;
16
```
17

18
### Version Export
19

20
Access to the package version string for debugging and compatibility checks.
21

22
```javascript { .api }
23
/**
24
 * Package version string - useful for debugging and compatibility checks
25
 */
26
const ver: string;
27
```
28

29
**Usage Examples:**
30

31
```javascript
32
import { setupJestCanvasMock, ver } from 'jest-canvas-mock';
33

34
// Check package version
35
console.log('jest-canvas-mock version:', ver);
36

37
// Conditional behavior based on version
38
if (ver === '2.5.2') {
39
  // Version-specific setup
40
}
41

42
// Basic usage - uses global.window
43
setupJestCanvasMock();
44

45
// With custom window object
46
setupJestCanvasMock(customWindow);
47

48
// Common pattern - reset mocks before each test
49
beforeEach(() => {
50
  jest.resetAllMocks();
51
  setupJestCanvasMock();
52
});
53

54
// Setup after clearing Jest mocks
55
afterEach(() => {
56
  jest.clearAllMocks();
57
  setupJestCanvasMock();
58
});
59
```
60

61
## Automatic Setup Options
62

63
For most use cases, automatic setup via Jest configuration is recommended:
64

65
### Package.json Configuration
66

67
```json
68
{
69
  "jest": {
70
    "setupFiles": ["jest-canvas-mock"]
71
  }
72
}
73
```
74

75
### Multiple Setup Files
76

77
```json
78
{
79
  "jest": {
80
    "setupFiles": [
81
      "./__setups__/other.js",
82
      "jest-canvas-mock"
83
    ]
84
  }
85
}
86
```
87

88
### Custom Setup File
89

90
Create a setup file that imports jest-canvas-mock:
91

92
```javascript
93
// __setups__/canvas.js
94
import 'jest-canvas-mock';
95
// or
96
require('jest-canvas-mock');
97
```
98

99
Then reference it in package.json:
100

101
```json
102
{
103
  "jest": {
104
    "setupFiles": ["./__setups__/canvas.js"]
105
  }
106
}
107
```
108

109
## Mock Behavior
110

111
The setup function performs the following operations:
112

113
1. **Global API Mocking**: Adds mock implementations of canvas-related classes to the window object:
114
   - `Path2D`
115
   - `CanvasGradient`
116
   - `CanvasPattern`
117
   - `CanvasRenderingContext2D`
118
   - `DOMMatrix`
119
   - `ImageData`
120
   - `TextMetrics`
121
   - `ImageBitmap`
122
   - `createImageBitmap`
123

124
2. **HTMLCanvasElement Extension**: Overrides methods on `HTMLCanvasElement.prototype`:
125
   - `getContext()` - Returns mock 2D context
126
   - `toBlob()` - Mock implementation with proper error handling
127
   - `toDataURL()` - Returns mock data URL
128

129
3. **Jest Integration**: All mocked methods are Jest mock functions with full spy capabilities
130

131
## Environment Compatibility
132

133
The mock is designed to work in various Jest environments:
134

135
- **jsdom**: Full compatibility with jsdom environment
136
- **node**: Works in Node.js environment without browser APIs
137
- **Custom environments**: Compatible with custom Jest environments
138

139
## Error Handling
140

141
The setup process is robust and handles various edge cases:
142

143
- Existing mock functions are preserved and extended
144
- Multiple setup calls are safe and will not create conflicts
145
- Custom window objects are properly validated
146
- Fallback to global window when no window object is provided