@assertrx/dino 1.0.0

package/skills/playwright-core/canvas-and-webgl.md

@@ -0,0 +1,494 @@
+# 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