zebbern/claude-code-guide / skills/playwright/core
playwright-core
VerifiedBattle-tested Playwright patterns for E2E, API, component, visual, accessibility, and security testing. Covers locators, assertions, fixtures, network mocking, auth flows, debugging, and framework recipes for React, Next.js, Vue, and Angular. TypeScript and JavaScript.
canvas-and-webgl.md
View on GitHub# 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |