vite-plugin-vitest-cache (vCache)

Note

In vitest terms, the caching covers: transformation, setup, collection, running, environment and preparation of tests. All of those are skipped for cached entries in exchange for a small price of calculating the hashes.

vCache provides test caching for Vitest. This plugin is useful for:

• running non-trivial, complex, resource-intensive, or otherwise slow tests, as it enables running only the tests that are actually affected by code changes
• monorepos, as it avoids the complications and limitations stemming from complex package dependency trees by ignoring module boundaries and treating everything as sources, calculating hashes from tree shaken code.

How it Works

It uses the same toolkit used for building your sources to build the test files. Hashes of these files are then used for cache matching. When running the tests, only the test files without a cache-hit (test files affected by the latest code changes for example) are run, the rest are simply restored from cache.

Installation

npm install --save-dev @raegen/vite-plugin-vitest-cache

yarn add --dev @raegen/vite-plugin-vitest-cache

Usage

import { defineConfig } from "vitest";
import vCache from '@raegen/vite-plugin-vitest-cache';

export default defineConfig({
  plugins: [vCache()],
});

Usage with CI

The only potential obstacle here, is cache persistence across runs, contexts. Since we use filesystem for cache storage, it's just a matter of configuring the respective CI cache to include the paths used by vCache (See dir).

Github Actions

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: vCache
      id: v-cache
      uses: actions/cache@v4
      with:
        path: **/.tests
        key: v-cache

    - name: Test
      run: ...run tests

Gitlab CI/CD

job:
  script: ...run tests
  artifacts:
    name: v-cache
    paths:
      - **/.tests

Options

dir

Control where the caches are saved.

@default ".tests" (relative to the project root)

vCache({ dir: ".tests" });

states

Control which result states to cache. Possible values are "pass" and "fail".

@default ["pass"]

vCache({ states: ["pass"] });

silent

Control whether vCache should write any logs to stdout.

@default false

vCache({ silent: true });

strategy

interface ExtendedCacheEntry {
  data: SerializedRecord;
  path: string;
  cost: number;
  timestamp: number;
  size: number;
}

interface CacheStrategy {
  (entries: ExtendedCacheEntry[]): ExtendedCacheEntry[];
}

Cache cleanup strategy. We can't have it grow forever, can we? Strategy is effectively a reducer for cache entries. It is invoked for each existing cache id (test file), with an array of currently stored cache entries (entries: ExtendedCacheEntry[]) for that id and should return an array of cache entries to be stored. (all the cache entries not present in the returned array are removed).

@default stores last 3 USED cached entries

vCache({
  strategy: (entries: ExtendedCacheEntry[]) => entries.sort((a, b) => b.timestamp - a.timestamp).slice(0, 3)
})

Note

Caution

The purpose of this plugin is not to promote what are ultimately bad test practices. Your unit tests should NOT be non-trivial, complex, resource-intensive, or otherwise slow. If you find yourself in need of such tests, first and foremost evaluate whether unit testing is what you need and look into integration, E2E testing etc.