Improve documentation

[nzakas]

I just recently started using MSW, and I found the documentation to be difficult to follow. I have some suggestions on how to improve things:

Getting Started

I wanted to set up a fake server for testing a Node.js project. I was surprised that I couldn't find a complete example anywhere on the site. To understand better, this is what I did my first time trying to use MSW:

1. Go to Getting Started
2. Step 1: Install. Easy enough, done!
3. Step 2: Write network behavior. My options are "Intercepting requests" or "Mocking responses". So I choose "Intercepting requests".
4. Intercepting requests. Hmmm, I see how to define interceptors, but I don't see anything about how to use them. The examples have either http.get (for example) at the top level or are exporting a handlers variable. Both don't make sense without the context of how they're used, which I still have not encountered. I don't know what to do with any of this information. So I go over to "Mocking responses".
5. Mocking responses. No complete examples here either. At this point I'm getting frustrated.
6. Step 3: Integrate your environment. I know I want to use MSW in Node.js, so I click on that.
7. Node.js integration. Okay, so now I see how to set up a server! But what is ...handlers and where are they defined? Where are the interceptors? Where do they go in the server? Lost, I go back to Getting Started and click on "Usage Examples"
8. Usage Examples. A GitHub repo, this looks promising! But where is the simple "getting started" example? I'm not using any of these frameworks, so I'm not sure where to go.

At this point, I have not found a single complete example in one place. It took me another couple of days before I finally figured out how to piece all of the disparate docs together to get something working.

Now, there is a lot of good information in the docs, but it all seems focused primarily on explaining each individual piece of MSW rather than giving a good understanding of how all the pieces work together.

Suggestions

1. Change Step 2 to be: What do you want to mock? You can link to the same Browser and Node.js pages, though I'd label them "A Service Worker in the Browser" and "An HTTP Server in Node.js" for clarity.
2. Use actual interceptors in service worker and server examples. Including actual interceptors in these examples would go a long way towards improving understanding. The stubs in the current examples are confusing and it took me a while to figure out that I needed to copy from the interceptors examples and insert into the server example. Just a simple example in each section would go a long way. You can also include "This shows a very basic interceptor, to learn about how to customize interceptors, click here" and link off to the interceptor docs.
3. Change Step 3 to be: Customize the behavior. Here you can link to your interceptors, mocking responses, etc. pages that you currently have as step 2.
4. All interceptors examples should be in a mock service worker of server. I'm guessing the idea for not doing this is that you don't want people to think that these can only be used in one spot or the other, but it's really confusing to have zero context when looking at interceptors docs. You could double up the examples, showing one for service workers and one for servers (maybe with a tabbed interface?) or alternate the examples and just explain in the prose that you can swap one for the other.

Mocking responses

The Mocking responses page is missing a common use case: Returning a non-200 code with a JSON body. The text() and json() are nice, but they hide a lot of what has to happen to a JSON body to work properly in error conditions.

[kettanaito]

Hi, @nzakas! Thank you so much for putting your time to provide the feedback. I will try to process it and write down some action points I can take to improve the docs. Do you mind elaborating on a few moments?

Step 2: Write network behavior. My options are "Intercepting requests" or "Mocking responses". So I choose "Intercepting requests".

Did you feel like you had to choose between these? This may be a poor visual representation because those two are basically a list, and you need to read them in order: first, you lean how to intercept requests; second, you learn how to return mocked responses.

I think this separation makes sense. You can intercept requests without mocking the responses—that a legitimate use case.

Both don't make sense without the context of how they're used, which I still have not encountered.

Yeah, I see. What you saying is completely valid. From what I can see, the biggest frustration on your end was due to the lack of a complete A-Z example to follow.

The Getting started docs themselves are modular. MSW can and is used for many many things, and it'd mean writing 10 getting started guides based on what you personally want to use it. So I made a decision to split it into sections and the intention here is that you open the Getting started page and then go through the steps, read the references pages, then go back and continue the tutorial.

You don't see immediate usage examples of the handlers when you describe the network because all that follows after is the integration part. And here it gets a bit tricky because MSW can be used anywhere but the source of the mocks, your handlers, are still defined in the same way.

I need to think what's the best way to address this.

Mocking responses. No complete examples here either. At this point I'm getting frustrated.

