vitest/references/features-filtering.md

---

name: test-filtering description: Filter tests by name, file patterns, and tags

---

Test Filtering

CLI Filtering

By File Path

# Run files containing "user"
vitest user

# Multiple patterns
vitest user auth

# Specific file
vitest src/user.test.ts

# By line number
vitest src/user.test.ts:25

By Test Name

# Tests matching pattern
vitest -t "login"
vitest --testNamePattern "should.*work"

# Regex patterns
vitest -t "/user|auth/"

Changed Files

# Uncommitted changes
vitest --changed

# Since specific commit
vitest --changed HEAD~1
vitest --changed abc123

# Since branch
vitest --changed origin/main

Related Files

Run tests that import specific files:

vitest related src/utils.ts src/api.ts --run

Useful with lint-staged:

// .lintstagedrc.js
export default {
  '*.{ts,tsx}': 'vitest related --run',
}

Focus Tests (.only)

test.only('only this runs', () => {})

describe.only('only this suite', () => {
  test('runs', () => {})
})

In CI, .only throws error unless configured:

defineConfig({
  test: {
    allowOnly: true, // Allow .only in CI
  },
})

Skip Tests

test.skip('skipped', () => {})

// Conditional
test.skipIf(process.env.CI)('not in CI', () => {})
test.runIf(!process.env.CI)('local only', () => {})

// Dynamic skip
test('dynamic', ({ skip }) => {
  skip(someCondition, 'reason')
})

Tags

Tags must be declared in config, then applied to tests/suites and filtered with a tag expression:

// vitest.config.ts
defineConfig({
  test: {
    tags: [{ name: 'db' }, { name: 'slow' }, { name: 'flaky' }],
  },
})

// test file
test('database test', { tags: ['db'] }, () => {})

vitest --tagsFilter "db && !flaky"
vitest --tagsFilter "unit || e2e"
vitest --list-tags            # show defined tags

Full syntax, priority, and per-tag options: see features-test-tags.

Include/Exclude Patterns

defineConfig({
  test: {
    // Test file patterns
    include: ['**/*.{test,spec}.{ts,tsx}'],

    // Exclude patterns
    exclude: [
      '**/node_modules/**',
      '**/e2e/**',
      '**/*.skip.test.ts',
    ],

    // Include source for in-source testing
    includeSource: ['src/**/*.ts'],

    // Scope discovery to a directory (faster than broad excludes)
    dir: './src',
  },
})

v4 simplified default exclude to only node_modules/.git. Prefer test.dir to limit where tests are found; spread configDefaults.exclude to restore the old excludes.

Watch Mode Filtering

In watch mode, press: - p - Filter by filename pattern - t - Filter by test name pattern - a - Run all tests - f - Run only failed tests

Projects Filtering

Run specific project:

vitest --project unit
vitest --project integration --project e2e

Environment-based Filtering

const isDev = process.env.NODE_ENV === 'development'
const isCI = process.env.CI

describe.skipIf(isCI)('local only tests', () => {})
describe.runIf(isDev)('dev tests', () => {})

Combining Filters

# File pattern + test name + changed
vitest user -t "login" --changed

# Related files + run mode
vitest related src/auth.ts --run

List Tests Without Running

vitest list                 # Show all test names
vitest list -t "user"       # Filter by name
vitest list --filesOnly     # Show only file paths
vitest list --json          # JSON output

Key Points

• Use -t for test name pattern filtering
• --changed runs only tests affected by changes
• --related runs tests importing specific files
• Tags provide semantic test grouping
• Use .only for debugging, but configure CI to reject it
• Watch mode has interactive filtering