Feature Request: support network mocking

[sheremet-va]

Clear and concise description of the problem

We want to support a unified network mocking mechanism in Vitest: both in Node.js and in the browser. This is a pain point that a lot of projects face, having to resort to third-party solutions. We even have a documentation page about network mocking.

Suggested solution

MSW is an industry standard in network mocking. If we ever have this feature, we should follow the same API. I want to propose these drafts based on MSW implementation:

// having all utilities in `vi`
import { vi } from 'vitest'

const networkMocker = vi.setupNetworkMocker(
  vi.http.get('/response', () => new Response(null, { statusCode: 404 }),
)
await networkMocker.start()

// having all utilities in `vitest/network`
import { http, setupNetworkMocker } from 'vitest/network'

const networkMocker = setupNetworkMocker(
  http.get('/response', () => new Response(null, { statusCode: 404 }),
)
await networkMocker.start()

// split utilities between different places
import { http } from 'vitest/mock-http'

 // if we every support graphql, it should not be exposed form the same entry point for types support
import { graphql } from 'vitest/mock-graphql'
import { vi } from 'vitest'

const github = graphql.link('https://api.github.com/graphql')

const networkMocker = vi.setupNetworkMocker(
  http.get('/response', () => new Response(null, { statusCode: 404 }),
  github.query('GetUser', oneResolver),
)
await networkMocker.start()

The naming is not final as is the API.

As a rule, we want MSW's handlers to be supported out of the box, so this is also valid:

import { http } from 'msw'
import { vi } from 'vitest'

const server = vi.setupNetworkMocker(
  http.get('/response', () => new Response(null, { statusCode: 404 }),
)

Alternative

No response

Additional context

MSW has @mswjs/interceptors package that we can use.

Having network capabilities built-in, we can also expose config option like networkMockingReset that would reset handlers after every test (enabled by default).

We could also keep the mocker in memory and enable/disable it automatically without the need to specify beforeAll/afterAll hooks.

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that requests the same feature to avoid creating a duplicate.

[kettanaito]

Hi! Thanks for adding me in.

The unified network mocking interface across Node.js and the browser is literally the mission behind MSW. I think we should align our efforts here to produce a solution that would benefit the developers, and I don't believe that solution should be tired to Vitest.

Before I dive into what's been happening in the MSW world, I'd like to ask you:

• What prevents you from adopting MSW directly?

Be as detailed as you feel comfortable. I genuinely want to know and see if your pain points would resonate with my pain points. Thanks.

MSW direction

In the upcoming weeks, I'm going to release mswjs/msw#2650. It's a complete internal rewrite of MSW and the introduction of something I call the network source architecture. The library is now implemented on primitives like a network source and a network frame, allowing for more customization while leveraging the same predictable request resolution algorithm that's been powering it for almost a decade now.

I think this is highly relevant in regards to what you're trying to achieve for the following reasons:

• The defineNetwork() API introduces a unified public-facing API for controlling your mocks. We maintain setupServer/setupWorker for compatibility, but the way forward is this (highly inspired by Vite and Vitest, by the way).
• The concept of a network source makes it easier to use MSW APIs in environments otherwise unsuitable for it. Playwright is a good example and the reason why we built @msw/playwright. Its page.route API can now be a network source for MSW to digest and route through the handlers, similarly to how the setupServer and setupWorker APIs have been implemented on top of the new architecture (highly recommend looking into that).

This change allows for customization without imposing the cost on the consumer. The same handlers, the same APIs, but what yields the network frames is up to you now.

Also worth mentioning that in the ideal world, I would love for something like msw@4 to get rid of the setupWorker/setupServer APIs altogether. I've been dreaming about a single entry API for the developer, but it's tricky to achieve. Guessing their environment is never reliable. But, perhaps, in the future their experience will turn into something more like this:

import { defineNetwork } from 'msw'
import { sources } from 'msw/node'

const network = defineNetwork({ sources })
await network.enable()

Where the swappable piece is the network sources, not the public API itself. So the need for different setup* APIs is gone and the user adapts to the environment by choosing the appropriate sources presets or building their own.

I'm also considering a higher-level API for building your own setup* functions on top of defineNetwork. I don't know how viable that is yet.

Interceptors

A fundamental change is coming to Interceptors: socket-based interception (see mswjs/interceptors#770). We tap at the socket level, each interceptor pipes the packets through a respective parser, decides if those packets are relevant, then handles or doesn't handle them. This is the most advanced interception algorithm that anybody will ever build for Node.js. It literally intercepts the network right before the C++ bindings for the network code. Nowhere lower to go unless one wishes to compile and use their custom version of Node.js.

I share in your decision to use Interceptors. A insane amount of work has been put into it and more tools should benefit from that (like Nock does, for example, where they've adopted Interceptors last year). That being said, it's also the most technically advanced project I've ever worked on, requiring deep Node.js knowledge and tackling rather obscure issues, at times. This might be a good layer for us to collaborate as I can always use some help there.

How does this benefit Vitest

The dream that started MSW was consistent network handling across different tools. If you share that dream with me, it is crucial we don't introduce proprietary APIs when it comes to API mocking in Vitest. Developers are already familiar with MSW, the library ships world-class DX, promotes and is built on web standards, has the richest feature set you can find. It's also maintained by this guy who knows exactly what it should or should not be, for what is worth.

Here's what I recommend.

1. Adopt the defineNetwork API or its derivative.

const network = defineNetwork({ sources, handlers })
await network.enable()
network.use(...handlers)
await network.disable()

This is going to be useful for Vitest internals more than its public APIs, I imagine. defineNetwork is meant for customization, but it's a bit repetitive if you ask the user to use it. The user expects something like setup* that they provide with handlers and then control in their tests.

Please note that the new architecture is releasing as experimental and while MSW is already rewritten with it, nothing here is set in stone. I welcome your feedback and any suggestions to improve. In fact, having Vitest as one of the early external adopters of this architecture could affect how it develops and matures a lot!

The network source architecture is environment-agnostic. Environmental specificity is handled in the network sources (see ServiceWorkerNetworkSource or InterceptorNetworkSource as the example). This sounds exactly what Vitest aims to achieve.

2. Keep the handlers contract. Benefit from http, graphql, and ws namespaces.

3. Decide on what Vitest is responsible for in the context of network interception and see any potential areas where relying on MSW would ease your responsibilities. I mean this in the best faith possible. All I want is a great DX for developers mocking APIs in their tests.

Historically, shipping MSW as a part of Vitest has been problematic. I have to point out here that those problems mostly stemmed from the worker side of things. I do not believe using msw/node would have any of those issues. It's a slim DX layer on top of Interceptors, and I would rather Vitest reused that than becoming another slim layer on top of Interceptors.

In the browser, the new architecture allows you to swap ServiceWorkerNetworkSource with anything else of your choosing if the worker script proves problematic to manage, but still expose the same setup* API to the developer.

Closing thoughts

I'm blabbering too much. Would be great to hear your answer to my question and your thoughts on everything I said above. I would be grateful to collaborate on this feature and ship the best experience that we can.

[kettanaito]

Based on your initial proposal above, all those APIs are already what defineNetwork does. I don't see much reason for Vitest to ship that. The main challenge here is to understand whether Vitest is planning on building extra behaviors on top of what MSW does, whether it needs any layer of abstraction at all, and how to leverage MSW in regards to different camps of users—those using it already, and those not using it.

And the answers to those questions will branch the approach here.

1. Vitest ships custom behaviors: use defineNetwork under the hood to stay compatible with MSW while extending whatever you need.
2. Vitest doesn't need custom behaviors, only to integrate the pieces correctly into the test runner: accept the defineNetwork result directly/indirectly or any other DX we find appropriate (e.g. Vitest can export defineNetwork similarly to how it re-exports defineConfig from vite).