Add "ctx.forward" for forwarding (bypassing) requests

What

A new ctx.forward utility may be added to forward the currently captured request to its original destination (bypass).

Why

• See #655

Currently bypassing is done via implicit/explicit return in the resolver. This is not intuitive and deterministic action, which also makes it hard to distinguish when the user forgot to return a mocked response, and when they meant to bypass intentionally.

With the introduction of this feature, the library could reliably print a warning when you have a handler, but return no response from the resolver—it becomes safe to assume that you forgot to do that.

API

rest.get('/user', (req, res, ctx) => {
  if (anything) {
    return ctx.forward()
  }

  return res(ctx.text('mocked'))
})

[IanVS]

Doing so will not produce any onUnhandledRequest warnings, as the request was handled, just not resolved to a mocked response.

It might not be an onUnhandledRequest warning, but I do get this in my console:

[MSW] Expected a mocking resolver function to return a mocked response Object, but got: undefined. Original response is going to be used instead.

I’d love to be able to mark paths as explicitly bypassed / passthrough. I’d suggest though, instead of calling it ctx.forward(), perhaps to use the same word as mirage, and call it ctx.passthrough(), since at least to me, that makes the behavior more clear. To my mind, forward makes it seem like sending it somewhere that it wasn’t sent initially, like forwarding an email to a new recipient.

[kettanaito]

Hey, @adarnon.

There is a way to bypass any request in the handler directly right now:

rest.get('/user', (req, res, ctx) => {
  // Skip this handler and perform the request as-is
  // if the request URL contains the "skip" query parameter.
  if (req.url.searchParams.get('skip')) {
    return
  }

  return res(ctx.json({ id: 1 }))
})

Read more in Conditional response.

Both explicit and implicit return in the resolver that doesn’t return a mocked response composition (res) is treated as the instruction to perform that captured request as-is. Doing so will not produce any onUnhandledRequest warnings, as the request was handled, just not resolved to a mocked response.

What this task is about is to introduce an explicit API to state that you wish to perform the request as-is, opposed to having to rely on how the library interprets the return statement.

if (req.url.searchParams.get('skip')) {
  return res(ctx.forward())
}