Canvas Filmstrip Testing Skill

Tests canvas-rendered filmstrips that visualize how matrix data (energy fields, foam grids, etc.) evolves over simulated time. Each strip shows multiple frames side-by-side.

This is about visual rendering of data progressions. It catches:

• Color scale/gradient changes
• Canvas rendering bugs
• Missing or misaligned frames
• Incorrect visual interpolation

For the underlying data correctness, see

matrix-data-model-progression-testing

When to Use This

• Verifying canvas-rendered strips match expected appearance
• Testing color scales and gradients
• Debugging visual artifacts in filmstrip rendering
• Validating that progression data renders correctly

The 8-Layer Visual Pipeline

Each layer tests a specific aspect of the wave physics simulation:

src/render/bathymetryProgressions.ts

src/state/energyFieldProgressions.ts

src/render/shoalingProgressions.ts

src/render/waveBreakingProgressions.ts

src/render/energyTransferProgressions.ts

src/render/foamGridProgressions.ts

src/render/foamDispersionProgressions.ts

src/render/foamContoursProgressions.ts

Architecture

stories/
  01-bathymetry/
    01-bathymetry.mdx              → MDX story page
    01-bathymetry.visual.spec.ts   → Playwright visual test
    strip-bathymetry-basic.png     → Baseline screenshot (colocated)
    strip-bathymetry-features.png
  02-energy-field/
  ...

src/render/*Progressions.ts        → Progression data + strip definitions

Strip Definition Pattern

Each progression file exports strips for visual testing:

// src/render/bathymetryProgressions.ts
export const BATHYMETRY_STRIP_BASIC = {
  testId: 'strip-bathymetry-basic',
  pageId: '01-bathymetry',
  snapshots: PROGRESSION_BATHYMETRY_BASIC.snapshots,
};

export const BATHYMETRY_STRIPS = [
  BATHYMETRY_STRIP_BASIC,
  BATHYMETRY_STRIP_FEATURES,
];

Visual Test Pattern

// stories/01-bathymetry/01-bathymetry.visual.spec.ts
import { BATHYMETRY_STRIPS } from '../../src/render/bathymetryProgressions';
import { defineStripVisualTests } from '../visual-test-helpers';

defineStripVisualTests(BATHYMETRY_STRIPS);

Commands

# Run visual tests
npm run test:visual:headless        # CI/agents
npm run test:visual:headed          # Debugging with browser UI

# Update baselines after intentional changes
npm run test:visual:update:headless
npm run test:visual:update:headed

# Clear test artifacts
npm run reset:visual                # Clear results/reports only
npm run reset:visual:all            # Clear results + colocated baselines

# Start dev server for interactive debugging
npm run stories                     # Starts on http://localhost:3001

Workflow: Data First, Then Visual

CRITICAL: Always verify data before visual testing.

Wrong workflow:
  Change coefficient → Update visual snapshot → "Looks the same, try higher"

Correct workflow:
  Change coefficient → Run npx vitest run *Progressions.test.ts →
  Verify matrix values changed → Then update visual if needed

1. Verify data with ASCII - Run

   *Progressions.test.ts

2. If data correct, update visual -

   npm run test:visual:update:headless

3. If data wrong, fix logic first - Don't touch visuals

Mapping testId to Source

When a visual test fails:

1. testId like

   strip-bathymetry-basic

   →

   BATHYMETRY_STRIP_BASIC

   in progressions file
2. pageId like

   01-bathymetry

   →

   stories/01-bathymetry/

   folder
3. Pattern:

   strip-{layer}-{variant}

   →

   *{layer}Progressions.ts

Debugging with Chrome DevTools MCP

// Start dev server
npm run stories

// Open specific story page
mcp__chrome-devtools__new_page({
  url: "http://localhost:3001/?page=01-bathymetry"
})

// Take snapshot to find strip UIDs
mcp__chrome-devtools__take_snapshot()

// Screenshot the strip element
mcp__chrome-devtools__take_screenshot({ uid: "<strip-uid>" })

// After code changes, reload and compare
mcp__chrome-devtools__navigate_page({ type: "reload" })
mcp__chrome-devtools__take_screenshot({ uid: "<strip-uid>" })

Common Issues

Visual Differs but Data is Correct

Check:

• Color scale mapping (value → color)
• Canvas context settings (smoothing, etc.)
• Cell sizing/spacing in strip renderer

Visual Passes but Looks Wrong

The baseline may be incorrect. Manually verify:

1. Start dev server:

   npm run stories

2. Navigate to the story
3. Visually inspect the strip
4. If wrong, update baseline:

   npm run test:visual:update:headless

Related Skills

• matrix-data-model-progression-testing - Verify data correctness first
• component-screenshot-testing - For React UI component screenshots
• visual-regression - Shared infrastructure and commands
• visualization-algorithms - Canvas rendering algorithms