SurfSense/.cursor/skills/playwright-testing/canvas-and-webgl.md

# Canvas and WebGL Testing

> **When to use**: When your application renders content on `<canvas>` elements -- charts (Chart.js, D3), maps (Mapbox, Leaflet), games, image editors, WebGL visualizations, drawing tools, signature pads.
> **Prerequisites**: [core/assertions-and-waiting.md](assertions-and-waiting.md), [core/locators.md](locators.md)

## Quick Reference

```typescript
// Screenshot comparison — the primary strategy for canvas
await expect(page.locator('canvas#chart')).toHaveScreenshot('revenue-chart.png');

// Click at specific coordinates on canvas
await page.locator('canvas').click({ position: { x: 200, y: 150 } });

// Read canvas state via page.evaluate
const pixelColor = await page.evaluate(() => {
  const canvas = document.querySelector('canvas') as HTMLCanvasElement;
  const ctx = canvas.getContext('2d')!;
  const pixel = ctx.getImageData(100, 100, 1, 1).data;
  return { r: pixel[0], g: pixel[1], b: pixel[2], a: pixel[3] };
});
```

## Patterns

### Screenshot Comparison (Visual Regression)

**Use when**: Verifying the visual output of canvas-rendered content -- charts, graphs, maps, drawings. This is the most reliable approach because canvas pixels are not queryable via DOM.
**Avoid when**: The canvas content is dynamic on every render (animations, timestamps). Use threshold or mask options.

**TypeScript**
```typescript
import { test, expect } from '@playwright/test';

test('revenue chart renders correctly', async ({ page }) => {
  await page.goto('/dashboard');

  // Wait for the chart to finish rendering
  await expect(page.locator('canvas#revenue-chart')).toBeVisible();

  // Optionally wait for a loading indicator to disappear
  await expect(page.getByTestId('chart-loading')).toBeHidden();

  // Screenshot comparison against a baseline
  await expect(page.locator('canvas#revenue-chart')).toHaveScreenshot('revenue-chart.png', {
    maxDiffPixelRatio: 0.01,  // Allow 1% pixel difference for anti-aliasing
  });
});

test('chart updates after date range change', async ({ page }) => {
  await page.goto('/dashboard');

  // Change date range
  await page.getByRole('combobox', { name: 'Date range' }).selectOption('Last 30 days');

  // Wait for chart to re-render
  await expect(page.getByTestId('chart-loading')).toBeHidden();

  // Compare against a different baseline
  await expect(page.locator('canvas#revenue-chart')).toHaveScreenshot('revenue-chart-30d.png', {
    maxDiffPixelRatio: 0.01,
  });
});

test('mask dynamic areas in canvas screenshot', async ({ page }) => {
  await page.goto('/dashboard');

  await expect(page.locator('canvas#chart')).toHaveScreenshot('chart-stable.png', {
    // Mask the timestamp area that changes every render
    mask: [page.locator('.chart-timestamp')],
    maxDiffPixelRatio: 0.02,
  });
});
```

**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');

test('revenue chart renders correctly', async ({ page }) => {
  await page.goto('/dashboard');
  await expect(page.locator('canvas#revenue-chart')).toBeVisible();
  await expect(page.getByTestId('chart-loading')).toBeHidden();

  await expect(page.locator('canvas#revenue-chart')).toHaveScreenshot('revenue-chart.png', {
    maxDiffPixelRatio: 0.01,
  });
});

test('chart updates after date range change', async ({ page }) => {
  await page.goto('/dashboard');
  await page.getByRole('combobox', { name: 'Date range' }).selectOption('Last 30 days');
  await expect(page.getByTestId('chart-loading')).toBeHidden();

  await expect(page.locator('canvas#revenue-chart')).toHaveScreenshot('revenue-chart-30d.png', {
    maxDiffPixelRatio: 0.01,
  });
});
```

### Interacting with Canvas via Coordinates

**Use when**: Testing user interactions on canvas -- clicking chart data points, dragging on a drawing tool, selecting map regions.
**Avoid when**: The element has an accessible DOM overlay (many chart libraries render tooltips as HTML). Interact with the overlay instead.

**TypeScript**
```typescript
import { test, expect } from '@playwright/test';

test('click on chart data point shows tooltip', async ({ page }) => {
  await page.goto('/analytics');

  const canvas = page.locator('canvas#line-chart');
  await expect(canvas).toBeVisible();

  // Click at a specific coordinate on the canvas
  await canvas.click({ position: { x: 200, y: 100 } });

  // Tooltip appears as an HTML overlay (most chart libraries)
  await expect(page.getByTestId('chart-tooltip')).toContainText('Revenue: $12,400');
});

test('draw a line on the canvas', async ({ page }) => {
  await page.goto('/drawing-tool');

  const canvas = page.locator('canvas#drawing-area');

  // Simulate a drag to draw a line
  await canvas.hover({ position: { x: 50, y: 50 } });
  await page.mouse.down();
  await page.mouse.move(200, 200, { steps: 10 }); // Smooth drag
  await page.mouse.up();

  // Verify via screenshot
  await expect(canvas).toHaveScreenshot('drawn-line.png');
});

test('pinch-to-zoom on a map canvas', async ({ page }) => {
  await page.goto('/map');

  const canvas = page.locator('canvas#map');

  // Scroll to zoom (common in map libraries)
  await canvas.hover({ position: { x: 300, y: 300 } });
  await page.mouse.wheel(0, -500); // Scroll up = zoom in

  // Verify zoom level changed
  await expect(page.getByTestId('zoom-level')).toHaveText('Zoom: 12');
});
```

**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');

test('click on chart data point shows tooltip', async ({ page }) => {
  await page.goto('/analytics');

  const canvas = page.locator('canvas#line-chart');
  await expect(canvas).toBeVisible();

  await canvas.click({ position: { x: 200, y: 100 } });
  await expect(page.getByTestId('chart-tooltip')).toContainText('Revenue: $12,400');
});

test('draw a line on the canvas', async ({ page }) => {
  await page.goto('/drawing-tool');

  const canvas = page.locator('canvas#drawing-area');
  await canvas.hover({ position: { x: 50, y: 50 } });
  await page.mouse.down();
  await page.mouse.move(200, 200, { steps: 10 });
  await page.mouse.up();

  await expect(canvas).toHaveScreenshot('drawn-line.png');
});
```

### Canvas API Testing via `page.evaluate()`

**Use when**: You need to inspect canvas pixel data, read the rendering context state, or verify programmatic canvas operations.
**Avoid when**: A screenshot comparison is sufficient. Pixel-level assertions are brittle.

**TypeScript**
```typescript
import { test, expect } from '@playwright/test';

test('verify specific pixel color on canvas', async ({ page }) => {
  await page.goto('/color-picker');

  // Click the red swatch
  await page.getByRole('button', { name: 'Red' }).click();

  // Read the pixel color at the canvas center
  const color = await page.evaluate(() => {
    const canvas = document.querySelector('canvas#preview') as HTMLCanvasElement;
    const ctx = canvas.getContext('2d')!;
    const centerX = Math.floor(canvas.width / 2);
    const centerY = Math.floor(canvas.height / 2);
    const pixel = ctx.getImageData(centerX, centerY, 1, 1).data;
    return { r: pixel[0], g: pixel[1], b: pixel[2], a: pixel[3] };
  });

  expect(color.r).toBeGreaterThan(200); // Red channel high
  expect(color.g).toBeLessThan(50);     // Green channel low
  expect(color.b).toBeLessThan(50);     // Blue channel low
});

test('verify canvas dimensions match expected size', async ({ page }) => {
  await page.goto('/editor');

  const dimensions = await page.evaluate(() => {
    const canvas = document.querySelector('canvas#main') as HTMLCanvasElement;
    return { width: canvas.width, height: canvas.height };
  });

  expect(dimensions).toEqual({ width: 1920, height: 1080 });
});

test('canvas has content (is not blank)', async ({ page }) => {
  await page.goto('/chart');

  // Wait for rendering
  await expect(page.getByTestId('chart-loading')).toBeHidden();

  const isBlank = await page.evaluate(() => {
    const canvas = document.querySelector('canvas') as HTMLCanvasElement;
    const ctx = canvas.getContext('2d')!;
    const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
    // Check if all pixels are transparent (blank canvas)
    return imageData.data.every((value, index) => {
      return index % 4 === 3 ? value === 0 : true; // Check alpha channel
    });
  });

  expect(isBlank).toBe(false);
});
```

**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');

test('verify specific pixel color on canvas', async ({ page }) => {
  await page.goto('/color-picker');
  await page.getByRole('button', { name: 'Red' }).click();

  const color = await page.evaluate(() => {
    const canvas = document.querySelector('canvas#preview');
    const ctx = canvas.getContext('2d');
    const centerX = Math.floor(canvas.width / 2);
    const centerY = Math.floor(canvas.height / 2);
    const pixel = ctx.getImageData(centerX, centerY, 1, 1).data;
    return { r: pixel[0], g: pixel[1], b: pixel[2], a: pixel[3] };
  });

  expect(color.r).toBeGreaterThan(200);
  expect(color.g).toBeLessThan(50);
  expect(color.b).toBeLessThan(50);
});

