references/perf-disable-isolation.md
GitHubDisable Test Isolation When Safe
By default, Vitest runs each test file in an isolated environment. This ensures tests don't affect each other but adds overhead. For projects with proper cleanup, disabling isolation speeds up execution significantly.
Default (full isolation):
// vitest.config.ts
export default defineConfig({
test: {
// Default - each file runs in fresh environment
isolate: true,
},
})
Optimized (disabled isolation):
// vitest.config.ts
export default defineConfig({
test: {
// Faster - files share environment
isolate: false,
},
})
Prerequisites for disabling isolation:
- Tests properly clean up after themselves
- No global state modification without restoration
- All mocks are restored in afterEach
- No test relies on being the first/only test in the environment
Hybrid approach with projects:
// vitest.config.ts
export default defineConfig({
test: {
projects: [
{
// Unit tests - safe to share environment
name: 'unit',
include: ['src/**/*.test.ts'],
isolate: false,
},
{
// Integration tests - need isolation
name: 'integration',
include: ['tests/integration/**/*.test.ts'],
isolate: true,
},
],
},
})
CLI usage:
# Quick test with isolation disabled
vitest --no-isolate
# Check for tests that depend on isolation
vitest --no-isolate --reporter=verbose
When NOT to disable isolation:
- Tests modify global state without cleanup
- Tests use
vi.mockat the module level withoutvi.resetModules - Tests have known order dependencies
Benefits:
- Faster test suite execution
- Reduced memory usage
- Quicker feedback loops
Reference: Vitest Improving Performance