Configure Vitest with multiple workspaces to separate unit tests and edge tests, each running in the right environment.

Set up Vitest with unit and edge workspaces, using node and edge-runtime environments, to test different layers of your app.

Multiple Workspaces Solution

[00:00] Let's start by defining multiple projects in VTest, one for our unit tests and another for our edge function tests. To do that, head to your VTest configuration, and in this test object, add a new property called projects. Assign it an empty array as a value, for now. You might have

[00:16] used a different property before here called workspace, and while it will still work in the current version of VTest, it's being deprecated, so highly recommend to use the projects property instead from now on. Luckily, the value to these properties remains the same, and you can provide a combination of different things to this array. You can provide an inline VTest configuration,

[00:36] this is something that we're going to use right now, and you can also provide a path to a VTest config, maybe if it's nested somewhere like this. Alternatively, you can provide a whole pattern here. For example, if you're in a monorepo, you can specify that VTest should look up

[00:50] nested VTest configurations matching this pattern. This is really handy. So, for now, let's define inline configuration for our unit tests. Provide the test key again, because we are defining our configuration from the root. Give it a distinct name, unit. Specify that we're going to use globals

[01:06] here, and provide environment as node. Now, the only thing remaining is to tell VTest which files should be considered unit tests. In other words, which files should belong to this project. You can do that by providing the include property, and here you can provide file patterns to match. So,

[01:22] let's say that all tests ending in .test.ts will be considered a part of our unit project. In a similar manner, let's define VTest configuration for our edge function tests. I will copy this object and give it another name, so let's call it edge. We'll still use global functions like test

[01:38] and expect. The environment, though, will be different. We will use a custom environment called edge runtime that we will install in a second, and the pattern will be different as well. We will target tests ending on .edge.test.ts, and once you do, you can spot that this pattern

[01:55] actually will include this one as well. So, our tests will overlap, and that's not very nice. To fix that, let's go to the unit test here, which has a more permissive pattern, and provide the exclude area explicitly, because the options you provide here in your configurations

[02:09] are taken as is. You can merge them with the root level options by providing the extend property here, but you can also be explicit and have every project self-contained. So, to exclude this, we'll simply provide this edge test pattern over here, and there's just one tiny catch.

[02:26] Because of this explicitness that I mentioned, VTest will not merge any of these properties with VTest defaults. So, for example, if you run unit tests right now, it may accidentally pick up tests matching this pattern from your not module directories, and that's not nice.

[02:40] And to fix that problem, head to the VTest slash config import, and import config defaults object. This object contains all the default values for VTest configuration, and now you can go to this exclude pattern for unit tests, and spread the value of config default slash exclude.

[02:58] So, this exclude here will contain the different exclude patterns that VTest has, for example, for not modules. And now, this concludes the definition of these two separate projects. So, to summarize quickly, what we have is, in our tests, we have projects, which is an array of different VTest projects, one for unit tests, and another for edge function tests. Now that we have

[03:18] this defined, it's time for us to configure this edge runtime environment, so these edge function tests can even run. I'll open my terminal and run npm install, and install all the packages necessary for my edge function tests. Now, this completes the test setup, so it's time for us to write the

[03:33] tests themselves. Let's do the unit tests first. So, in this slugify.test.ts test for the slugify function, I will create a new test case, call it returns a slugified string, and use this slugify function as I expect. So, if I provided a string with a space, for example, over here, I expect

[03:51] the return result to be hello world, where the space gets replaced with a dash, which is very common when you slugify strings in JavaScript. And now to the edge function tests. So, the request handler function I have here runs in an edge runtime, and in order for me to test it reliably, I need to replicate that environment in my tests as well. That's why we installed all of those

[04:10] dependencies before. I can head to the test file at handler.edge.test.ts and do a few things related to the test setup first. So, I'm going to import from edge runtime package the class called edge runtime. Then, I will create a variable called runtime that will be instantiation of this class

[04:27] new edge runtime. And here, I need to provide the code to execute in this special edge runtime environment. For this, I will import my code from the function, from this handler that I want to test, and I will add ?raw, which will use the raw loader in VTest to load this module as string,

[04:46] basically to load the content of that module instead of the expert that that module has. And I will name it initial code and provide here as a shorthand property like this. Now, I'll create a simple test case called returns user by id, make it a promise, and orchestrate

[05:04] my test like this. So, what's happening here is I'm using this runtime object to call dispatch fetch methods, which is a special method to perform a fetch request within that edge runtime, and then I'm just getting the response back and asserting on that response, making sure that the

