Chart.js Test Utilities

Common errors

• TypeError: expect(...).toEqualImageData is not a function

  cause The Jasmine custom matcher provided by `chartjs-test-utils` has not been properly registered or imported into the test environment.
  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.

• Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.

  cause An asynchronous operation, such as `triggerMouseEvent` or `fixture.run`, was called without `await`, causing the test to complete before the async function resolved.
  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 () => { ... });`.

• ERROR in ./test/specs/my-test.js Module not found: Error: Can't resolve 'chartjs-test-utils' in ...

  cause The `chartjs-test-utils` package is not installed or incorrectly referenced in the project's `node_modules`.
  fix Run `npm install chartjs-test-utils` or `yarn add chartjs-test-utils` to ensure the package is correctly installed.

Warnings

• breaking 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.
  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.
• breaking 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.
  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)`.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Add `fixture.cleanup();` to your test suite's `afterEach` block to correctly reset the DOM state after each test.

Install

• npm install chartjs-test-utils npm
• yarn add chartjs-test-utils yarn
• pnpm add chartjs-test-utils pnpm

Imports

• fixture
  wrong:

  const fixture = require('chartjs-test-utils').fixture

  correct:

  import { fixture } from 'chartjs-test-utils'

  CommonJS `require` still works but ESM `import` is preferred in modern setups. Access methods like `fixture.run()`.
• triggerMouseEvent
  wrong:

  import triggerMouseEvent from 'chartjs-test-utils'

  correct:

  import { triggerMouseEvent } from 'chartjs-test-utils'

  This is a named export. Ensure it's awaited as it became async in v0.2.0.
• toEqualImageData

  import 'chartjs-test-utils'

  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.

Quickstart

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.

import { fixture, triggerMouseEvent } from 'chartjs-test-utils';
import { Chart } from 'chart.js';

describe('MyChart integration', () => {
  let chart, canvas, wrapper;

  // Add global matchers provided by chartjs-test-utils
  beforeAll(() => {
    // Assuming chartjs-test-utils is imported globally or its matchers are explicitly added
    // For this example, we'll assume a global setup or 'import "chartjs-test-utils"' handles it.
  });

  beforeEach(async () => {
    // fixture.run creates a new DOM environment for each test
    const result = await fixture.run('<canvas id="myChart" width="400" height="400"></canvas>');
    canvas = result.querySelector('#myChart');
    wrapper = result;

    chart = new Chart(canvas, {
      type: 'bar',
      data: {
        labels: ['Red', 'Blue', 'Yellow'],
        datasets: [{
          label: 'Votes',
          data: [12, 19, 3],
          backgroundColor: ['red', 'blue', 'yellow']
        }]
      },
      options: {
        responsive: false
      }
    });
  });

  afterEach(() => {
    if (chart) {
      chart.destroy();
    }
    fixture.cleanup(); // Cleans up the DOM environment
  });

  it('should render correctly', () => {
    // Use custom matcher to check image data. Requires a baseline image or pixel comparison logic.
    // expect(canvas).toEqualImageData('my-chart-baseline'); // Example usage with a baseline
    expect(chart.data.datasets[0].data[0]).toBe(12);
  });

  it('should trigger mouse events and update chart', async () => {
    // Simulate a mouse click on the canvas
    await triggerMouseEvent(canvas, 'mousemove', 100, 100); // Simulate hover
    await triggerMouseEvent(canvas, 'click', 100, 100); // Simulate click

    // In a real test, you'd assert changes caused by the event, e.g., tooltip visibility.
    // For demonstration, we just ensure the event can be triggered without error.
    expect(true).toBe(true);
  });
});