chore(test): vitest migration

[chrisgervang]

Summary

This PR implements the exploration phase of the tape-to-vitest migration as outlined in the RFC.

What's included:

• Vitest configuration with multi-environment support (node, headless browser, render)
• Idempotent migration script that converts tape tests to vitest
• Test-utils updates for vitest compatibility
• 188 test files converted from tape to vitest
• Render tests converted to native vitest browser mode

Render Test Status

Current results: 167 passed, 6 failed, 12 skipped

Test	Status	Notes
icon-lnglat-rectangle	96.09% match	Golden image offset - needs regeneration
mvt-layer	98.79% match	Very close, minor rendering diff
mvt-layer-binary	98.79% match	Very close, minor rendering diff
scenegraph-layer-frame-3	97.68% match	Animation timing difference
post-process-effects	97.19% match	Golden image offset - needs regeneration
scatterplot-transition-2	92.02% match	Animation timing difference
scatterplot-transition-3/4	skipped	Timeline.setTime timing issues
terrain-extension-drape/offset	skipped	TerrainExtension loading timeout

The golden image mismatches appear to be due to differences in screenshot capture between the old probe.gl infrastructure and the new vitest browser commands.

Test output configuration

• All environments use TAP reporter - Consistent output format across CI and local development

Excluded/Skipped tests

luma.gl v9 API changes:

• mask/*.spec.ts - uniforms API changed
• path-layer-vertex.spec.ts - Transform not exported from @luma.gl/engine

Pre-existing issues (fix on master first):

• attribute.spec.ts - data-column.ts overwrites user stride/offset

Needs investigation (async/timing issues):

• tile-3d-layer.spec.ts, layer-extension.spec.ts, pick-layers.spec.ts
• terrain-layer.spec.ts, mvt-layer.spec.ts

Migration approach

The migration script (scripts/tape-to-vitest-migration.cjs) is idempotent:

• Reads original tape source from master branch
• Converts to vitest syntax while preserving assertion messages
• Can be re-run after fixing issues on master

Typed array equality

Added a custom equality tester to match tape's deepEqual behavior for typed arrays. This is marked as TODO for removal once tests are updated to use explicit comparisons.

Future improvements

• Refactor generateLayerTests to use vitest's test.each() so individual test cases are visible in vitest output (currently run in a loop inside one test() block)
• Regenerate golden images for failing render tests

Next steps (per RFC)

1. Fix deep import paths in tape tests on master
2. Delete obsolete test files (GPUGridLayer)
3. Re-run migration script
4. Address remaining environment-specific failures
5. Move to implementation phase
6. Regenerate golden images for render tests with offset issues

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches the core test harness, CI execution order, and shared @deck.gl/test-utils, so failures may be widespread if any environment/project config diverges (especially browser/render + Playwright). No production/runtime library behavior is changed.

Overview
Switches the repo’s primary test runner to Vitest with separate projects (node, headless/browser, render), updating package.json scripts, CI workflow steps (including Playwright Chromium install), and contributor docs to match the new test matrix.

Updates @deck.gl/test-utils to support Vitest via a new @deck.gl/test-utils/vitest entry point and a spy abstraction (createSpy) that works with both vi.spyOn and the legacy @probe.gl/test-utils spies; adds type declarations for browser driver globals and adjusts minor browser test runner behavior.

Converts a large batch of existing tape tests to Vitest syntax (including adding new Vitest browser-mode interaction specs), removes the old tape browser harness (index.html, test/browser.ts), and adds an idempotent scripts/tape-to-vitest-migration.cjs to automate future conversions. Misc: tweaks eslint/gitignore/tsconfig and adds .yarnrc to smooth dependency/engine constraints during the migration.

^{Written by Cursor Bugbot for commit 0c3fa68. This will update automatically on new commits. Configure here.}

[cursor]

Unused test data array TEXT_PIXEL_OFFSET_TESTS

Low Severity

The TEXT_PIXEL_OFFSET_TESTS constant defines an array of test cases but is never used. Unlike the other test data arrays in the file (COLOR_TESTS, SIZE_TESTS, TEXT_TESTS) which all have corresponding for...of loops that generate tests, TEXT_PIXEL_OFFSET_TESTS has no such test loop. This dead code adds confusion and maintenance burden.

 

[chrisgervang]

We're stuck on vitest 2 until we upgrade from node 18.

[chrisgervang]

The RFC outlines the goal being to implement a backwards-compatibility layer and deprecation warnings in @deck.gl/test-utils. I'm not sure what users use it for, but gets a significant number of downloads still so we need to not break anything.

I'm thinking we'll need to keep some old test infrastructure around for this module to ensure correctness on both tape and vitest until deck v10

Temporarily, I've removed tape and probe.gl from deck's test utils until I get all tests to pass without the extra complexity.

[chrisgervang]

Trying to run all of the tests in the node environment resulted in a lot of failures (which is not a surprise), so I'm going to instead implement the same test config for node that we have on master, which is basically a smoke-test.

I'll keep test-fast but remove test-node

[chrisgervang]

I don't think we need ocular-test anymore. Vitest seems to offer everything you need to run tests.

Please let me know if ocular-test did something internally that we lose because we're removing it

[chrisgervang]

Hoping to remove puppeteer after all tests pass

[akre54]

Instead of using a string replace have you considered something like https://github.com/facebook/jscodeshift ?

That way you can operate on the syntax tree and it's a little less hairy than trying to use a regex to parse

[chrisgervang]

Since this is one-time-use and already working reliably, I don’t see a strong reason to change it right now - but I’m open to revisiting if this there's something claude can't figure out

[cursor]

Regex error matcher incorrectly placed in toThrow assertions

Medium Severity

The migration script incorrectly converted t.throws(fn, regex) assertions. The regex pattern meant to match the error message is placed as the second argument to expect() instead of being passed to toThrow(). For example, expect(() => layer.validateProps(), /sizeScale/).toThrow() should be expect(() => layer.validateProps()).toThrow(/sizeScale/). The current code only verifies that some error is thrown, not that the error message matches the expected pattern, weakening test coverage.

Additional Locations (1)

• test/modules/carto/api/parse-map.spec.ts#L116-L117

 

[cursor]

Optional peer dep still required by main entry

Medium Severity

The main @deck.gl/test-utils entry point (index.ts) re-exports from ./tape, which has a top-level static import {makeSpy} from '@probe.gl/test-utils'. However, @probe.gl/test-utils is now marked as optional: true in peerDependenciesMeta. Any import from the main entry — even just device or gl — will fail at module load time if @probe.gl/test-utils is not installed, contradicting the optional designation.

Additional Locations (2)

• modules/test-utils/src/index.ts#L10-L11
• modules/test-utils/src/tape.ts#L7-L8

 

[cursor]

Migration converts spy.reset() to mockReset() incorrectly

High Severity

The migration script converts probe.gl's .reset() to vitest's .mockReset(), but these have different semantics. Probe.gl's reset() only clears call tracking (calls, callCount), while vitest's mockReset() clears call tracking AND removes the spy's call-through implementation, making the spied method return undefined. The correct vitest equivalent is mockClear(), which only clears call tracking without affecting the implementation. This affects attribute.spec.ts and terrain-effect.spec.ts, where spied methods like setData and renderTerrainCover become no-ops mid-test.

Additional Locations (2)

• test/modules/core/lib/attribute/attribute.spec.ts#L793-L794
• test/modules/extensions/terrain/terrain-effect.spec.ts#L58-L59

 

[cursor]

Static import contradicts optional peer dependency marking

Medium Severity

tape.ts uses a static import {makeSpy} from '@probe.gl/test-utils', but the package marks @probe.gl/test-utils as an optional peer dependency. This means importing from @deck.gl/test-utils (the main entry, which re-exports from ./tape) crashes at module load time if @probe.gl/test-utils isn't installed — even for exports like testInitializeLayer or TestRunner that don't need spies. The RFC specifies a dynamic await import(...) with try/catch to make this truly optional.

Additional Locations (1)

• modules/test-utils/package.json#L49-L53

 

[cursor]

Migration script leaves vitest files importing from probe.gl path

Medium Severity

Step 16 only rewrites @deck.gl/test-utils imports to the /vitest subpath when the file uses testLayer or testLayerAsync. Vitest test files that only import device, getLayerUniforms, or other utilities are left importing from the default entry point, which unconditionally triggers import {makeSpy} from '@probe.gl/test-utils' in tape.ts. This creates an unnecessary hard dependency on @probe.gl/test-utils for pure vitest test files — contradicting the optional peer dependency marking in package.json. At least 5 converted spec files (e.g., cpu-aggregator.spec.ts, webgl-aggregator.spec.ts) are affected since the exports they need (device, etc.) are available from @deck.gl/test-utils/vitest.

Additional Locations (1)

• modules/test-utils/src/tape.ts#L7-L8

 

[cursor]

Static import of optional dependency crashes main entry

High Severity

tape.ts uses a static import {makeSpy} from '@probe.gl/test-utils' but @probe.gl/test-utils is declared as an optional peer dependency. Since index.ts re-exports from ./tape, the entire @deck.gl/test-utils package fails to load when the optional dependency is absent — including non-spy exports like gl, device, and toLowPrecision. The RFC explicitly designed this as a lazy dynamic await import() with try/catch to gracefully handle the missing optional dependency, but the implementation uses a top-level static import instead.

Additional Locations (2)

• modules/test-utils/src/index.ts#L10-L11
• modules/test-utils/package.json#L49-L53

 

[cursor]

Static import contradicts optional peer dependency declaration

Medium Severity

tape.ts uses a static top-level import {makeSpy} from '@probe.gl/test-utils', but @probe.gl/test-utils is declared as an optional peer dependency in package.json. Since index.ts re-exports from ./tape, importing anything from @deck.gl/test-utils (the main entry) will crash if @probe.gl/test-utils is not installed. The RFC explicitly specifies using a lazy await import('@probe.gl/test-utils') with try-catch for graceful degradation when the package is absent. The current implementation breaks consumers who only install @deck.gl/test-utils without @probe.gl/test-utils.

Additional Locations (1)

• modules/test-utils/package.json#L49-L53

 

[cursor]

Interaction tests run in both headless and render

Low Severity

test/interaction/**/*.spec.ts is included in both the headless project (line 147) and the render project (line 205). Since the test script runs --project headless then test-render (which runs --project render), and CI does the same, interaction tests execute twice per run. This wastes CI time and could cause flakiness from parallel Deck instance creation/teardown.