[05:18] JSON body of this response equals to the object that I'm returning from my edge handler over here. And this concludes my edge test case, as well as my unit test cases. Let's run those projects right now through the CLI. So, we can open the terminal, and just as normal, we would run npm test,

[05:35] which runs the VTest command, and you can see that it prints the results of both of these projects. First, here is the unit project with our slugify test and the edge project with our handler test. This is very handy to run all our projects at the same time, but you can also run a specific project in isolation. If you use the Vita CLI and then provide it with the option project and

[05:55] specify the project name, for example, unit, this will only run the unit test, which you can see in the test report. And in the same way, you can provide a different name, for example, edge to run our edge handler tests, and here we have the results as well.

Multiple Workspaces

[00:00] VTest is a versatile test runner, and you can use it for many things. You can have your unit tests running in VTest, also your integration tests. We've explored how to run your React component tests in the actual browser, straight from VTest using its browser mode feature, and so on. And all of those different use cases have different requirements.

[00:18] Your unit test environment might be Node.js, but once you're running your React tests, they will run in the actual browser. Your integration tests may require a different environment as well. So basically, it means you need to approach all of those use cases differently. And VTest helps you do that through the feature called workspaces, or projects.

[00:35] In this exercise, you will explore that feature, because the app you have to test has two layers of tests, unit tests, but also integration tests for the edge functions that live in your app. And those edge functions need a special environment to run reliably. So follow the instructions, define two different workspaces for unit tests and for the edge

[00:53] integration tests, with their own requirements, and then complete the test cases to have them passing.

Do you know this feeling when a tool “clicks”? When you suddenly become so comfortable with it that it’s no longer just a means to an end but an instrument to craft better experiences for yourself. Over the past decade, that transition has happened with a bunch of tools for me.

Today, I want it to happen for you with Vitest.

In this workshop, my goal is to make you a Vitest superuser. And that means stepping beyond the basics and into the advanced. That means getting so good at Vitest that you would feel confident crafting custom test experiences, understanding the inner works of your test runner, and equipping that knowledge to solve everything from complexity issues to poor test performance.

Welcome to the Advanced Vitest Patterns workshop!

## What You’ll Learn

The overarching theme of this workshop is ***customization***. I believe your experience with tools is defined by how well you understand them and how comfortable you are when it comes to customizing them. With this workshop, I’ve collected some of the best techniques and pieces of advice to make you a true Vitest superuser.

I’m also taking this workshop as an opportunity to teach you the importance of the test setup. Throughout the exercises, you will be crafting your own test experience through things like custom fixtures, matchers, and equality testers. This will help you orchestrate tests for complex, real-world applications.

### Setup

In the first block, you will get more comfortable with Vitest. From writing and debugging tests faster with the Vitest’s extension for Visual Studio Code, to configuring and visually exploring code coverage and setting up multiple test projects to use your test runner to the fullest.

### Context

You will learn how to customize your test experience by creating *custom fixtures*. Discover the fixture syntax, its life-cycle, and how to implement them in a type-safe way. Then, note down the best practices of fixture design to make sure your custom fixtures eradicate complexity, not introduce it.

### Assertions

Following the topic of customization, find out how you can supercharge your assertions. First, you will create your own matchers to help express your expectations toward your tested app and make your tests read like human language. Then, explore what is an equality tester and how you can teach the Vitest’s built-in `.toEqual` matcher to compare the incomparable.

Nail down how to write assertions for eventual states with `expect.poll` and become in full control of how much information you get out of failed assertions by understanding the balance between the hard and soft assertions.

### Performance

And yes, I’ve saved the best for last. Performance.

Learn how to profile slow test runs using built-in metrics in Vitest as well as the `vitest-profiler-plugin`. You will read the CPU and heap profiles, understand what they mean, and how you can use them to hunt down the problematic areas of your tests.

Everything past this point is techniques to make your tests faster. **We are talking up to x40 times faster** (that’s not a typo). Take a peek behind the scenes to see how Vitest orchestrates test runs and what defaults it has in place to ensure reliable results. Go through the difference between parallelization and concurrency in tests, explore the effects test isolation has on performance, and learn how to split your tests into shards for faster CI/CD jobs.

## Who Is This Workshop For

This workshop is for all developers who want to learn how to customize Vitest to create better, custom test experiences on top of it. For everyone who has felt like adding a new test in your project feels like fighting against the entire world. For everyone who has found themselves lost before a slow test suite.

As the name suggests, you will be going through advanced topics, which makes a prior basic experience with Vitest mandatory to get the most out of these exercises.

Learn advanced Vitest patterns—custom fixtures, matchers, and performance tuning—to craft faster, more effective test experiences.

