home
TypeScript-first HTTP request mocking
npm • Docs • Examples • Issues • Roadmap
Zimic is a lightweight, thoroughly tested, TypeScript-first HTTP request mocking library, inspired by Zod's type inference and using MSW under the hood.
Zimic provides a flexible and type-safe way to mock HTTP requests.
- ⚡ Statically-typed mocks: Declare the schema of your HTTP endpoints and create fully typed mocks.
- 🔗 Network-level intercepts: Internally, Zimic combines MSW and interceptor servers to act on real HTTP requests. From you application's point of view, the mocked responses are indistinguishable from the real ones.
- 🔧 Flexibility: Mock external services and reliably test how your application behaves. Simulate success, loading, and error states with ease using standard web APIs.
- 💡 Simplicity: Zimic was designed to encourage clarity, simplicity, and robustness in your mocks. Check our getting started guide and starting mocking!
import { type JSONValue } from 'zimic';
import { type HttpSchema } from 'zimic/http';
import { httpInterceptor } from 'zimic/interceptor/http';
type User = JSONValue<{
username: string;
}>;
// Declare your service schema
type MyServiceSchema = HttpSchema.Paths<{
'/users': {
GET: {
response: {
200: { body: User[] };
};
};
};
}>;
// Create and start your interceptor
const myInterceptor = httpInterceptor.create<MyServiceSchema>({
type: 'local',
baseURL: 'http://localhost:3000',
});
await myInterceptor.start();
// Declare your mocks
const listHandler = myInterceptor.get('/users').respond({
status: 200,
body: [{ username: 'diego-aquino' }],
});
// Enjoy!
const response = await fetch('http://localhost:3000/users');
const users = await response.json();
console.log(users); // [{ username: 'diego-aquino' }]Note
Zimic has gone a long way in v0, but we're not yet v1!
Reviews and improvements to the public API are possible, so breaking changes may exceptionally land without a major release during v0. Despite of that, we do not expect big mental model shifts. Usually, migrating to a new Zimic release requires minimal to no refactoring. During v0, we will follow these guidelines:
- Breaking changes, if any, will be delivered in the next minor version.
- Breaking changes, if any, will be documented in the version release, along with a migration guide detailing the introduced changes and suggesting steps to migrate.
From v0.8 onwards, we expect Zimic's public API to become more stable. If you'd like to share any feedback, please feel free to open an issue or create a discussion!
Zimic is a development and testing tool that helps you mock HTTP responses in a type-safe way. Some of our best use cases:
- Testing: If your application relies on external services over HTTP, you can mock them with Zimic to make your tests simpler, faster and more predictable. Each interceptor references a schema declaration to provide type inference and validation for your mocks. After breaking changes, adapting the interceptor schema will help you to quickly identify all of the affected mocks and keep your test scenarios consistent with the real-life API.
- Development: If you are developing a feature that depends on an external service that is unreliable, unavailable, or costly, you can use Zimic to mock it and continue your development without interruptions. Zimic can also be used to create mock servers, using remote interceptors and interceptor servers, which can be accessible by multiple applications in your development workflow and even be containerized.
Zimic allows you to intercept HTTP requests and return mock responses. In local HTTP interceptors, Zimic uses MSW to intercept requests in the same process as your application. In remote HTTP interceptors, Zimic uses a dedicated local interceptor server to handle requests. This opens up more possibilities for mocking, such as handling requests from multiple applications. Both of those strategies act on real HTTP requests after they leave your application, so no parts of your application code are skipped and you can get more confidence in your tests.
Tip
How do I search the wiki?
To search resources in this wiki, click on the GitHub search bar (or press /), prefix your query
repo:zimicjs/zimic type:wiki and type your search terms.
Visit our examples to see how to use Zimic with popular frameworks, libraries, and use cases!
The changelog is available on our GitHub Releases page.