Assertions are at the heart of every test—they capture your true expectations of the system. In this block, you’ll go beyond the basics: creating custom matchers and equality testers, improving failure messages for faster debugging, and expressing expectations toward eventual states in a more natural way.

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

Assertions Introduction

[00:00] Now that we've covered custom fixtures, it's time for us to talk about other ways to customize your test experience. And in this exercise block, you and I are going to focus on the most important part of any test. Assertions. In the heart of any assertion lies a matcher, a function that helps you describe your expectations. Functions like to be, to equal,

[00:19] to match object, to throw, and so forth. VTest already comes with a vast variety of built-in matchers that you can use, but you can also create your own. In fact, custom matchers is a great way to introduce the main specific requirements into your test suite. For example, if you're testing user authentication and it takes a few steps to determine if the user

[00:37] is in the right state, instead of repeating those steps in every test, you can introduce your custom matcher code to be authenticated and move all the authentication logic into that matcher. You're probably starting to notice a pattern here. Customizing your test experience helps you be both descriptive and declarative in your tests, as well as offload the complexity

[00:55] of a tested system to where it belongs in the test setup. And in addition to custom matchers, we're going to cover some of the ways to help you describe your expectations in tests, things like soft and attributable assertions, as well as custom equality testers. This is a lot of material, so I hope you're ready, and let's go!

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

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

Multiple Workspaces

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

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

Assertions Introduction

Transcript