Advanced Vitest Patterns 

Artem Zakharchenko

Advanced Vitest Patterns

Writing tests for their own sake is a pointless chore:

```tsx
describe('add numbers', () => {
  it('should add two numbers', () => {
    expect(add(1, 2)).toBe(3)
  })

  it('should add two other numbers', () => {
    expect(add(3, 4)).toBe(7)
  })
});
```

Another annoying testing problem is when tests are too brittle, and paint your logs red even though the application seems to work just fine.

When your tests lack real purpose or seem to fail for no good reason, it's no wonder you start to question their value.

Tests are supposed to give you confidence in your code, and save you from shipping broken stuff to prod. So why does writing them feel like such a burden?

The problem is that tests like these are focused on implementation details instead of the underlying behavior. Everyone talks about the importance of testing, but there's a lack of understanding about how to write tests that are actually useful.

How would it feel to have 100% trust in your tests, knowing that any failures are not a false alarm? What if you could seamlessly translate the underlying behavior of your application into tests that are easy (and even fun) to write?

It's possible, but it requires you to take a step back from just syntax.

In order to have the confidence you're testing the right things in the right ways, you need to dig into the underlying patterns behind the scenes of a testing framework.

This is exactly what you will do in Testing Fundamentals.

In this workshop, Artem Zakharchenko, testing expert and creator of the Mock Service Worker API mocking library, will guide you through creating your own version of the Vitest testing framework.

Building a testing framework from scratch will give you a deep understanding of how the pieces fit together, and change the way you think about testing for the better.

## What You'll Learn

The workshop is broken out into four parts, each with its own challenges and exercises that build upon the last:

### Principles

First, you'll explore the principles and mental models that underlie testing strategies. This is where you will begin to distinguish between the intention of your code and its implementation details. When you focus the intention of what your code should accomplish, you can write tests that are more resilient to change.

### Test Structure

Next, you'll do a deep dive into the structure of the testing framework. You'll create your own `expect` and `test` functions, configure your test environment, and use hooks to manage side effects in your tests.

### Testing Asynchronous Code

Testing asynchronous code requires a slightly different approach when compared to testing synchronous code. Here you'll practice with testing promises and async functions, as well as handling errors and rejections.

### Moving to Vitest

Once you've learned the fundamentals of testing and built your own mini-framework, you will migrate your tests to the Vitest framework. This process will cement your understanding of not just the "hows", but also the "whys" of testing.

## Who This Workshop Is For

This workshop is for developers who have some testing experience, but feel like they're missing the bigger picture. If you're tired of writing tests that feel like a chore, and want to understand how to write tests that are actually useful, this workshop is for you.

Testing Fundamentals

Let’s face it, mocking can be really confusing.

First, you need to know what to mock. Then, find the right way to mock that thing so it doesn’t compromise your test suite. Over-mock, and your tests become pointless. Under-mock, and they get brittle instead.

In either case, you put in so much effort, and you don’t feel like you’re getting much in return.

This is where Artem comes in. He’s been proving developer misconceptions around mocking wrong for nearly a decade, and he’s here to make you a mocking pro.

## What You’ll Learn

In this hands-on workshop, you’ll learn:

- The purpose of mocking;
- What to mock and when;
- How to write mocks that bring value instead of being a maintenance chore;
- How to separate your mocks from implementation details;
- Type safety strategies for your mocks;
- And **all the mocking techniques** you will need to test your code!

By solving targeted, real-world problems using the Vitest framework, you’ll gain a comprehensive understanding of mocking and finally unlock it as a useful tool in your testing arsenal.

## Workshop Structure

This workshop contains 6 exercise blocks dedicated to various techniques on mocking different data types.

### Boundaries

Understand what mocking really is, and learn how it helps you create test boundaries. See what each mock you introduce does to your tested code using visual metaphors.

### Mocking Functions

Functions are at the heart of JavaScript logic. Learn how to mock functions for effective input-output testing. Create mock functions, spy on function calls, and mock function implementation to tap into the right behaviors of the tested code.

### Mocking Date and Time

Eliminate the side effects of ever-changing date and time in your tests. Learn how to freeze time and mock date/time-dependent code to ensure consistent test results across different runs and time zones.

### Mocking Globals

Explore how to mock implicit dependencies, in a non-intrusive way. Learn to mock global values, methods, and environment variables to create the perfect test setup without meddling with things you don't own.

### Mocking Network

Gain control over network communication and test your client-side code reliably. Intercept requests and mock responses using Mock Service Worker. Reproduce various network scenarios, from success and error responses to offline behavior and response timing.

