Documentation/UX feedback regarding relative URL matching

[srcreigh]

Hello, thank you SO MUCH for this wonderful library. I'm very excited to use it. I am so excited the potential of mocking the network layer instead of individual functions.

I want to let you know that I was very confused why this setup code didn't match requests to my development server:

export const handlers = [
  rest.post("/tasks/act", (_, res, ctx) => {
    return res(ctx.status(200));
  }),
];

The reason why is that I my development backend server runs on a different port than my react dev server. I have to imagine that this setup is very common; although my current workplace serves React from a local Rails server, every other previous workplace and in all my personal projects I used http://localhost:3000 for React and http://localhost:5000 or something for the backend (ie separate ports/processes). Why? Setting up the back-end to serve the React app is an extra setup step which I can't currently justify.. nginx reverse proxy and 2 servers in prod is a simple way to not complicate the API server.. I'm also not sure if serving react via the API server locally will have the nice live reloading experience that the npm start create-react-app dev server provides.

(Please note that before posting this issue, I inspected all open issues as well as also several closed issue threads containing the word "relative", for relative paths. Unless I missed something, I have some confirmation that this issue hasn't been addressed.)

What follows is a few brainstormed ideas to help with clarity of others regarding relative path matching:

1. In the docs, maybe you could introduce a decision point regarding relative paths in the Getting Started guide. Instruct them to use rest.post($YOUR_API_ROOT_PATH + '/login', with a tip saying "If you backend and frontend use the same port, you can shorten this to rest.post('/login')!" That way, the default works and there's better options for some people, vs the default doesn't work for some people but works for others.
2. Another avenue to help my experience would have been an informative error message. I saw all the warnings from msw in the console and was excited to resolve them all. Unfortunately, the message "Request to http://localhost:5000/tasks/act..." not matching anything was rather opaque. Maybe you could check for relative paths which would have matched if the host was the same, and inform the user that they can use an absolute URL to produce a match? (This could produce tons of new warnings for existing library users though... ehh...)
3. I don't want to look a gift horse in the mouth, but I have to wonder if ignoring base url is a sensible default? To be clear, maybe /login should match $DIFFERENT_HOST/login, in addition to $SAME_HOST/login. Yes, maybe this will match two different hosts to a single handler, which isn't ideal... ehhh... I don't want to go down too far the rabbit hole of suggesting potentially backwards incompatible changes so I'll stop there. :)

To reiterate on the main point - I'm so happy that this library exists.. it was what I opted to spend my evening trying out after a day of research! Btw, I found out about it since the 3rd Google search result for "how to mock fetch in jest" is the Kent C Dodds article recommending msw. Anyways, I am a big fan and thank you so much for all your work til now. Cheers 😁

[kettanaito]

Hey, @srcreigh. Thank you for your kind feedback!

We do mention that relative URLs are resolved against location.origin in the Request matching > Exact request URL section of the documentation:

Note that relative URL are resolved against the current location (location.origin).

If your backend runs on a separate host/port than your frontend, it's implied that you need to construct an absolute URL. We come from the same general expectations when working with fetch: you too provide a different (absolute) URL when fetching data from such backend:

// You don't expect this to request your backend
// because you understand "/data" resolves against
// the current hostname (frontend).
fetch('/data')

// So to fetch data from your backend
// you provide an absolute URL to it.
// (Which may contain env variables, it's fine).
fetch('http://localhost:5000/data')

And so request matching in MSW works the same way in regards to relative/absolute URLs.

---

We do provide smart handler suggestions on unhandled requests. For example, given your use case you'd see the following warning in the browser's console/test output:

react_devtools_backend.js:2842 [MSW] Warning: captured a request without a matching request handler:

  • GET http://localhost:5000/data

If you still wish to intercept this unhandled request, please create a request handler for it.
Read more: https://mswjs.io/docs/getting-started/mocks

We don't perform any kind of diff'ing, as the suggestion above is enough for you to sport the problem (in your case a different port).

If you don't see this warning message, this likely means you're using an older version of the library. Update to the latest version of MSW to get the best experience.

---

Regarding a loose matching of relative and absolute URL, I don't think that ignoring the base URL is a good idea. Coming back to the common expectations when working with any request client that I've described above, people don't expect the base URL to be ignored. This kind of implicitness can be hurtful and raise a lot of problems.

You can ignore the base URL explicitly by using a path string with a wildcard:

rest.get('*/data', resolver)

I wouldn't commend that, as the nature of endpoints is largely static (even dynamic base URLs based on the environment still produce a static URL in the end), which means the URL cannot suddenly change on runtime. Including an explicit base URL, no matter if conditional, is a good approach to take.

// Look, this intercepts a request to an absolute URL
// using this particular env variable as a base URL.
rest.get(`{process.env.BASE_URL}`/data`, resolver)

Generally, prefer explicitness.

[srcreigh]

Thanks for the detailed response. The wildcard matching is really great!

If it wasn't clear before. One of my hoped for outcomes was to have slightly more information about the wonderful request matching system directly in the getting started guide. In my personal opinion, it would be nice for the request matching to "just work" without having to debug or read separate documentation page. My experience was like this: YES /login will match my backend! Oh wait it doesn't... hmm why? double checks code... confusion and maybe a little frustration... scans through documentation... reads about request matching... Oh this makes a lot of sense... fixes the code I got from the getting started guide... works perfectly now!.

Specifically this part: https://mswjs.io/docs/getting-started/mocks/rest-api#request-handler

Here's a few ideas:

• Demo some the fetch requests which do/don't match the handler?
• Expound a bit about how it's a relative URL so it only matches the current hostname?
• Use a wildcard (or base url) in the tutorial code?
• Include a small table with the 3 matching patterns? (relative, absolute, wildcard)

I think a little extra info there might help new folks understand just how well designed this library is 😁 We can't just go around expecting this high level of quality everywhere, help us out a bit haha.

as the suggestion above is enough for you to sport the problem

Respectfully, in my noob state given only knowledge from what I read in the getting started guide, it was not enough. My mental model at that point was that "/login" does wildcard matching - but it's not matching - is the library broken or something? Of course it wasn't, it's great, but that was my experience.

Anyways, I defer to you. Thanks again for the wonderful library and i'm so excited to be using such a simple and great tech 😁

[kettanaito]

I think the docs can use some improvement to make relative request URL matching more apparent 👍🏻

Demo some the fetch requests which do/don't match the handler?

A good call. I believe we can include something like "with this handler /this will be matched, but http://localhost:9000/this will not (notice the port difference)". This needs to stay aware of the Getting started tutorial's scope and don't sway too much. Note that the tutorial is aimed to help you achieve one single purpose. Of course, there are multiple things you can do with MSW and they will largely depend on your use case. For that, we have other sections of the docs. The goal is to link them well, so it's easier to find.

Expound a bit about how it's a relative URL so it only matches the current hostname?

We do encourage you to read about request matching in the Request handler section. I understand this is useful information and we should mention it in the tutorial.

Use a wildcard (or base url) in the tutorial code?

As I've stated before, using wildcards is rather harmful and should be avoided as it can produce false-positive matches. I don't recommend using wildcards for hostnames, which includes your case as well. Please use your environmental variable to compose a valid absolute URL to your backend.

Include a small table with the 3 matching patterns? (relative, absolute, wildcard)

There are plenty of such examples on the Request matching page. They don't belong in the focused scope of the tutorial, as they'd be stealing too much attention from the tutorial's purpose. Once again, I think the explanation and examples are there, the issue is to make them more discoverable.

I think a little extra info there might help new folks understand just how well designed this library is

I agree that expectations, just as use cases, are highly variable and diverse. We'll try to work on the documentation communicating certain APIs and capabilities you have when using MSW. Actually, we may use your fresh perspective to help us with that. Would you be interested in collaborating with us to make the docs better?

[srcreigh]

Actually, we may use your fresh perspective to help us with that. Would you be interested in collaborating with us to make the docs better?

Yes! Please tag me on anything.

Are the docs generated from this repo? Happy to send a PR, or we can work through the addition in this issue.

(Forgive me for replying so late - I must've archived the email half awake.)

[IanVS]

I just wanted to chime in that I was also bitten by this a little. I did find the documentation eventually which mentioned relative paths are relative to the page's hostname, but I then spent a while trying to find an option to set (maybe in .start()) to configure a default base path, which doesn't seem to exist. It sounds like you're against adding such an option, and prefer to add it in each handler, which is fine. But maybe examples of this in the docs would prevent confusion.

[kettanaito]

While we are unlikely to add base URL support to the library itself, we are by no means against you using it. Take a look at this video tutorial that explains how to achieve base path in your request handlers.

[michaeltg17]

Hi. I wanted to share that I struggled with this as well.

In my case I was mocking the location.origin and some other related properties but MSW wasn't matching the request. Finally I cloned the repo and checking the code I realized that it depends on the document.baseURI instead of the location.origin (getAbsoluteUrl function).

At the end I setup the test in another way that you don't need to mock and it worked fine, but wanted to share.

From MSW side, maybe documentation can be improved to include this document.baseURI usage. The warnings you get when a request is not matched are really good. But in this case when you setup handlers with relative paths it would be nice to see what the final full path is so you can check why it is not being matched.

[kettanaito]

Hi, @michaeltg17.

Our docs mention document.baseURI usage a few times:

• https://mswjs.io/docs/runbook/#step-1-verify-setup
• https://mswjs.io/docs/basics/intercepting-requests/#how-do-i-use-relative-urls-in-nodejs

In practice, document.baseURI equals to location.origin 99.9% of the time. I believe we chose to rely on document.baseURI because it will take <base href /> into account in the browser. This has no effect in Node.js.

If you'd like a better mention of this in the docs, please suggest one.