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: 162 passed, 2 failed, 9 skipped

Test	Status	Notes
arc-lnglat	❌ ~95-99% match	Flaky subtle rendering diff
gridcell-lnglat	❌ ~98-99% match	Flaky subtle rendering diff
icon-lnglat-rectangle	✅ passed	Golden image regenerated
mvt-layer	✅ passed
mvt-layer-binary	✅ passed
post-process-effects	✅ passed	Golden image regenerated
scenegraph-layer-frame-1/2/3	✅ passed	Fixed with shared Deck instance
scatterplot-transition-1/2/3/4	✅ passed	Fixed with shared Deck instance, tests 3/4 unskipped
terrain-extension-drape/offset	skipped	TerrainExtension loading timeout

Timeline/Transition Test Fix

Tests that manipulate timeline.setTime() in onAfterRender now use a shared Deck instance pattern via updateDeckForTest(). This keeps the animation loop running between callbacks, allowing timeline changes to trigger re-renders.

Test output configuration

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

Excluded/Skipped tests

Render tests (flaky):

• arc-lnglat, gridcell-lnglat - Subtle rendering differences, needs investigation

Render tests (timeout):

• terrain-extension-drape, terrain-extension-offset - TerrainExtension loading timeout

Interaction tests:

• 6 keyboard controller tests, 1 picking test - Need investigation

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.

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. Investigate flaky arc-lnglat and gridcell-lnglat tests

🤖 Generated with Claude Code

---

Note

Medium Risk
Moderate risk because it rewires core CI/test commands to Vitest/Playwright and changes @deck.gl/test-utils exports/peer deps, which can break contributor workflows and downstream test consumers if assumptions differ.

Overview
Migrates the repo’s test workflow from ocular-test/tape to Vitest projects (node/headless/browser/render) and updates CI to run yarn test-ci, upload render diff artifacts on failure, and keep a tape-compat smoke test for backwards compatibility.

Updates @deck.gl/test-utils to support both runners by introducing @deck.gl/test-utils/vitest, making spy creation/reset injectable, and adding async cleanup to avoid luma.gl shader-error race unhandled rejections; also adds a new export map entry and optional vitest peer dependency.

Adds/updates migration tracking docs (new docs/TEST-STATUS.md, expanded RFC notes, CONTRIBUTING test commands), adjusts lint/ignore lists and gitignore for new configs/screenshots, and removes the old index.html browser test entry.

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

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]

Root devDependencies missing required build-time dependency for test-utils

Medium Severity

@probe.gl/test-utils was removed from root devDependencies, but tape.ts (which is compiled as part of @deck.gl/test-utils) still has a hard static import of makeSpy from it. The package relies on @probe.gl/test-utils being available as a transitive dependency (likely through @vis.gl/dev-tools), making the build fragile — if that transitive path ever changes, the @deck.gl/test-utils module will fail to compile.

Additional Locations (1)

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

 

[cursor]

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

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

[cursor]

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

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

[cursor]

Missing @probe.gl/test-utils optional marker for vitest-only users

Low Severity

The @probe.gl/test-utils peer dependency is required (non-optional) even though the ./vitest sub-entry (vitest.ts) never imports from it. Users who exclusively import from @deck.gl/test-utils/vitest will receive unnecessary peer dependency warnings about @probe.gl/test-utils. While documented in the RFC, marking it as optional in peerDependenciesMeta alongside vitest would be more accurate — users of the main entry would still get a runtime error (with a clear stack trace) if it's missing, which is arguably better than a generic peer dep warning.

Additional Locations (1)

• modules/test-utils/src/vitest.ts#L1-L38

 

[chrisgervang]

This is not an issue, dont bring it up again

[cursor]

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

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

[cursor]

Spy cleanup changes from reset to restore

Medium Severity

The spy cleanup changed from calling spy.reset() (which clears call tracking but keeps the spy active) to restoreSpy() (which calls mockRestore()/restore(), fully removing the spy and restoring the original method). For probe.gl users going through the backward-compatible tape.ts path, this changes the contract: spies are now fully torn down between test cases instead of just having their tracking cleared. While spies are re-created via injectSpies each iteration, any test that relied on the old reset-only semantics (e.g., checking cumulative spy state across the cleanup boundary, or relying on the spy wrapper remaining on the prototype) will behave differently.

Additional Locations (1)

• modules/test-utils/src/lifecycle-test.ts#L193-L194

 

[cursor]

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

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

[cursor]

Utility file imports from wrong test-utils entry point

Medium Severity