### Mocking Modules

Understand when to use module mocking and explore alternative techniques before you do. Learn how to mock modules in a type-safe and efficient way using built-in APIs in Vitest.

## Who This Workshop Is For

This workshop is meant for all developers, both those who are new to automated testing and those who’ve been writing tests for years. If you are unsure when to introduce mocks into your test suite, or how to do that so you don’t have to refactor it the next day, this workshop was made specifically for you.

Mocking Techniques in Vitest

The closer your tests resemble how your software is being used, the more confidence they will give you. There’s so many great patterns stemming from this simple rule, patterns I’m sure you’re already using to write better tests.

Then, there’s the elephant in the room. **Your test environment.**

For decades, web developers have been testing their UIs in make-believe environments that are neither the browser nor Node.js. It made them come up with a frankly ridiculous amount of test setup, polyfills, and workarounds just to make it work. Remember when you had to mock `location` in tests? `window.matchMedia`? Yeah…

It’s time to abandon such practices. The tools have improved and there’s no excuse for you to be sleeping on it. It’s time for you to learn how to use Vitest Browser Mode for in-browser component testing!

## What You’ll Learn

In this workshop, you will learn a new approach to component testing that’s both different and the same. It is different because you will write and run your tests in the actual browser, taking advantage of the standard APIs and powerful browser automation. It is the same because it’s still the component level test you know and love, with rendering, querying, and asserting. 

Your users don’t interact with the UIs you build in JSDOM. They do that in the real browser, and now your tests will too!

### **Sunsetting JSDOM**

The first step in our journey is understanding why browser-like environments fall short. JSDOM has served us well, but it's time to recognize its limitations. You'll experience firsthand how browser-like environments like JSDOM are letting you down.

We'll explore examples of valid JavaScript code that works perfectly in browsers and Node.js but fails in JSDOM, undermining the value of the tests you work so hard to write. You'll discover why these inconsistencies happen and why moving to real browser testing is the solution.

### **Vitest Browser Mode**

Vitest Browser Mode allows you to run isolated component-level tests in the actual browser while providing the convenience and flexibility of integration-level testing. It's not a full end-to-end testing framework like Playwright or Cypress, but rather the perfect middle ground for component testing.

In this module, you'll learn:

- How to install and configure Vitest Browser Mode in your project;
- The technical differences between how JSDOM and Browser Mode run your tests;
- Steps needed to migrate existing JSDOM tests to Browser Mode;
- How to set up Playwright as the browser automation provider for your component tests;
- Common setup scenarios like applying global assets in tests and configuring Vitest for both unit and component-level testing within the same project.

### **Best Practices**

Choosing the right tools is important, but knowledge that transcends any particular tool is even more valuable. In this section, we'll focus on five key areas of best practices when it comes to testing your React components:

