Define response mocking API

[kettanaito]

What:

I suggest to define a response mocking API supported by the library.

Why:

It is essential to have a usable API to define response mocks.

How:

Mimic res from express

Example:

msw.get('...', (req, res) => {
  res.status(301).json({ message: 'Item has been moved' })
})

Pros:

• Familiar syntax of one of the most used nodejs server frameworks
• Entire response mocking API is gathered under the exposed res Object

Cons:

• Relies on res Object mutation
• Effectively, is a mocking (the res from express is a custom Object)

Functional composition

Example:

import { response, status, json } from '–'

msw.get('...', (req) => {
  return response(
    status(301),
    json({ message: 'Item has been moved' }),
  )
})

Pros:

• Uses composition instead of mutations, so the mock instance is passed from one transformer function to another
• More versatile, as any function may now become a part of the mocking chain, as long as it follows the call and return signatures

Cons:

• May not be straightforward for developers not familiar with functional programming
• Essentials like json or status would need to be explicitly imported (may be solved by exposing them as a handler function parameters)
• Doesn't have a fixed scope that controls the mocked response (any function can), thus is vague and may result into issues due to that

[kettanaito]

Support for multiple API may also be a viable option.

[bebraw]

To expand on functional composition, consider

msw.get('...', (req, { response, status, json }) => {
  return response(
    status(301),
    json({ message: 'Item has been moved' }),
  )
})

... // Inject context in another file
msw.init({ response: ..., status: ..., json: ... })

You can also implement Express style res on top of this kind of protocol.

[kettanaito]

@bebraw yeah, this is one of the ways to group essential utils without having to explicitly import them.

Maybe one thing I would move aside is the response itself. It feels wrong to expose it on the same level with helper functions, when it must be obligatory to use in the handler. Do you think it's reasonable to allow to return anything from the handler function ((req, { ... }) => any), but at the same time ship with some pre-defined helpers?

[kettanaito]

I've adopted the functional composition approach. You can see the example of usage in the current README. With something like context exposed as the third argument of the handler function, it eliminates the only issue I had against this approach—exposure of essential utils (json, set, etc.).

I like the current signature, and especially adore that a developer can write his own mocking helpers following a straightforward API.

msw.get('https://api.com/user/:username', (req, res, { status, json }) => {
  return res(
    status(301, 'Moved far away'),
    json({ message: `The user "${req.params.username}" has been moved` }),
  )
})

[kettanaito]

Response mocking API has been defined in favor of functional composition. I will add/update any relevant documentation once GitBook unblocks my account.

Closing this issue, but welcome any succeeding discussion on the topic.