Provide a way (or document an existing way) to return a NetworkError once

Is your feature request related to a problem? Please describe.

I would like to have a documented way of defining a handler that returns a NetworkError only once, then falls back to an existing handler. This can be helpful in testing an app’s request-retrying logic.

---

I know how to return a valid response or a failing status code once:

server.use(
  rest.get('/foo', (_req, res, ctx) => {
    return res.once(
      ctx.status(404, 'Not found')
    );
  })
);

And I know how to return a network error:

server.use(
  rest.get('/foo', (_req, res, ctx) => {
    return res.networkError('Failed to conect');
  })
);

But since these both depend on returning the result of different methods on res, I’m not sure how to use the current API to return a network error once.

---

I tried a few options, including the three below, but they all continued to respond with errors after the first request. They also resulted in TypeScript errors, which makes sense:

server.use(
  rest.get('/foo', (_req, res, ctx) => {
    return res.once(res.networkError('Failed to conect'));
  })
);

server.use(
  rest.get('/foo', (_req, res, ctx) => {
    return res.once(() => res.networkError('Failed to conect'));
  })
);

server.use(
  rest.get('/foo', (_req, res, ctx) => {
    return res.once((innerRes) => innerRes.networkError('Failed to conect'));
  })
);

Describe the solution you’d like

I’m not familiar with msw’s internals, so there may be a better fit for the API, but an intuitive solution for me would be:

• Provide networkError on the ctx object. This would be consistent with the API for changing just about every other aspect of a response (networkError strikes me as out of place on the res object).

It could then be used something like this:

server.use(
  rest.get('/foo', (_req, res, ctx) => {
    return res.once(
      ctx.networkError('Failed to conect')
    );
  })
);

Describe alternatives you’ve considered

Another good option would be to provide networkError as a method on once:

server.use(
  rest.get('/foo', (_req, res, ctx) => {
    return res.once.networkError('Failed to conect');
  })
);

Or to provide once on rest and graphql and all request methods on once:

server.use(
  rest.once.get('/foo', (_req, res, ctx) => {
    return res.networkError('Failed to conect');
  })
);

Or to provide once as a method of all request methods and have it inherit the preceding method’s behavior:

server.use(
  rest.get.once('/foo', (_req, res, ctx) => {
    return res.networkError('Failed to conect');
  })
);

Additional context

I’m guessing there may already be a way of accomplishing this, just requiring digging into the internals. If so, it would be wonderful to add documentation for it. This would help users and discourage them from relying on undocumented portions of the API that might change.

[kettanaito]

I’m considering the introduction of “intentions” returned from the resolver (see #1207). Returning a mocked response object is no longer flexible as the scenarios for mocks grow in complexity. I believe the intention-driven design will allow us to make resolvers more straightforward. It can also allow us to decouple intentions (“return network errors”) from modifiers (always/once), which should fix this particular issue.

[noahbrenner]

I found a workaround for now, though I’d still love to see this supported natively. Here’s what’s working for me:

function enableSuccessfulResponse() {
  server.use(
    rest.get("http://example.com", (_req, res, ctx) => {
      return res(ctx.json({ foo: "bar" }));
    })
  );
}

server.use(
  rest.get("http://example.com", (_req, res) => {
    enableSuccessfulResponse();
    return res.networkError("Failed to connect");
  })
);