GeezerVison

text: 'Parallel and Sequential Test Files',

link: '/guide/recipes/parallel-sequential',

},

{

text: 'Running Only Affected Tests',

link: '/guide/recipes/affected-tests',

},

],

},

{

const nonNullable = <T>(value: T): value is NonNullable<T> => value !== null && value !== undefined

const skipCli = new Set(['mergeReports', 'shard'])

const skipCli = new Set(['mergeReports', 'shard', 'sinceLastRun'])

const skipConfig = new Set([

'config',

- **Type:** `VCSProvider | string`

- **Type:** `'git' | 'mtime' | VCSProvider | string`

interface VCSProvider {

interface VCSProviderOptions {

root: string

changedSince?: string | boolean

/** Resolves the dependencies of the test files of the run. */

resolver: ModulesResolver

}

interface ModulesResolver {

/**

getDependencies(): Promise<ModuleDependency[]>

}

interface ModuleDependency {

/** Absolute path of the file. */

file: string

/**

recordedAt?: number

}

- **Default:** `'git'`

Custom provider for detecting changed files. Used with the [`--changed`](/guide/cli#changed) flag to determine which files have been modified.

Provider for detecting changed files. Used with the [`--changed`](/guide/cli#changed) flag to determine which files have been modified.

Vitest has two built-in providers:

- `'git'` returns the files that differ from the `--changed` reference, plus staged and untracked files.

- `'mtime'` <Version type="experimental">5.1.0</Version> returns the recorded dependencies whose modification time is newer than the run that recorded them, and deleted dependencies. It needs [`experimental.recordDependencies`](#experimental-recorddependencies): a dependency without a record is always reported as changed, so every test runs until the records exist. It does not need Git and ignores the `--changed` reference. A `--changed` run updates the records of the tests it ran, so the next `--changed` run selects only the tests whose dependencies changed since, and the test files that failed in their last run.

```ts [vitest.config.ts]

import { defineConfig } from 'vitest/config'

export default defineConfig({

test: {

experimental: {

recordDependencies: true,

vcsProvider: 'mtime',

},

},

})

::: warning

The `mtime` provider compares file times with the clock of the machine that ran the tests. A checkout or a copy that sets file times in the past is not detected.

:::

By default, Vitest uses Git to detect changed files. You can provide a custom implementation of the `VCSProvider` interface to use a different version control system:

You can provide a custom implementation of the `VCSProvider` interface to use a different version control system. `options.resolver.getDependencies()` returns every file the test files of the run depend on, so a provider can limit its work to these files:

```ts [vitest.config.ts]

import { defineConfig } from 'vitest/config'

test: {

experimental: {

vcsProvider: {

async findChangedFiles({ root, changedSince }) {

// return paths of changed files

async findChangedFiles({ root, changedSince, resolver }) {

const dependencies = await resolver.getDependencies()

// return the paths of the changed files

return []

},

},

}

- **Type:** `boolean`

- **Default:** `false`

- **CLI:** `--experimental.vcsProvider <path>`

- **Config:** [experimental.vcsProvider](/config/experimental#experimental-vcsprovider)

Custom provider for detecting changed files. (default: `git`)

Provider for detecting changed files: `git`, `mtime` (requires `experimental.recordDependencies`) or a path to a custom provider. (default: `git`)

vitest --merge-reports --reporter=junit

- **Type:** `boolean`

- **Default:** `false`

Run only the tests whose dependencies were modified since the last run of the test. A test is selected when one of the files it loaded during its last run has a newer modification time than that run, or was deleted. A test that never ran with this flag has no record and always runs. A test file that failed in its last run also runs, until it passes, because the cause of a failure can be outside the recorded files, for example an environment variable or a server that was down.

vitest run --since-last-run

The flag enables [`changed`](/config/changed), [`experimental.recordDependencies`](/config/experimental#experimental-recorddependencies) and the `mtime` [provider](/config/experimental#experimental-vcsprovider). Every run with this flag updates the records of the tests it ran, so the next run selects only the tests affected by changes made in between. To run every test again, run Vitest without the flag, or delete the cache with [`--clearCache`](#clearcache).

The flag requires [`cache`](/config/cache). Vitest throws an error if the cache is disabled.

::: warning

The modification time comes from the file system. A `git checkout` or an unpacked archive that sets old modification times is not detected. Files that a test did not load during its last run, for example a new `.env` file or a new `__mocks__` file, are not detected either. See [`experimental.recordDependencies`](/config/experimental#experimental-recorddependencies) for the full list of recorded files.

:::

See [Running Only Affected Tests](/guide/recipes/affected-tests) for a comparison with `--changed`.

- **Type:** `boolean`

title: Running Only Affected Tests | Recipes

A full run of a large suite is the right check before a merge, but it is slow feedback for a small change. If you edited one module, only the tests that load that module can change their result. Vitest has two flags that select those tests. They differ in one question: changed compared to what?

- [`--changed`](/config/changed) compares the working tree with a Git reference.

- [`--since-last-run`](/guide/cli#since-last-run) compares every file a test loaded with the time of the test's last run.

vitest run --changed # uncommitted changes, staged and unstaged

vitest run --changed HEAD~1 # the last commit and uncommitted changes

vitest run --changed origin/main # everything on this branch

Vitest asks Git for the changed files, then finds the test files that import them, directly or through other modules. A test runs when any file in its import graph is in the list.

The reference is the baseline, so the same command gives the same selection until the baseline moves. This fits checks that are defined in terms of Git: a pull request against `origin/main`, or a pre-push hook that covers the commits you are about to push. It requires a Git repository, and a change that is committed and merged stops being "changed", even if the tests never ran against it on your machine.

vitest run --since-last-run

The first run with `--since-last-run` runs every test and records the files each test loaded, including dynamic imports, mocks, setup files and snapshot files. Every later run compares the modification time of those files with the time of the run that recorded them. A test runs again when one of its files is newer or was deleted, or when the test has no record yet. A test file that failed in its last run also runs again, until it passes, even if the fix was outside the recorded files.

Each run updates the records of the tests it ran, so the baseline moves with you: after a run, only the next edit selects tests again. Git is not involved, so the flag works in a fresh container, in a worktree with an unrelated history, or in a directory that is not a repository. A new test file, or one that was never recorded, always runs.

The records live in the [cache](/config/cache). `vitest run --clearCache` deletes them, and the next `--since-last-run` run is a full run again.

| You want to run the tests affected by… | Use |

| ---------------------------------------------------------------------- | --------------------------------- |

| a branch, before opening or updating a pull request | `--changed origin/main` |

| the commits you are about to push | `--changed <upstream>` |

| your uncommitted edits, in a Git repository | `--changed` or `--since-last-run` |

| your edits since you last ran the tests, committed or not | `--since-last-run` |

| edits in a directory without Git, or with a history you do not control | `--since-last-run` |

`--changed` is the better fit when the baseline is shared with other people: the reference is the same on every machine and in CI. `--since-last-run` is the better fit when the baseline is your own last run: it does not matter whether you committed in between, or whether Git is there at all.

AI coding agents run tests after almost every edit. They often work in a container or a temporary worktree, commit in the middle of a task, and start a new process for every command. A Git baseline fits none of that: `--changed` is empty right after a commit, and it needs a repository. `--since-last-run` tracks what the agent actually ran, so each `vitest run --since-last-run` covers exactly the edits since the previous one, and the first command in a fresh environment is a full run that builds the records.

Tell the agent about it in the instructions file of your project:

```md [AGENTS.md]

- After a change, run `vitest run --since-last-run` to test only what the change affects.

- Before you finish, run `vitest run` once for the whole suite.

Two things the records cannot see: a file that no test loaded during the last run (a new `.env` file, a new `__mocks__` file), and modification times set in the past by a checkout or an unpacked archive. The full run at the end covers both.

- [`changed`](/config/changed)

- [`--since-last-run`](/guide/cli#since-last-run)

- [`experimental.recordDependencies`](/config/experimental#experimental-recorddependencies)

- [Test Filtering](/guide/filtering)

import type { Vitest } from './core'

import type { TestProject } from './project'

import type { TestSpecification } from './test-specification'

import type { ModuleDependency, ModulesResolver } from './vcs/vcs'

import { existsSync } from 'node:fs'

import os from 'node:os'

import { cleanUrl } from '@vitest/utils/helpers'

export class AffectedModulesResolver {

export class AffectedModulesResolver implements ModulesResolver {

private existsCache = new Map<string, boolean>()

private transformConcurrency = os.availableParallelism()

private activeTransforms = 0

private transformQueue: Array<() => void> = []

private related: string[] = []

// set while `getDependencies` walks the graph

walked: Set<string> | undefined

constructor(

private vitest: Vitest,

private related: string[],

private specs: TestSpecification[],

) {}

async resolve(specs: TestSpecification[]): Promise<TestSpecification[]> {

// the graph is only known after transforming it, so it is walked once without changes

async getDependencies(): Promise<ModuleDependency[]> {

this.walked = new Set()

await this.getAffectedSpecifications([])

const files = new Set(Array.from(this.walked, (id) => cleanUrl(id)))

this.walked = undefined

return Array.from(files, (file) => ({ file }))

}

async getAffectedSpecifications(related: string[]): Promise<TestSpecification[]> {

this.related = related

const specs = this.specs

if (this.dependsOnConfig(this.vitest.vite.config.configFileDependencies)) {

return specs

}

constructor(

private project: TestProject,

private environment: DevEnvironment,

private resolver: AffectedModulesResolver,

public resolver: AffectedModulesResolver,

) {}

getModule(id: string): Promise<ModuleNode | null> {

if (!node) {

return

}

this.graph.resolver.walked?.add(id)

node.watchedFiles.forEach((file) => this.graph.resolver.walked?.add(file))

// a file imported with a query is a separate module

if (node.failed || this.changed.has(cleanUrl(id))) {

this.changed.add(id)