The codemod fixture output for utility files imports device from @deck.gl/test-utils (the main entry point backed by tape.ts), while all test file fixtures correctly import from @deck.gl/test-utils/vitest. The main entry point unconditionally imports makeSpy from @probe.gl/test-utils, meaning any vitest-only user who hasn't installed @probe.gl/test-utils as a peer dependency will get a runtime import failure when the utility file loads. Since these fixtures define the expected codemod output, the codemod will propagate this inconsistency to all converted utility files.

Additional Locations (1)

• scripts/codemods/tape-to-vitest/fixtures/output/05-layer-callbacks.ts#L8-L9

 

[cursor]

Cursor Bugbot has reviewed your changes and found 2 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]

Vitest mockRestore destroys spy before later test cases reuse it

Medium Severity

The defaultResetSpy calls mockRestore() which completely restores the original method and removes the spy. In lifecycle-test.ts, spies are injected per test case via injectSpies on the layer's prototype, so calling mockRestore() between test cases restores the prototype method. When the next test case re-spies the same prototype method, vi.spyOn wraps the original again — but if a test case's onAfterUpdate calls spy.mockRestore() directly (as seen in the converted HeatmapLayer test fixture output), the spy from injectSpies is destroyed mid-test-case. The probe.gl equivalent reset() only cleared call tracking. Using mockClear instead of mockRestore would preserve the spy while clearing call counts, matching the original reset() semantics.

 

[cursor]

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

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

[cursor]

Utility file codemod output imports from wrong entry point

Low Severity

The codemod fixture 06-utility-file.ts imports device from @deck.gl/test-utils (the default/tape entry point) instead of @deck.gl/test-utils/vitest. This causes the converted test to transitively import @probe.gl/test-utils via tape.ts, which defeats the purpose of the vitest-specific entry point. Meanwhile, 05-layer-callbacks.ts correctly uses @deck.gl/test-utils/vitest. This inconsistency means the codemod would produce output that unnecessarily pulls in @probe.gl/test-utils for utility files. All vitest-converted files that only need device, gl, or other non-spy utilities from test-utils should import from @deck.gl/test-utils/vitest to avoid the probe.gl dependency.

Additional Locations (1)

• scripts/codemods/tape-to-vitest/fixtures/output/05-layer-callbacks.ts#L8-L9

 

[cursor]

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

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

[cursor]

Duplicated cleanup logic risks inconsistent maintenance

Low Severity

cleanupAfterLayerTestsAsync is a near-exact copy of cleanupAfterLayerTests, differing only by a single await line before finalize(). The finalize-and-check-resource-counts logic (~8 lines) is duplicated. If the resource checking logic changes (e.g., adding new resource types to track), both functions must be updated in lockstep or they'll diverge silently. Extracting the shared finalize/check logic into a small helper would eliminate this maintenance risk.

Additional Locations (1)

• modules/test-utils/src/lifecycle-test.ts#L316-L337

 

[cursor]

Cursor Bugbot has reviewed your changes and found 2 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]

Exported type has required fields wrapper makes optional

Low Severity

The vitest.ts entry point re-exports the TestLayerOptions type from lifecycle-test.ts, which has createSpy and resetSpy as required fields. However, the testLayer and testLayerAsync wrapper functions in vitest.ts accept these as optional (with defaults). Consumers who import TestLayerOptions to type their options objects would be forced to provide createSpy/resetSpy even though the functions don't require them. Exporting a separate type (e.g., Omit<TestLayerOptions, 'createSpy' | 'resetSpy'> & { createSpy?: SpyFactory; resetSpy?: ResetSpy }) or making these fields optional in TestLayerOptions would align the type with the actual API.

Additional Locations (1)

• modules/test-utils/src/lifecycle-test.ts#L185-L208

 

[cursor]

Browser project uses headed renderPlaywright instead of default

Low Severity

The browser project (for local debugging with visible browser) uses renderPlaywright as its provider, which has a fixed viewport of {width: 1024, height: 768}. However, the browser project is headed mode intended for general debugging of unit tests, not for render/golden-image comparison. Using the render-specific viewport configuration in the non-render debugging project is unintentional — the headless project uses the default playwright() provider without viewport constraints, which is the expected configuration here.

 

[cursor]

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

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

[cursor]

Cleanup functions have duplicated resource-checking logic

Low Severity

The new cleanupAfterLayerTestsAsync function duplicates the entire body of cleanupAfterLayerTests, differing only by setLayers([]) plus an await setTimeout(0) before finalization. The resource-counting loop and error construction are copy-pasted. If a bug is fixed in one cleanup path, the other could easily be missed. The async version could call the sync cleanup's shared logic after its yield, or a shared helper could extract the resource-check code.

Additional Locations (1)

• modules/test-utils/src/lifecycle-test.ts#L318-L337