{"id":15569,"library":"chartjs-test-utils","title":"Chart.js Test Utilities","description":"chartjs-test-utils is a dedicated utility package designed to simplify and standardize the testing of Chart.js applications and plugins. It provides specialized tools such as fixture management for rendering charts in isolated DOM environments, mock contexts to control canvas behavior, and custom Jasmine matchers like `toEqualImageData` and `toEqualOptions` for asserting chart rendering and configuration. The package is currently at v0.5.0, with releases typically driven by dependency updates or minor feature enhancements rather than a strict schedule. Its primary differentiator is its deep integration with Chart.js's internal rendering and configuration, making it indispensable for maintaining visual and functional correctness across Chart.js ecosystem projects, particularly when used with Karma and Jasmine.","status":"active","version":"0.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/chartjs/chartjs-test-utils","tags":["javascript","chart.js","karma","jasmine","fixture","test","utils"],"install":[{"cmd":"npm install chartjs-test-utils","lang":"bash","label":"npm"},{"cmd":"yarn add chartjs-test-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add chartjs-test-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the test framework, especially for custom matchers.","package":"jasmine","optional":false},{"reason":"Provides the test runner environment, which this package is designed to integrate with.","package":"karma","optional":false},{"reason":"Integrates Jasmine with the Karma test runner.","package":"karma-jasmine","optional":false}],"imports":[{"note":"CommonJS `require` still works but ESM `import` is preferred in modern setups. Access methods like `fixture.run()`.","wrong":"const fixture = require('chartjs-test-utils').fixture","symbol":"fixture","correct":"import { fixture } from 'chartjs-test-utils'"},{"note":"This is a named export. Ensure it's awaited as it became async in v0.2.0.","wrong":"import triggerMouseEvent from 'chartjs-test-utils'","symbol":"triggerMouseEvent","correct":"import { triggerMouseEvent } from 'chartjs-test-utils'"},{"note":"Custom Jasmine matchers like `toEqualImageData` and `toEqualOptions` are typically added to Jasmine's `expect` globally upon import/require of the package, rather than being imported as named functions. This assumes a test environment where the package is initialized before tests run.","symbol":"toEqualImageData","correct":"import 'chartjs-test-utils'"}],"quickstart":{"code":"import { fixture, triggerMouseEvent } from 'chartjs-test-utils';\nimport { Chart } from 'chart.js';\n\ndescribe('MyChart integration', () => {\n  let chart, canvas, wrapper;\n\n  // Add global matchers provided by chartjs-test-utils\n  beforeAll(() => {\n    // Assuming chartjs-test-utils is imported globally or its matchers are explicitly added\n    // For this example, we'll assume a global setup or 'import \"chartjs-test-utils\"' handles it.\n  });\n\n  beforeEach(async () => {\n    // fixture.run creates a new DOM environment for each test\n    const result = await fixture.run('<canvas id=\"myChart\" width=\"400\" height=\"400\"></canvas>');\n    canvas = result.querySelector('#myChart');\n    wrapper = result;\n\n    chart = new Chart(canvas, {\n      type: 'bar',\n      data: {\n        labels: ['Red', 'Blue', 'Yellow'],\n        datasets: [{\n          label: 'Votes',\n          data: [12, 19, 3],\n          backgroundColor: ['red', 'blue', 'yellow']\n        }]\n      },\n      options: {\n        responsive: false\n      }\n    });\n  });\n\n  afterEach(() => {\n    if (chart) {\n      chart.destroy();\n    }\n    fixture.cleanup(); // Cleans up the DOM environment\n  });\n\n  it('should render correctly', () => {\n    // Use custom matcher to check image data. Requires a baseline image or pixel comparison logic.\n    // expect(canvas).toEqualImageData('my-chart-baseline'); // Example usage with a baseline\n    expect(chart.data.datasets[0].data[0]).toBe(12);\n  });\n\n  it('should trigger mouse events and update chart', async () => {\n    // Simulate a mouse click on the canvas\n    await triggerMouseEvent(canvas, 'mousemove', 100, 100); // Simulate hover\n    await triggerMouseEvent(canvas, 'click', 100, 100); // Simulate click\n\n    // In a real test, you'd assert changes caused by the event, e.g., tooltip visibility.\n    // For demonstration, we just ensure the event can be triggered without error.\n    expect(true).toBe(true);\n  });\n});","lang":"typescript","description":"Demonstrates setting up a basic Chart.js test using `fixture` to manage the DOM and `triggerMouseEvent` to simulate user interactions, within a Jasmine test suite."},"warnings":[{"fix":"Review existing `toEqualImageData` assertions and update expected baseline images or adjust chart dimensions to match new verification criteria. Ensure your charts render with consistent sizes.","message":"The `toEqualImageData` matcher was updated in v0.3.0 to include size verification, potentially causing tests to fail if chart dimensions changed or were previously not strictly checked.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Refactor tests to use `async/await` syntax when calling `triggerMouseEvent` and `fixture.run`. For example, change `fixture.run(element, cb)` to `await fixture.run(element)`.","message":"In v0.2.0, `triggerMouseEvent` became an asynchronous function and `fixture.run` was updated to return a Promise instead of using a callback. This change requires tests to use `await` with these functions.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Always ensure your project's `package.json` explicitly lists and installs compatible versions of `jasmine`, `karma`, and `karma-jasmine` as specified by `chartjs-test-utils`'s peer dependency requirements (e.g., `jasmine: >=3.0.0`, `karma: >=6.0.0`, `karma-jasmine: >=4.0.0`). Regularly check for updates and potential conflicts.","message":"This package relies heavily on peer dependencies (`jasmine`, `karma`, `karma-jasmine`). Mismatched or outdated versions of these peer dependencies can lead to runtime errors or unexpected behavior during test execution.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Add `fixture.cleanup();` to your test suite's `afterEach` block to correctly reset the DOM state after each test.","message":"When using `fixture.run()`, remember to call `fixture.cleanup()` in your `afterEach` or `afterAll` hooks to prevent DOM contamination between tests and ensure isolated environments.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `chartjs-test-utils` is imported or required in a way that allows its matchers to be registered, typically by including `import 'chartjs-test-utils'` at the top of your test file or through a global setup in Karma/Jasmine.","cause":"The Jasmine custom matcher provided by `chartjs-test-utils` has not been properly registered or imported into the test environment.","error":"TypeError: expect(...).toEqualImageData is not a function"},{"fix":"Prepend `await` to calls to `triggerMouseEvent` and `fixture.run`. If the test function itself is not `async`, change its declaration to `it('should do something', async () => { ... });`.","cause":"An asynchronous operation, such as `triggerMouseEvent` or `fixture.run`, was called without `await`, causing the test to complete before the async function resolved.","error":"Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL."},{"fix":"Run `npm install chartjs-test-utils` or `yarn add chartjs-test-utils` to ensure the package is correctly installed.","cause":"The `chartjs-test-utils` package is not installed or incorrectly referenced in the project's `node_modules`.","error":"ERROR in ./test/specs/my-test.js Module not found: Error: Can't resolve 'chartjs-test-utils' in ..."}],"ecosystem":"npm"}