Setup and Configuration

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.

Capabilities

Setup Jest Canvas Mock

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.

/**
 * Sets up canvas mocking on the specified window object or global.window
 * @param window - Optional window object to mock, defaults to global.window
 */
function setupJestCanvasMock(window?: Window): void;

Version Export

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

/**
 * Package version string - useful for debugging and compatibility checks
 */
const ver: string;

Usage Examples:

import { setupJestCanvasMock, ver } from 'jest-canvas-mock';

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

// Conditional behavior based on version
if (ver === '2.5.2') {
  // Version-specific setup
}

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

// With custom window object
setupJestCanvasMock(customWindow);

// Common pattern - reset mocks before each test
beforeEach(() => {
  jest.resetAllMocks();
  setupJestCanvasMock();
});

// Setup after clearing Jest mocks
afterEach(() => {
  jest.clearAllMocks();
  setupJestCanvasMock();
});

Automatic Setup Options

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

Package.json Configuration

{
  "jest": {
    "setupFiles": ["jest-canvas-mock"]
  }
}

Multiple Setup Files

{
  "jest": {
    "setupFiles": [
      "./__setups__/other.js",
      "jest-canvas-mock"
    ]
  }
}

Custom Setup File

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

// __setups__/canvas.js
import 'jest-canvas-mock';
// or
require('jest-canvas-mock');

Then reference it in package.json:

{
  "jest": {
    "setupFiles": ["./__setups__/canvas.js"]
  }
}

Mock Behavior

The setup function performs the following operations:

1. Global API Mocking: Adds mock implementations of canvas-related classes to the window object:

   • Path2D
   • CanvasGradient
   • CanvasPattern
   • CanvasRenderingContext2D
   • DOMMatrix
   • ImageData
   • TextMetrics
   • ImageBitmap
   • createImageBitmap

2. HTMLCanvasElement Extension: Overrides methods on HTMLCanvasElement.prototype:

   • getContext() - Returns mock 2D context
   • toBlob() - Mock implementation with proper error handling
   • toDataURL() - Returns mock data URL

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

Environment Compatibility

The mock is designed to work in various Jest environments:

• jsdom: Full compatibility with jsdom environment
• node: Works in Node.js environment without browser APIs
• Custom environments: Compatible with custom Jest environments

Error Handling

The setup process is robust and handles various edge cases:

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