Yeah, I think the docs fail you at the very beginning. You expect each step in the Getting started tutorial to be a complete example but it's not by design. You follow a journey:

1. This is how to intercept requests.
2. This is how to respond with mocks.
3. This is how to integrate into whichever environment you want.

Now, these steps are dependent on each other so you progress through them in order. If you jump to the Integration parts, they won't be talking about how to describe the network because (a) it's not their concern; (b) the network description is the same anywhere you decide to integrate it.

Node.js integration. Okay, so now I see how to set up a server! But what is ...handlers and where are they defined?

This is a fantastic feedback. I think that page should at least reference to where the handlers come from. Noted!

But where is the simple "getting started" example?

What would be the simple getting started example for you?

This is that tricky part I was talking about. People use MSW in all sorts of way with all sorts of tools. It being environment- and framework-agnostic makes it difficult to create that "simple" example because that "simple" is different for everyone coming to the library.

Having such example also creates a confusing precedent of being "the" example. Then a bunch of folks follow it and make the wrong conclusions, like "Oh, this works only in React" or "Shoot, that seems to be for Jest only", etc.

Folks are usually integrating MSW with other tools (Cypress/Playwright/Jest). And even that is not mandatory, the library will work in a simple index.html (browser) or index.js (Node.js) without any frameworks whatsoever.

Can you please tell me more about where you are integrating MSW? Really want to learn from your expectations.

At this point, I have not found a single complete example in one place.

I interpret "complete" here as "comprehensive". If that's the case, each example repo in the JavaScript frameworks section of the examples is comprehensive. It features MSW integrations for development and integration + E2E levels of testing at the same time. Those are the most complete examples to me.

• Would barebones, no-dependency browser/Node.js integration examples be helpful to you?

The value of those examples is not so much to show you how MSW works but to highlight where different frameworks keep their integration points. MSW works the same everywhere, but the frameworks require you to know where to put those integrations. For example, Remix has entry.server.js while Next.j has an instrumentation.ts, and then Vue and Svelte has their own places where the Node.js entrypoint begins. The goal of examples is to help people see where those entrypoints are. From there, it's always the same browser/Node.js integration of MSW as described in the docs.

I do believe what caused the most frustration for you was thinking that MSW can be used in one particular way, like most tools are. You pull in react-redux you expect it to work with React. That's also great because now the docs can emphasize necessary parts while skipping on the general React bits.

MSW is a bit unique in that regard, and I agree it can get unclear what/how you do with it. I value your feedback a lot, and I think I need to improve the docs. Just have those few questions above to help me narrow down the exact improvements.

It gets even more complex as we bring in support for more protocols, like WebSocket. Now, mocking WebSockets is completely different from mocking HTTP, but there are reused experiences also, like the integration points remain the same. It's not easy to get this right. Hope to iterate on this with you and make the docs better. Once again, thank you!

[nzakas]

Did you feel like you had to choose between these?

Yes. It definitely felt like "at this point, here are two possible next paths." If the intent is to encourage people to go to Interceptors first and then Mocking Responses, I'd suggest removing Mocking Responses from the Getting Started page and instead link to it at the end of the Interceptors page.

So I made a decision to split it into sections and the intention here is that you open the Getting started page and then go through the steps, read the references pages, then go back and continue the tutorial.

I understand your thinking here, as this was the way the ESLint docs were set up initially. However, users don't have the time or interest to gather together all of the different concepts and stitch them together. You're giving them individual Lego pieces when they want a pirate ship.

A "Getting Started" page is really meant to be a jumping off point once people get the basics.

This is that tricky part I was talking about. People use MSW in all sorts of way with all sorts of tools. It being environment- and framework-agnostic makes it difficult to create that "simple" example because that "simple" is different for everyone coming to the library.

Having such example also creates a confusing precedent of being "the" example. Then a bunch of folks follow it and make the wrong conclusions, like "Oh, this works only in React" or "Shoot, that seems to be for Jest only", etc.

Again, I totally understand this perspective because it's where I started too. However, developers are really good at analogies...if you show them one example, they are really good at figuring out what bits to change to make it work for them.

Here's what I'd like to see right on the Getting Started page:

// import everything you need from MSW
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";

// create and start a mock server (can also be a service worker for browsers)
const server = setupServer();
server.listen();

