Context and Problem Statement¶

For effective frontend development and testing, we need a reliable way to mock API responses without depending on backend services. We need to select an API mocking library that integrates well with our testing framework, supports our GraphQL and REST endpoints, and provides a good developer experience.

Which API mocking library should we use for our React application: MSW, Nock, or JSON Server?

Decision Drivers¶

• Support for both REST and GraphQL APIs
• Integration with our testing framework (Vitest)
• Developer experience and ease of use
• Browser and Node.js compatibility
• Maintainability and debugging capabilities
• Community support and documentation

Considered Options¶

• Mock Service Worker (MSW)
• Nock
• JSON Server

Decision Outcome¶

Chosen option: Mock Service Worker (MSW)

We have decided to use MSW for the Newgotiate UI application due to its service worker approach, support for both browser and Node.js environments, and excellent GraphQL integration.

Reasoning¶

1. Service Worker Approach: MSW intercepts requests at the network level using service workers, providing a more realistic testing environment that closely mimics production behavior.

2. Environment Flexibility: MSW works in both browser and Node.js environments with the same API, allowing consistent mocking across unit tests, integration tests, and development.

3. GraphQL Support: MSW has first-class support for GraphQL, which is critical for our application that uses GraphQL for data fetching.

4. Developer Experience: The declarative API makes it easy to define and maintain mock handlers, with excellent TypeScript support.

5. Integration: MSW integrates seamlessly with React Query, which we're already using for data fetching.

Implementation Notes¶

• Handlers are defined in src/core/msw/handlers.ts
• MSW is set up in src/mocks/browser.ts for browser environments and src/mocks/node.ts for Node.js
• We're using graphql.query for GraphQL mocking to ensure proper endpoint handling
• Mock data is stored separately from handlers to improve maintainability

Consequences¶

• Team members need to understand the service worker concept for effective debugging
• We need to ensure proper setup in both test and development environments
• We should document common patterns for mocking complex scenarios

Pros and Cons of the Options¶

Mock Service Worker (MSW)¶

• Good, because it intercepts requests at the network level, providing realistic testing
• Good, because it works in both browser and Node.js environments
• Good, because it has excellent support for both REST and GraphQL
• Good, because it integrates well with our existing tools (React Query, Vitest)
• Good, because it has strong TypeScript support
• Good, because it allows for runtime request interception during development
• Bad, because it requires additional setup for service workers
• Bad, because debugging can be more complex due to the network interception approach

Nock¶

• Good, because it's specifically designed for Node.js testing
• Good, because it has a mature API with extensive matching capabilities
• Good, because it's lightweight and focused on HTTP mocking
• Bad, because it only works in Node.js, not in browsers
• Bad, because it has limited GraphQL support
• Bad, because it doesn't integrate as seamlessly with browser-based testing

JSON Server¶

• Good, because it provides a full fake REST API with zero coding
• Good, because it's easy to set up and use
• Good, because it persists data, allowing for more complex test scenarios
• Bad, because it doesn't support GraphQL
• Bad, because it requires a separate server process
• Bad, because it's more suited for prototyping than testing

Links¶

• MSW Documentation
• Nock Documentation
• JSON Server Documentation