- **Queries**: Find elements on the page the same way your users or their assistive technology would;
- **User events**: Interact with the tested elements from the user’s perspective;
- **API mocking**: Use Mock Service Worker to intercept requests and handle their responses as well as discover how to efficiently use MSW in Vitest Browser Mode by creating a custom test context;
- **Element presence**: Test elements that should (or shouldn't) appear on the page reliably without false positives or flaky results.
- **Page navigation**: Learn where to draw the line when testing page transitions and routing in the actual browser.

### **Debugging Tests**

The true value of tests comes when they fail. But dealing with failing tests can be quite frustrating without the right techniques.

In this block, you'll learn some of my favorite debugging techniques that go well beyond console logging:

- How to inspect the DOM state at any point in test;
- Using the debugger statement to stop JavaScript execution entirely;
- Wielding conditional breakpoints to step through the problematic code.

These techniques will transform your approach to test failures from dread to confidence so the next time you see a failing test you will know what to do.

## Who Is This Workshop For

This workshop is for all React developers who want to write reliable and valuable tests for their components. Whether you're new to component testing or have been writing tests for years, you will inevitably learn new tools, APIs, and techniques to gain more value out of your test suite. That’s my sole motivation behind this material.

React Component Testing with Vitest

The Testing Bundle

Learn advanced Vitest patterns: IDE setup, multi-project config, custom fixtures, matchers, profiling, and speeding up slow test suites.

Advanced Vitest Patterns Introduction

Workshop Introduction

Boost your productivity in Vitest with IDE integration and smart config options that streamline writing and running your tests.

Setup Introduction

Set up the Vitest extension in VS Code to view, run, and debug tests directly in the editor for a smoother testing workflow.

Run tests inline, watch them continuously, and debug failed cases in VS Code with the Vitest extension for faster feedback.

Visual Studio Code extension solution

Visual Studio Code extension

Enable and configure code coverage in Vitest with the v8 provider to review test gaps and identify untested parts of your code.

Enable code coverage in Vitest with the v8 provider, generate HTML reports, preview in Vitest UI, and spot untested code paths.

Code Coverage Solution

Code Coverage

Take a short break before we dive into customizing the test context and extending Vitest to better fit your workflow.

Setup Outro

Setup

Learn how to use custom fixtures in Vitest to hide setup complexity and make your tests read like simple, focused scenarios.

Context Introduction

Extend Vitest with custom fixtures like createMockCart() using Faker to generate test data and simplify cart total calculations.

Learn how to extend Vitest with custom fixtures like createMockCart, using Faker for mock data and best practices for test design.

Custom Fixtures Solution

Custom Fixtures

Make Vitest fixtures run automatically by disabling lazy initialization—useful for global setups like mocked databases or APIs.

Enable automatic Vitest fixtures with auto: true to ensure setup and cleanup always run—ideal for mocks like databases or APIs.

Automatic Fixtures Solution

Automatic Fixtures

You’ve built custom fixtures and improved your test setup. Next up: assertions, matchers, and equality testers.


Context Outro

Context

Assertions define your expectations. Learn to write powerful matchers, clearer failures, and handle complex states with ease.

Assertions Introduction

Use custom Vitest matchers like .toMatchSchema() to validate data against Zod schemas, reducing test boilerplate and improving clarity.

Create custom Vitest matchers like .toMatchSchema() with Zod for cleaner, type-safe tests and extend expect directly in setup.

Custom Matchers Solution

Custom Matchers

Learn how asymmetric matchers work in Vitest and extend types so custom matchers like .toMatchSchema() are recognized by TypeScript.

Extend Vitest types to support .toMatchSchema() as an asymmetric matcher and validate nested objects like users in transactions.

Asymmetric Matchers Solution

Asymmetric Matchers

Implement a custom equality tester in Vitest to compare values like measurements semantically instead of relying on strict object equality.

Extend Vitest’s .toEqual() with custom equality testers, like comparing Measurement instances by semantic value instead of raw objects.

Custom Equality Testers Solution

Custom Equality Testers

Use Vitest’s expect.poll() for retryable assertions, replacing vi.waitFor() to test eventual asynchronous states more cleanly.

Replace vi.waitFor() with Vitest’s expect.poll() to write clearer retryable assertions for eventual async states in tests.

Retryable Assertions Solution

Retryable Assertions

Use soft assertions in Vitest to run multiple checks without stopping at the first failure, giving fuller feedback when debugging tests.

Use expect.soft() in Vitest to run multiple assertions without stopping at the first failure, giving fuller insight into test failures.

Soft Assertions Solution

Soft Assertions

You’ve mastered custom matchers and smarter assertions. Next up: test performance—let’s see what makes tests fast or painfully slow.

Assertions Outro

Assertions

Slow tests drag teams down. Learn how to profile Vitest runs, spot performance bottlenecks, and make test suites run faster.

Performance Introduction

Profile slow Vitest tests with vitest-profiler to identify performance bottlenecks and analyze which parts of execution take the most time.

Use vitest-profiler to generate CPU and memory profiles of your test suite, spot slow functions, and identify performance bottlenecks.

Profiling Slow Tests Solution

Profiling Slow Tests

Speed up large Vitest suites by enabling concurrency so multiple test cases run at the same time instead of sequentially within each file.

Run Vitest tests concurrently with test.concurrent to speed up large suites, configure maxConcurrency, and avoid shared state flakiness.

Concurrency Solution

Concurrency

Disable test isolation in Vitest to avoid spawning a new worker per file and reduce overhead when running hundreds or thousands of test files.

Turn off test isolation in Vitest to cut worker overhead and speed up large suites, but beware of shared state risks and possible flakiness.

Isolation  Solution

Isolation

Split large Vitest suites into shards to run tests across multiple processes or CI jobs, reducing runtime and handling thousands of cases.

Run Vitest with --shard and --reporter=blob to split large suites across processes, then merge reports for a single test summary.

Sharding Solution

Sharding

You’ve completed the performance block. Now you can profile Vitest, understand its processes, and make smarter trade-offs for speed.

Performance Outro

Performance

You’ve finished the Advanced Vitest Patterns workshop. From fixtures to performance, you now have a stronger testing toolkit.

Advanced Vitest Patterns

Advanced Vitest Patterns

Transcript

Multiple Workspaces

Transcript