// define your interceptors
server.use(
    http.get("https://api.example.com", () => HttpResponse.text("Hello, world!"))
);

// your request now goes to the mock server
const response = await fetch("https://api.example.com");
const text = await response.text();
console.log(text); // Hello, world!

// clean up after you're done
server.close();

To me, this is very generic but introduces all of the most important parts of MSW:

1. Creating your server (or service worker, I don't think it actually matters)
2. Defining an interceptor
3. Mocking out a response
4. Cleaning up afterwards

So even though people use MSW with testing frameworks, this example doesn't contain any testing framework or environment information and yet I still think it gets across everything I need to know about MSW right up front.

You can always add a short paragraph after it like, "This example uses a Node.js integration to mock out an HTTP server, but MSW can also mock out a service worker in a browser (link), and can even mock out WebSockets (link)."

Can you please tell me more about where you are integrating MSW? Really want to learn from your expectations.

Check out: https://github.com/humanwhocodes/humanfs/blob/box/packages/box/tests/box-client.test.js

I interpret "complete" here as "comprehensive".

What I really want is a single complete example in one file. My general frustration with sharing GitHub repos (which is not directed at you, but at the larger practice in OSS) is that it drops people into the middle of an unfamiliar code base with the expectation that they have the time and interest to explore and find their way around. A single file, even if it used a test framework I was unfamiliar with and an integration I didn't want, would still have been incredibly valuable as a starting point. (Once again,

I hope this helps.

[kettanaito]

This doesn't just help, this is incredible! Will process this and refine the Getting started page. Thank you so much for making MSW better!

[kettanaito]

Update

I've rewritten the Getting started tutorial based on your feedback, @nzakas! I hope it's in a much better shape now. Please let me know what you think about it now.

[nzakas]

Better! I like that there's code right on the page and a throughline between them all. I still feel like the experience is a bit disjointed because I have to mentally keep track of where things are in different files vs. just having one complete example in one code block that shows all the pieces.

[kettanaito]

That's okay imo. You never really put all of it in the same module because that defeats the reliability purpose. I think asking the reader to keep track of there modules is appropriate.

[nzakas]

I'm using everything in one module. 😄

Again, the role of a "Getting started" page is not to give people the canonical way to use the project. Instead, the role is to get people familiar enough with the important concepts to be able to jump off into supplementary documentation. The example doesn't need to be the way people will actually use it, it's just there to get something running that exercises the project.

By splitting up the code, it's still pretty easy to get lost. I understand that this is the way you think about using the project, but I'm suggesting that it's not the way a user (a new user, at that!) will think about the project. I know to you it makes sense that interceptors are the core concept to understand in that they can be inserted in multiple places, but as a new user, the concept of interceptors outside of a container is just something abstract that needs to be mentally bookmarked for later. When I came to the docs, my goal was "find out how to create a mock server," not "find out how to create an interceptor" (because I had no idea what that was).

Of course, it's your project, you can organize things however you'd like. 😄 If nothing else, at a minimum I'd suggest to stop using the word "handlers" and instead stick with "interceptors" everywhere. That at least would eliminate the number of terms new users would need to understand to get going.

[kettanaito]

The example doesn't need to be the way people will actually use it, it's just there to get something running that exercises the project.

There are a lot of people who won't read past the first example. I agree with you on the purpose of Getting started, and I also see a lot of value of getting the developers into the "this is how it's used" workflow from example one.

but as a new user, the concept of interceptors outside of a container is just something abstract that needs to be mentally bookmarked for later.

This sounds like an explanation issue though. If you have/recall some of that confusion, please share. I think a single paragraph can go a long way in making things more clear.

If nothing else, at a minimum I'd suggest to stop using the word "handlers" and instead stick with "interceptors" everywhere.

Those are not equivalent. A handler decides how to handle requests, thus the name. Handlers do not do the actual interception. They are just a network description format. You can even call them manually, giving any Request instance and get a Response instance back (no interception involved!).

We have a rather consistent naming across the ecosystem, where "interceptors" is referred to the actual interceptors. Those are the underlying mechanism of spying on requests, then feeding their Fetch API representation to your request handlers.

As a library user, you can call them as it makes most sense to you, but to support your point of consistency, I'd leave the terminology intact. It's deliberate and I've spent a lot of time making it so.