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
Medium risk because it rewires the project’s test harness/CI pipeline (Vitest workspace projects, Playwright browser setup, new scripts) and changes @deck.gl/test-utils spy behavior/exports, which could cause missed or flaky tests even though runtime library code is largely untouched.

Overview
Switches the repo’s test runner from tape/ocular-test to Vitest with a multi-project workspace (node, headless, browser, render) backed by Playwright, and updates CI to run these projects separately (plus artifact upload for render diffs) while keeping a tape-compat smoke test.

Updates @deck.gl/test-utils to support Vitest via a new @deck.gl/test-utils/vitest entry and a spy-factory abstraction (decoupling from @probe.gl/test-utils), adds browser-driver type declarations, and adjusts interaction/render helpers for Vitest browser commands.

Bulk-converts many existing tests from tape assertions to vitest (expect/toHaveBeenCalled, etc.), removes the legacy index.html/test/browser.ts tape browser harness, and adds a tape-to-vitest migration script plus supporting lint/gitignore/docs updates.

^{Written by Cursor Bugbot for commit 394fe75. 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]

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]

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

 

[cursor]

Piped test commands mask Vitest failures

High Severity

package.json pipes vitest output through tap-spec in test, test-fast, test-headless, test-render, and test-ci. In npm/yarn scripts, pipeline status comes from the last command, so a failing vitest run can still exit successfully if tap-spec succeeds.

Additional Locations (1)

• package.json#L27-L33

 

[cursor]

Piped test scripts can mask failures

Medium Severity

The new test* scripts pipe vitest output into tap-spec using |. In npm/yarn scripts, pipeline status is taken from the last command, and tap-spec is only a formatter. This can report success even when vitest fails, making yarn test, test-fast, and related checks unreliable.

 

[cursor]

Migration removes unrelated function arguments

Medium Severity

The generic rewrite in convertTapeToVitest removes any first argument named t from calls matching fn(t, ...), not just tape helper calls. The comment says method calls are excluded, but the regex does not enforce that, so valid calls can be rewritten incorrectly and silently change behavior.

 

[cursor]

Engine checks disabled for all installs

Medium Severity

Adding --ignore-engines true disables dependency engine validation globally. This allows unsupported Node versions to install vitest and related tooling, then fail later at runtime instead of failing fast during install, which makes setup and CI/local behavior inconsistent and harder to diagnose.

 

[felixpalmer]

@chrisgervang I've tried giving this a spin, but all commands (yarn test, yarn test-browser & yarn test-render) are all returning:

yarn test
yarn run v1.22.19
$ vitest run --project node --project headless | tap-spec && npm run test-render


  ✖ No tests found


error Command failed with exit code 1.

[chrisgervang]

@felixpalmer @Pessimistress can you try:

rm -rf node_modules
yarn install
yarn vitest list --project node

If it still fails, what's your Node version (node --version)?
I'm on Node v18 in the .nvmrc using corepack for yarn, and can reproduce tests working in a fresh clone.

[felixpalmer]

@chrisgervang fixed with:

npx playwright install

Now running yarn test-browser kicks off the tests. Perhaps we should add a postinstall hook to package.json?

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

[cursor]

Migration script blindly replaces all .restore() and .reset() calls

Medium Severity

Step 14b uses blanket regexes /\.restore\s*\(\s*\)/g and /\.reset\s*\(\s*\)/g to replace ALL .restore() with .mockRestore() and ALL .reset() with .mockClear(). This transforms any object method named restore or reset, not just spy methods. For example, canvas context save()/restore() pairs, WebGL state management, or any domain object with a reset() method would be incorrectly rewritten. Since the script is designed to be re-run idempotently on future changes, this risks silently breaking non-spy code in any future invocation.

 

[cursor]

Migration script removes t from all function calls

Medium Severity

Step 11 uses /(\w+)\s*\(\s*t\s*,\s*/g to remove t as the first argument from ANY function call (except a small keyword list). This incorrectly transforms legitimate calls where a variable named t (e.g., a time value, a type parameter, a temporary variable) is passed as a real argument. The keyword exclusion list only covers control flow keywords and misses common functions like expect, Math.min, setTimeout, Array.from, etc. Since this script is idempotent and intended for re-use, this risks silently dropping real arguments in future conversions.

 

[cursor]

@probe.gl/test-utils peer dependency not marked optional

Medium Severity

The new ./vitest subpath export doesn't depend on @probe.gl/test-utils, yet it remains a required (non-optional) peer dependency. Users who only want the vitest entry point are still forced to install @probe.gl/test-utils. The peerDependenciesMeta marks vitest as optional but omits @probe.gl/test-utils, contradicting the RFC which specifies it should be optional.