perf(experimental): add file system cache

.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,47 @@ 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
+function experimental_defineCacheKeyGenerator(
+  callback: (
+    environment: DevEnvironment,
+    id: string,
+    sourceCode: string,
+  ) => string | undefined | null
+): 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
+      })
+    }
+  }
+}
+```

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,31 @@ 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/).
+:::
+
+::: danger ADVANCED
+If you are a plugin author, consider defining a [cache key generator](/api/advanced/plugin#definecachekeygenerator) if your plugin 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:** `join(tmpdir(), 'vitest')`
+
+Directory where the file system cache is located.
+
+## 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 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,26 @@ 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 {
+    // 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 (!this.requiresTransform(id)) {
       return
     }