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

Filter by custom tags:

test('database test', { tags: ['db'] }, () => {})
test('slow test', { tags: ['slow', 'integration'] }, () => {})

Run tagged tests:

vitest --tags db
vitest --tags "db,slow"      # OR
vitest --tags db --tags slow # OR

Configure allowed tags:

defineConfig({
  test: {
    tags: ['db', 'slow', 'integration'],
    strictTags: true, // Fail on unknown 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'],
  },
})

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

<!-- Source references:

• https://vitest.dev/guide/filtering.html
• https://vitest.dev/guide/cli.html

-->