perf(experimental): add file system cache (#9026)

Author: sheremet-va

.github/workflows/ci.yml

@@ -127,6 +127,42 @@ jobs:
           path: test/ui/test-results/
           retention-days: 30
 
+  test-cached:
+    needs: changed
+    name: 'Cache&Test: node-${{ matrix.node_version }}, ${{ matrix.os }}'
+    if: needs.changed.outputs.should_skip != 'true'
+    runs-on: ${{ matrix.os }}
+
+    timeout-minutes: 30
+
+    strategy:
+      matrix:
+        node_version: [24]
+        os:
+          - macos-latest
+          - windows-latest
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: ./.github/actions/setup-and-cache
+        with:
+          node-version: ${{ matrix.node_version }}
+
+      - uses: browser-actions/setup-chrome@b94431e051d1c52dcbe9a7092a4f10f827795416 # v2.1.0
+
+      - name: Install
+        run: pnpm i
+
+      - uses: ./.github/actions/setup-playwright
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Test
+        run: pnpm run test:ci:cache
+
   test-browser:
     needs: changed
     name: 'Browsers: node-${{ matrix.node_version }}, ${{ matrix.os }}'

docs/.vitepress/scripts/cli-generator.ts

@@ -41,6 +41,7 @@ const skipConfig = new Set([
   'ui',
   'browser.name',
   'browser.fileParallelism',
+  'clearCache',
 ])
 
 function resolveOptions(options: CLIOptions<any>, parentName?: string) {

docs/api/advanced/plugin.md

@@ -123,3 +123,51 @@ The project's `configFile` can be accessed in Vite's config: `project.vite.confi
 
 Note that this will also inherit the `name` - Vitest doesn't allow multiple projects with the same name, so this will throw an error. Make sure you specified a different name. You can access the current name via the `project.name` property and all used names are available in the `vitest.projects` array.
 :::
+
+### experimental_defineCacheKeyGenerator <Version type="experimental">4.0.11</Version> <Experimental /> {#definecachekeygenerator}
+
+```ts
+interface CacheKeyIdGeneratorContext {
+  environment: DevEnvironment
+  id: string
+  sourceCode: string
+}
+
+function experimental_defineCacheKeyGenerator(
+  callback: (context: CacheKeyIdGeneratorContext) => string | undefined | null | false
+): void
+```
+
+Define a generator that will be applied before hashing the cache key.
+
+Use this to make sure Vitest generates correct hash. It is a good idea to define this function if your plugin can be registered with different options.
+
+This is called only if [`experimental.fsModuleCache`](/config/experimental#fsmodulecache) is defined.
+
+```ts
+interface PluginOptions {
+  replacePropertyKey: string
+  replacePropertyValue: string
+}
+
+export function plugin(options: PluginOptions) {
+  return {
+    name: 'plugin-that-replaces-property',
+    transform(code) {
+      return code.replace(
+        options.replacePropertyKey,
+        options.replacePropertyValue
+      )
+    },
+    configureVitest({ experimental_defineCacheKeyGenerator }) {
+      experimental_defineCacheKeyGenerator(() => {
+        // since these options affect the transform result,
+        // return them together as a unique string
+        return options.replacePropertyKey + options.replacePropertyValue
+      })
+    }
+  }
+}
+```
+
+If the `false` is returned, the module will not be cached on the file system.

docs/api/advanced/vitest.md

@@ -607,3 +607,11 @@ function experimental_parseSpecifications(
 ```
 
 This method will [collect tests](#parsespecification) from an array of specifications. By default, Vitest will run only `os.availableParallelism()` number of specifications at a time to reduce the potential performance degradation. You can specify a different number in a second argument.
+
+## experimental_clearCache <Version type="experimental">4.0.11</Version> <Badge type="warning">experimental</Badge> {#clearcache}
+
+```ts
+function experimental_clearCache(): Promise<void>
+```
+
+Deletes all Vitest caches, including [`experimental.fsModuleCache`](/config/experimental#fsmodulecache).

docs/config/experimental.md

@@ -5,7 +5,75 @@ outline: deep
 
 # experimental
 
-## openTelemetry <Version type="experimental">4.0.10</Version>
+## experimental.fsModuleCache <Version type="experimental">4.0.11</Version> {#experimental-fsmodulecache}
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Enabling this option allows Vitest to keep cached modules on the file system, making tests run faster between reruns.
+
+You can delete the old cache by running [`vitest --clearCache`](/guide/cli#clearcache).
+
+::: warning BROWSER SUPPORT
+At the moment, this option does not affect [the browser](/guide/browser/).
+:::
+
+You can debug if your modules are cached by running vitest with a `DEBUG=vitest:cache:fs` environment variable:
+
+```shell
+DEBUG=vitest:cache:fs vitest --experimental.fsModuleCache
+```
+
+### Known Issues
+
+Vitest creates persistent file hash based on file content, its id, vite's environment configuration and coverage status. Vitest tries to use as much information it has about the configuration, but it is still incomplete. At the moment, it is not possible to track your plugin options because there is no standard interface for it.
+
+If you have a plugin that relies on things outside the file content or the public configuration (like reading another file or a folder), it's possible that the cache will get stale. To workaround that, you can define a [cache key generator](/api/advanced/plugin#definecachekeygenerator) to specify dynamic option or to opt-out of caching for that module:
+
+```js [vitest.config.js]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  plugins: [
+    {
+      name: 'vitest-cache',
+      configureVitest({ experimental_defineCacheKeyGenerator }) {
+        experimental_defineCacheKeyGenerator(({ id, sourceCode }) => {
+          // never cache this id
+          if (id.includes('do-not-cache')) {
+            return false
+          }
+
+          // cache this file based on the value of a dynamic variable
+          if (sourceCode.includes('myDynamicVar')) {
+            return process.env.DYNAMIC_VAR_VALUE
+          }
+        })
+      }
+    }
+  ],
+  test: {
+    experimental: {
+      fsModuleCache: true,
+    },
+  },
+})
+```
+
+If you are a plugin author, consider defining a [cache key generator](/api/advanced/plugin#definecachekeygenerator) in your plugin if it can be registered with different options that affect the transform result.
+
+## experimental.fsModuleCachePath <Version type="experimental">4.0.11</Version> {#experimental-fsmodulecachepath}
+
+- **Type:** `string`
+- **Default:** `'node_modules/.experimental-vitest-cache'`
+
+Directory where the file system cache is located.
+
+By default, Vitest will try to find the workspace root and store the cache inside the `node_modules` folder. The root is based on your package manager's lockfile (for example, `.package-lock.json`, `.yarn-state.yml`, `.pnpm/lock.yaml` and so on).
+
+At the moment, Vitest ignores the [test.cache.dir](/config/cache) or [cacheDir](https://vite.dev/config/shared-options#cachedir) options completely and creates a separate folder.
+
+## experimental.openTelemetry <Version type="experimental">4.0.11</Version> {#experimental-opentelemetry}
 
 - **Type:**
 

docs/config/server.md

@@ -71,25 +71,3 @@ If a `RegExp` is provided, it is matched against the full file path.
 When a dependency is a valid ESM package, try to guess the cjs version based on the path. This might be helpful, if a dependency has the wrong ESM file.
 
 This might potentially cause some misalignment if a package has different logic in ESM and CJS mode.
-
-## debug
-
-### dump
-
-- **Type:** `string | boolean`
-- **Default:** `false`
-
-The folder where Vitest stores the contents of inlined test files that can be inspected manually.
-
-If set to `true`, Vitest dumps the files inside the `.vitest-dump` folder relative to the root of the project.
-
-You can also use `VITEST_DEBUG_DUMP` env variable to enable this conditionally.
-
-### load
-
-- **Type:** `boolean`
-- **Default:** `false`
-
-Read files from the dump instead of transforming them. If dump is disabled, this does nothing.
-
-You can also use `VITEST_DEBUG_LOAD_DUMP` env variable to enable this conditionally.

docs/guide/cli-generated.md

@@ -798,3 +798,16 @@ Use `bundle` to bundle the config with esbuild or `runner` (experimental) to pro
 - **CLI:** `--standalone`
 
 Start Vitest without running tests. Tests will be running only on change. This option is ignored when CLI file filters are passed. (default: `false`)
+
+### clearCache
+
+- **CLI:** `--clearCache`
+
+Delete all Vitest caches, including `experimental.fsModuleCache`, without running any tests. This will reduce the performance in the subsequent test run.
+
+### experimental.fsModuleCache
+
+- **CLI:** `--experimental.fsModuleCache`
+- **Config:** [experimental.fsModuleCache](/config/experimental#experimental-fsmodulecache)
+
+Enable caching of modules on the file system between reruns.

package.json

@@ -25,6 +25,7 @@
     "release": "tsx scripts/release.ts",
     "test": "pnpm --filter test-core test:threads",
     "test:ci": "CI=true pnpm -r --reporter-hide-prefix --stream --sequential --filter '@vitest/test-*' --filter !test-browser run test",
+    "test:ci:cache": "CI=true pnpm -r --reporter-hide-prefix --stream --sequential --filter '@vitest/test-*' --filter !test-browser --filter !test-dts-config --filter !test-dts-fixture --filter !test-dts-playwright --filter !test-ui --filter !test-cache run test --experimental.fsModuleCache",
     "test:examples": "CI=true pnpm -r --reporter-hide-prefix --stream --filter '@vitest/example-*' run test",
     "test:ecosystem-ci": "ECOSYSTEM_CI=true pnpm test:ci",
     "typebuild": "tsx ./scripts/explain-types.ts",

packages/coverage-istanbul/src/provider.ts

@@ -50,15 +50,23 @@ export class IstanbulCoverageProvider extends BaseCoverageProvider<ResolvedCover
     })
   }
 
-  onFileTransform(sourceCode: string, id: string, pluginCtx: any): { code: string; map: any } | undefined {
+  requiresTransform(id: string): boolean {
     // Istanbul/babel cannot instrument CSS - e.g. Vue imports end up here.
     // File extension itself is .vue, but it contains CSS.
     // e.g. "Example.vue?vue&type=style&index=0&scoped=f7f04e08&lang.css"
     if (isCSSRequest(id)) {
-      return
+      return false
     }
 
     if (!this.isIncluded(removeQueryParameters(id))) {
+      return false
+    }
+
+    return true
+  }
+
+  onFileTransform(sourceCode: string, id: string, pluginCtx: Vite.Rollup.TransformPluginContext): { code: string; map: any } | undefined {
+    if (!this.requiresTransform(id)) {
       return
     }