chore(dev-tools): upgrade shared test tooling to Vitest 5

.gitignore

@@ -20,3 +20,4 @@ modules/dev-tools/.alias.json
 coverage/
 .nyc_output/
 tsconfig.tsbuildinfo
+.vitest/

modules/dev-tools/docs/README.md

@@ -107,6 +107,17 @@ extend the shared vis.gl defaults and add repository-specific file selection and
 When no project configuration exists, `ocular-lint` uses the packaged defaults directly.
 #### vite
 
+The shared test configuration targets Vitest 5. Install its peers explicitly, including Vite
+(Vitest 5 no longer installs Vite as a dependency):
+
+```bash
+yarn add --dev vitest@^5.0.2 @vitest/coverage-v8@^5.0.2 vite@^8.0.0 playwright
+```
+
+The coverage package is optional when coverage is not used. Keep Vitest, its browser provider,
+and coverage provider on matching versions. Vite 6.4, 7, and 8 are supported. The existing
+dev-tools Node requirement (22.15+, 24, or 26) satisfies Vitest 5's runtime requirement.
+
 Create `vitest.config.ts` at the repository root and call `getVitestConfig()` for shared Node,
 headed-browser, and headless-browser projects. Node-only tests use `*.node.spec.ts`; browser tests
 use `*.browser.spec.ts`.

modules/dev-tools/docs/upgrade-guide.md

@@ -14,6 +14,23 @@ and use `*.node.spec.ts` for Node tests and `*.browser.spec.ts` for Playwright b
 Pass a `projects` map to `getVitestConfig()` to customize, disable, or add projects. The legacy
 `node`, `browser`, and `headless` test-option fields remain temporarily available but are deprecated.
 
+### Vitest 5
+
+Update `vitest` and any directly installed `@vitest/*` providers to matching Vitest 5 versions.
+Vitest 4 is no longer supported by this version of the shared configuration. Yarn users must
+also install `vite` explicitly; it is now a required peer dependency. Vite 6.4, 7, and 8 are supported.
+
+Vitest 5 clears mock call history before each test and fails unawaited asynchronous assertions.
+Review tests that inspect calls made in `beforeAll`, and await `resolves`, `rejects`, and other
+asynchronous expectations. Coverage globs now match relative paths more precisely: compare the
+covered file inventory and retain newly included production files instead of weakening thresholds.
+
+Blob reports now default to `.vitest/blob/`. Update CI artifact paths, or retain existing paths
+with explicit, unique `--outputFile.blob` values for each shard and a matching `--merge-reports`
+directory. Add `.vitest/` to the consuming repository's `.gitignore` for generated artifacts.
+
+See the [Vitest 5 migration guide](https://vitest.dev/guide/migration/) for the complete changes.
+
 ## ocular-dev-tools 1.0.0
 
 Functional entry points replace subpath imports

modules/dev-tools/package.json

@@ -44,8 +44,8 @@
   },
   "dependencies": {
     "@biomejs/biome": "^2.4.8",
-    "@vitest/browser": "^4.0.18",
-    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/browser": "^5.0.2",
+    "@vitest/browser-playwright": "^5.0.2",
     "deepmerge": "^4.2.2",
     "esbuild": "^0.28.1",
     "esbuild-plugin-external-global": "^1.0.1",
@@ -59,9 +59,10 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "^5.0.2",
     "playwright": "^1.58.0",
-    "vitest": "^4.0.18"
+    "vite": "^6.4.0 || ^7.0.0 || ^8.0.0",
+    "vitest": "^5.0.2"
   },
   "peerDependenciesMeta": {
     "@vitest/coverage-v8": {

modules/docusaurus-website/test/get-default-config.spec.ts

@@ -11,3 +11,31 @@ test('getDocusaurusConfig supports omitted webpackConfig', () => {
     })
   ).not.toThrow();
 });
+
+test('getDocusaurusConfig normalizes nested documentation sidebars', () => {
+  const config = getDocusaurusConfig({
+    projectName: 'test-project',
+    repoUrl: 'https://github.com/visgl/test-project',
+    siteUrl: 'https://example.com',
+    docsTableOfContents: [
+      'overview',
+      {type: 'category', label: 'Guides', items: ['setup', {type: 'doc', id: 'advanced'}]}
+    ]
+  });
+  const [, presetOptions] = config.presets![0] as [
+    string,
+    {docs: {sidebarItemsGenerator: () => unknown}}
+  ];
+
+  expect(presetOptions.docs.sidebarItemsGenerator()).toEqual([
+    {type: 'doc', id: 'overview'},
+    {
+      type: 'category',
+      label: 'Guides',
+      items: [
+        {type: 'doc', id: 'setup'},
+        {type: 'doc', id: 'advanced'}
+      ]
+    }
+  ]);
+});

package.json

@@ -21,10 +21,11 @@
   "devDependencies": {
     "@luma.gl/constants": "^9.0.0-beta",
     "@vis.gl/dev-tools": "workspace:*",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "^5.0.2",
     "playwright": "^1.58.0",
     "pre-commit": "^1.2.2",
-    "vitest": "^4.0.18"
+    "vite": "^8.0.0",
+    "vitest": "^5.0.2"
   },
   "pre-commit": "pre-commit",
   "packageManager": "yarn@4.18.0+sha512.fcb8716fe7cd0eece141ffc18b92193a9df9204c1ba83189c288835223fc0bbe64af473bab0d5e9927a7daeb5caf2bb07eb2787cc9338ca040ea125f2a1f2f7e"

test/browser.browser.spec.ts

@@ -1,6 +1,17 @@
-import {expect, test} from 'vitest';
+import {expect, test, vi} from 'vitest';
+import {getBrowserFixtureValue} from './fixtures/browser-module.js';
+
+vi.mock('./fixtures/browser-module.js');
 
 test('browser project runs in a browser', () => {
   expect(globalThis.window).toBeDefined();
   expect(window.document).toBeDefined();
 });
+
+test('browser project intercepts module imports with the shared Playwright provider', () => {
+  expect(vi.isMockFunction(getBrowserFixtureValue)).toBe(true);
+  expect(getBrowserFixtureValue()).toBeUndefined();
+
+  vi.mocked(getBrowserFixtureValue).mockReturnValue('mocked');
+  expect(getBrowserFixtureValue()).toBe('mocked');
+});

test/fixtures/browser-module.ts

@@ -0,0 +1,4 @@
+/** Returns a recognizable value so browser tests can detect a missed module mock. */
+export function getBrowserFixtureValue(): string {
+  return 'original';
+}