Additional Locations (1)

• vitest.workspace.ts#L203-L205

 

[cursor]

Migration script overly broad .restore() and .reset() replacement

Medium Severity

Step 14b uses global regex /\.restore\s*\(\s*\)/g and /\.reset\s*\(\s*\)/g to convert spy methods, but these patterns match ANY .restore() or .reset() call on any object, not just spies. For example, a Canvas2D context.restore(), a WebGL state.reset(), or any other non-spy object with these methods would be incorrectly converted to .mockRestore() / .mockClear(), producing broken test files. The regex needs to be scoped to spy objects rather than applied globally.

 

[cursor]

Migration Step 2a converts all tests to describe blocks

Medium Severity

When hasNestedTTest is true (any t.test() exists in the original file), Step 2a converts ALL test('name', t => { patterns to describe('name', () => {, including standalone tests that don't contain nested tests. This causes standalone test assertions to run during collection rather than as proper test cases, making them invisible in test output when passing — effectively silently dropping tests from the suite.

 

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

[cursor]

probe.gl peer dependency not marked as optional per RFC

Medium Severity

The RFC explicitly specifies @probe.gl/test-utils should be an optional peer dependency (like vitest is), but the implementation marks only vitest as optional. Users importing from @deck.gl/test-utils/vitest don't need probe.gl at all, yet they'll get npm/yarn peer dependency warnings. Additionally, the RFC called for a lazy dynamic import() of @probe.gl/test-utils in the backward-compat path, but tape.ts uses a static import {makeSpy} from '@probe.gl/test-utils'. Since index.ts statically imports from ./tape, even users who only need testInitializeLayer (no spies) will trigger the probe.gl import and fail if it's not installed.

Additional Locations (1)

• modules/test-utils/src/tape.ts#L7-L8