test('canvas has content (is not blank)', async ({ page }) => {
  await page.goto('/chart');
  await expect(page.getByTestId('chart-loading')).toBeHidden();

  const isBlank = await page.evaluate(() => {
    const canvas = document.querySelector('canvas');
    const ctx = canvas.getContext('2d');
    const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
    return imageData.data.every((value, index) => {
      return index % 4 === 3 ? value === 0 : true;
    });
  });

  expect(isBlank).toBe(false);
});
```

### WebGL Rendering Verification

**Use when**: Your app uses WebGL for 3D visualizations, data plots, or games.
**Avoid when**: The canvas uses 2D context only.

WebGL canvas cannot be read with `getImageData` from a 2D context. Use `toDataURL()` or screenshot comparison.

**TypeScript**
```typescript
import { test, expect } from '@playwright/test';

test('WebGL scene renders a 3D model', async ({ page }) => {
  await page.goto('/3d-viewer');

  // Wait for WebGL to finish rendering
  await page.waitForFunction(() => {
    const canvas = document.querySelector('canvas#scene') as HTMLCanvasElement;
    const gl = canvas.getContext('webgl2') || canvas.getContext('webgl');
    return gl !== null;
  });

  // Give the renderer time to complete the first frame
  await expect(page.getByTestId('render-status')).toHaveText('Ready');

  // Screenshot comparison is the most reliable approach for WebGL
  await expect(page.locator('canvas#scene')).toHaveScreenshot('3d-model.png', {
    maxDiffPixelRatio: 0.02, // WebGL has more rendering variance
  });
});

test('WebGL canvas is not blank', async ({ page }) => {
  await page.goto('/3d-viewer');
  await expect(page.getByTestId('render-status')).toHaveText('Ready');

  // Check that the WebGL canvas has drawn something
  const hasContent = await page.evaluate(() => {
    const canvas = document.querySelector('canvas#scene') as HTMLCanvasElement;
    // Convert canvas to data URL and check it's not a blank image
    const dataUrl = canvas.toDataURL();
    // A blank canvas produces a very short data URL
    return dataUrl.length > 1000;
  });

  expect(hasContent).toBe(true);
});

test('rotate 3D model and verify new angle', async ({ page }) => {
  await page.goto('/3d-viewer');
  await expect(page.getByTestId('render-status')).toHaveText('Ready');

  // Take baseline screenshot
  const canvas = page.locator('canvas#scene');

  // Drag to rotate
  await canvas.hover({ position: { x: 300, y: 300 } });
  await page.mouse.down();
  await page.mouse.move(450, 300, { steps: 20 });
  await page.mouse.up();

  // Screenshot should differ from default angle
  await expect(canvas).toHaveScreenshot('3d-model-rotated.png', {
    maxDiffPixelRatio: 0.02,
  });
});
```

**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');

test('WebGL scene renders a 3D model', async ({ page }) => {
  await page.goto('/3d-viewer');

  await page.waitForFunction(() => {
    const canvas = document.querySelector('canvas#scene');
    const gl = canvas.getContext('webgl2') || canvas.getContext('webgl');
    return gl !== null;
  });

  await expect(page.getByTestId('render-status')).toHaveText('Ready');
  await expect(page.locator('canvas#scene')).toHaveScreenshot('3d-model.png', {
    maxDiffPixelRatio: 0.02,
  });
});

test('WebGL canvas is not blank', async ({ page }) => {
  await page.goto('/3d-viewer');
  await expect(page.getByTestId('render-status')).toHaveText('Ready');

  const hasContent = await page.evaluate(() => {
    const canvas = document.querySelector('canvas#scene');
    const dataUrl = canvas.toDataURL();
    return dataUrl.length > 1000;
  });

  expect(hasContent).toBe(true);
});
```

### Chart Library Testing Strategies

**Use when**: Testing Chart.js, D3, Recharts, Highcharts, or similar chart libraries.
**Avoid when**: Charts have full HTML/SVG DOM output (D3 with SVG). Use standard locators for SVG elements.

**TypeScript**
```typescript
import { test, expect } from '@playwright/test';

test('bar chart shows correct number of bars (SVG-based chart)', async ({ page }) => {
  await page.goto('/analytics');

  // SVG-based charts (D3, Recharts) render DOM elements — use locators
  const bars = page.locator('svg.chart rect.bar');
  await expect(bars).toHaveCount(12); // 12 months

  // Check a specific bar's aria-label or tooltip
  await bars.nth(0).hover();
  await expect(page.getByTestId('chart-tooltip')).toContainText('January: $8,200');
});

test('canvas-based chart displays data (Chart.js)', async ({ page }) => {
  await page.goto('/analytics');

  // Canvas charts — no DOM elements to query, use screenshot
  await expect(page.getByTestId('chart-loading')).toBeHidden();
  await expect(page.locator('canvas#monthly-chart')).toHaveScreenshot('monthly-chart.png');
});

test('chart legend toggles data series', async ({ page }) => {
  await page.goto('/analytics');

  // Click legend item (usually HTML, not canvas)
  await page.getByRole('button', { name: 'Revenue' }).click();

  // Revenue series hidden — chart should look different
  await expect(page.locator('canvas#chart')).toHaveScreenshot('chart-no-revenue.png');

  // Click again to re-enable
  await page.getByRole('button', { name: 'Revenue' }).click();
  await expect(page.locator('canvas#chart')).toHaveScreenshot('chart-with-revenue.png');
});

test('export chart as image', async ({ page }) => {
  await page.goto('/analytics');

  // Many chart libraries offer "download as PNG"
  const downloadPromise = page.waitForEvent('download');
  await page.getByRole('button', { name: 'Export as PNG' }).click();
  const download = await downloadPromise;

  expect(download.suggestedFilename()).toMatch(/chart.*\.png$/);
});
```

