|
1 | 1 | # Test isolation |
| 2 | + |
| 3 | +By default, Vitest runs each test file in an isolated environment (a worker, a forked process, or a VM context). That is a sensible default to make sure that no state gets leaked between test files and also make it a bit easier for you to orchestrate test setup as you don't have to worry about the entire test suite at once, just a single test file at a time. |
| 4 | + |
| 5 | +That being said, test isolation comes with a cost as spawning workers and processes takes time. Depending on the size of your test suite, that time can range from unsubstantial to quite drastic. That is why sometimes disabling test isolation can speed up your test run. |
| 6 | + |
| 7 | +<callout-warning>I am obligated to remind you that, much like concurrency, disabling test isolation is _never a solution to a problem_. It's a change in how your testing framework runs, and it often requires you to adjust your tests in order to benefit from it.</callout-warning> |
| 8 | + |
| 9 | +## When to disable test isolation? |
| 10 | + |
| 11 | +As with concurrency that we've covered previously, turning off test isolation is a conscious choice that comes with a price. It is worth mentioning that when I talk about disabling isolation, I only refer to _changing how Vitest runs your test files_. In other words, it's about telling Vitest _not_ to spend time dealing with workers/forks/vms when running tests. |
| 12 | + |
| 13 | +**When you disable test isolation, you're telling Vitest, "_It's alright, I've got the isolation covered myself_."** Isolation as a characteristic of your test suite is _mandatory_ for reliable and trustworthy testing. That is precisely why Vitest comes with isolation built-in—to help you write self-contained, independent tests. You don't need Vitest's test isolation to do that, it just makes it simpler. |
| 14 | + |
| 15 | +Isolation is the overarching theme when it comes to test performance. Reliable test runs cannot be achieved without properly isolated tests. This puts a similar list of criteria for disabling test isolation as we had for enabling concurrency: |
| 16 | + |
| 17 | +- Self-contained, independent tests; |
| 18 | +- Limited or properly managed side effects; |
| 19 | +- Carefully arranged test setup. |
| 20 | + |
| 21 | +This also means that you can benefit from correctly written tests in more ways than one. You can make them concurrent _and_ stop paying extra time for built-in isolation in Vitest since you've got it covered already. |
| 22 | + |
| 23 | +> I firmly believe that while right decisions are hard, one right decision leads to two right decisions, and so on. |
| 24 | +
|
| 25 | +### Reading metrics |
| 26 | + |
| 27 | +Since disabling test isolation is an effort, you have to know if it's the said isolation that contributes to your tests being slow. |
| 28 | + |
| 29 | +TODO: |
| 30 | + |
| 31 | +- How do I know that it's test isolation that takes significant time? Is it displayed in some metric in Vitest? |
| 32 | + |
| 33 | +## Disabling test isolation |
| 34 | + |
| 35 | +You can disable test isolation in Vitest by setting the `test.isolate` option to `false` in your Vitest configuration: |
| 36 | + |
| 37 | +```ts filename=vitest.config.ts highlight=3 |
| 38 | +export default defineConfig({ |
| 39 | + test: { |
| 40 | + isolate: false, |
| 41 | + }, |
| 42 | +}) |
| 43 | +``` |
| 44 | + |
| 45 | +> Alternatively, you can also provide a `--no-isolate` option to the Vitest CLI. |
| 46 | +
|
| 47 | +--- |
| 48 | + |
| 49 | +--- |
| 50 | + |
| 51 | +**TODO: Showcase the impact of disabling test isolation.** |
| 52 | + |
| 53 | +--- |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +## Related materials |
| 58 | + |
| 59 | +- [Test isolation](https://vitest.dev/guide/improving-performance.html#test-isolation) |
| 60 | +- [`test.isolate`](https://vitest.dev/config/#isolate) |
0 commit comments