@beta. For v3, read the docs in the v3 branch.Mocking with MSW
With --mock msw the generator also writes mock data and MSW request handlers for every operation. The frontend can then be built against the specification before the backend exists, and the same handlers serve tests and Storybook.
npm install -D msworqc -i ./openapi.yaml -o ./src/openapi --mock mswThis adds a third directory next to requests/ and queries/, here under src/openapi as the examples below import it:
src/openapi/mocks/├── data.ts # one mock function per schema and per response├── handlers.ts # one MSW handler per operation, and `handlers` with all of them└── index.ts # re-exports bothThe mocks are typed by the generated types, so they stay in step with the specification: regenerate after it changes, and anything of your own that no longer fits is a compile error.
In the browser
Section titled “In the browser”Copy MSW's worker script into the folder your app serves static files from, once:
npx msw init public/ --saveCreate the worker from the generated handlers:
import { setupWorker } from "msw/browser";import { handlers } from "../openapi/mocks";
export const worker = setupWorker(...handlers);Start it before the app renders, in development only:
async function enableMocking() { if (!import.meta.env.DEV) return; const { worker } = await import("./mocks/browser"); await worker.start();}
enableMocking().then(() => { createRoot(document.getElementById("root")!).render(<App />);});The handlers match the path under any base URL (*/pets/:petId), so they answer whatever the client's baseUrl is. The generated hooks need no change.
In tests
Section titled “In tests”import { setupServer } from "msw/node";import { handlers } from "../openapi/mocks";
const server = setupServer(...handlers);
beforeAll(() => server.listen());afterEach(() => server.resetHandlers());afterAll(() => server.close());Answering with something else
Section titled “Answering with something else”By default a handler answers with the mock of its operation's successful response. Each handler is also exported as a function that takes what to answer with instead: a body, or a resolver of your own.
import { HttpResponse } from "msw/http"; // "msw" with MSW 2import { findPetsHandler, findPetByIdHandler, petMock } from "../openapi/mocks";
server.use( // Another body, typed as the operation's response findPetsHandler([petMock({ name: "Momo" }), petMock({ id: 2 })]), // A resolver, for an error or anything that depends on the request findPetByIdHandler(({ params }) => HttpResponse.json({ message: `No pet ${params.id}` }, { status: 404 }), ),);MSW uses the first handler that matches, so put your own before the generated ones:
setupWorker(findPetsHandler([]), ...handlers);The mock of an object schema takes the properties to replace (petMock({ name: "Momo" })). The mocks of other schemas (arrays, unions, enums) take nothing.
What the values are
Section titled “What the values are”The values are fixed, never random, so a test or a snapshot sees the same data on every run. For each schema the first of these that applies is used:
- the
exampleof the response's media type, or the first of itsexamples - the schema's
example, the first of itsexamples, or itsdefault - its
const, or the first value of itsenum - a value made up from the type:
"string"or a fixed value for theformat(date-time,uuid,email, ...),1moved intominimumandmaximum,true, an array of one item, an object with all of its properties
So the quickest way to better mock data is to write examples in the specification. They are also what the backend has agreed to return.
Pet: type: object properties: name: type: string example: MomoAn example is only used when it is a value of its schema. One that has drifted from it (a missing required property, a string where the schema says integer) is passed over and the value is made up instead, because the mock would not compile otherwise. The same goes for an example of a schema composed with oneOf, anyOf or several allOf members, which is not checked.
Of a oneOf or anyOf the first member is used. With --useDateType the dates are Date objects, as the types say, and travel as text. writeOnly properties are left out, as they are in the response types.
A schema that refers to itself would never end, so a reference back to a schema that is still being built is cut: an optional property is left out, an array is empty, a nullable value is null. A schema that requires itself has no value at all; its mock returns an empty object and the generator says which schema it is.
What is not generated
Section titled “What is not generated”The handlers hold no state and do not look at the request. That is enough to build and test most screens, and these need a handler of your own, written with the generated types and mocks:
- A change that shows up later. Creating a pet does not add it to the list. Keep the list in a variable and answer both operations from it.
- Pagination. Every page is the same response, so an infinite query never reaches the end.
- Errors and empty states. Only the successful response is mocked. Answer with a resolver that returns the error.
Operations whose successful response has no JSON or text body (a 204, a file, a HEAD) are answered with the status and an empty body.
MSW versions
Section titled “MSW versions”MSW 2 and 3 are supported. Version 3 moved http and HttpResponse from msw to msw/http, so the generator looks at the MSW installed in your project and imports from where that version exports them. Without MSW installed it writes the imports for version 3. After upgrading MSW, generate again.
--check compares mocks/ as well when --mock is passed, and --format and --lint run on it with queries/.