Zimic

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.

Features

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!

Documentation

• Introduction
• Getting started
• API reference
• CLI reference
• Guides
  • Testing

Examples

Visit our examples to see how to use Zimic with popular frameworks, libraries, and use cases!

Changelog

The changelog is available on our GitHub Releases page.