**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');

test('bar chart shows correct number of bars (SVG-based)', async ({ page }) => {
  await page.goto('/analytics');

  const bars = page.locator('svg.chart rect.bar');
  await expect(bars).toHaveCount(12);

  await bars.nth(0).hover();
  await expect(page.getByTestId('chart-tooltip')).toContainText('January: $8,200');
});

test('canvas-based chart displays data', async ({ page }) => {
  await page.goto('/analytics');
  await expect(page.getByTestId('chart-loading')).toBeHidden();
  await expect(page.locator('canvas#monthly-chart')).toHaveScreenshot('monthly-chart.png');
});
```

## Decision Guide

| Scenario | Best Approach | Why |
|---|---|---|
| Verify chart looks correct | `toHaveScreenshot()` on canvas element | Canvas pixels are not DOM; screenshot is the source of truth |
| Click a data point on chart | `canvas.click({ position: { x, y } })` | Canvas does not have clickable child elements |
| Verify canvas is not blank | `page.evaluate` + `getImageData` or `toDataURL` | Quick programmatic check without baseline image |
| Test SVG-based chart (D3) | Standard locators (`svg rect`, `svg path`) | SVG elements are in the DOM; use locator queries |
| Read specific pixel color | `page.evaluate` + `getImageData` | Direct access to pixel data |
| Test WebGL rendering | `toHaveScreenshot()` with higher `maxDiffPixelRatio` | WebGL has rendering variance; pixel assertions are unreliable |
| Test canvas drag/draw | `mouse.down()` + `mouse.move()` + `mouse.up()` | Simulates real drawing interactions |
| Chart tooltip after hover | `canvas.hover({ position })` then assert tooltip DOM | Tooltips are usually HTML overlays |

## Anti-Patterns

| Don't Do This | Problem | Do This Instead |
|---|---|---|
| `page.getByRole('button')` inside a canvas | Canvas content has no DOM elements | Use `canvas.click({ position })` for coordinates |
| Assert pixel colors with exact RGB values | Anti-aliasing and GPU differences cause 1-2 value variance | Use ranges (`toBeGreaterThan(200)`) or `toHaveScreenshot` |
| Skip `maxDiffPixelRatio` in canvas screenshots | Different GPUs and OS versions render slightly differently | Set `maxDiffPixelRatio: 0.01` to `0.02` |
| `waitForTimeout` to wait for chart render | Arbitrary; too slow or too fast | Wait for a loading indicator to disappear or use `waitForFunction` |
| Read WebGL pixels via 2D context `getImageData` | WebGL and 2D contexts are mutually exclusive on the same canvas | Use `canvas.toDataURL()` or screenshot comparison |
| Take full-page screenshots for canvas tests | Captures unrelated content; more brittle baselines | Scope screenshot to `page.locator('canvas#specific')` |

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| Screenshot baseline always differs | GPU rendering differences across CI and local machine | Use Docker with consistent GPU settings, or increase `maxDiffPixelRatio` |
| Canvas click at coordinates hits wrong element | Coordinates are relative to element, but viewport changed | Use `position` relative to the canvas element, not the page |
| `getImageData` returns all transparent pixels | Canvas has not finished rendering when evaluated | Wait for a render-complete signal or use `waitForFunction` |
| `toDataURL` throws `SecurityError` | Canvas is tainted by cross-origin image | Serve images from the same origin or use CORS headers |
| WebGL context is null | Browser does not support WebGL or it is disabled in CI | Use `--enable-webgl` flag or run tests on a GPU-capable CI runner |
| Screenshot test passes locally, fails in CI | Different font rendering, DPI, or OS | Pin the Docker image, use `fonts` config, or increase threshold |

## Related

- [core/assertions-and-waiting.md](assertions-and-waiting.md) -- auto-retrying assertions and visual comparison options
- [core/configuration.md](configuration.md) -- configure screenshot thresholds and update baselines
- [core/iframes-and-shadow-dom.md](iframes-and-shadow-dom.md) -- canvas elements inside iframes
- [core/debugging.md](debugging.md) -- debugging visual regression failures with trace viewer