Allow reuse of request trackers after the interceptor is cleared

Marking request trackers as unusable after the interceptor is cleared makes sure no outdated interceptors are used. However, this strategy makes it impossible to reuse interceptors between tests:

const userListTracker = userInterceptor.get('/users')

beforeEach(async () => {
  userInterceptor.clear()
})

it('test 1', () => {
  userListTracker.respond(...) // won't work
})

it('test 2', () => {
  userListTracker.respond(...) // won't work
})

HTTP interceptor request match by form data and blob

The HTTP request tracker should support:

Defining form data to match requests

Receiving a second, optional argument to whether the match should be exact or not (default: false)

const creationTracker = authInterceptor
  .post('/users')
  .with({
    formData: creationPayload,
    body: blob, // or File or Buffer
  })
  .respond({
    status: 201,
    body: user,
  });

Include Windows and MacOS in CI end-to-end tests

Explicit root type definitions

Configure initial GitHub board

Remove worker handlers after clearing an interceptor

Verify compatibility when starting multiple interceptors in the same project

Create a new abstraction to be reused by interceptors? Expose worker?
Create test on zimic-test-client using one worker and multiple interceptors
Create test on zimic-test-client using multiple workers (there should be an error)

Context

Zimic currently only applies HTTP mocks to the process where the interceptor is called. This makes it unusable in multi-process scenarios.

An example that illustrates this case:

A route handler of a Next.js application is being tested using Vitest.
The Next.js server was started as a separate process using next dev.
The Vitest tests make HTTP requests to the route handler running on localhost.
The route handler access an external service. This service is not guaranteed to be running all the time and, as we have no control of its availability, the tests should not reach it directly.

This is a great use case for Zimic, since mocking external applications with type safety is one of our goals. However, this scenario is not currently supported. For example, a test of this application could look like:

The Vitest test initializes an interceptor and applies a mock to the external service. It is useful to keep the interceptor mock declarations in the test to easily simulate behaviors.
The route handler running on the second process is not affected and requests makes by the Vitest test to the route handler still reach the external service.

Archived proposals

Proposal 1: mocks applied directly to the remote process

Solution

A feature that would extend Zimic to this use case would be the introduction of "remote HTTP interceptors". Remote interceptors are similar to our current interceptors, but they apply mocks to remote processes instead of the one the interceptor is initialized.

Using the example above, the workflow using remote interceptors would be like:

The Next.js application would expose an endpoint (e.g. /zimic), available only in development and testing. This endpoint would be used by Zimic to receive mocks definitions and apply them to the Next.js process.
The Vitest test would create a remote interceptor, linking it to the endpoint made available by the Next.js application.
When applying mocks or doing any operation on the remote interceptor, a request would be issued to the endpoint on the Next.js application. In other words, declaring a mock in the Vitest test would actually send it to the Next,js application, where it would be applied. This would mean that all methods of remote interceptors and request trackers would need to be asynchronous.
The external service would no longer be reached in tests, as the Vitest test would be able to apply mocks remotely to the server application.

API

// creates a RemoteHttpInterceptor
const remoteInterceptor = createHttpInterceptor<{ ... }>({
  type: 'remote' // 'local' is the default
  remoteURL: 'http://localhost:3000/zimic',
})

const getTracker = await remoteInterceptor.get('/').respond({
  status: 200,
  body: { success: true }
})

// mock applied to remote application

const getRequests = await getTracker.requests()
expect(getRequests).toHaveLenght(1)

Proposal 2: Zimic mock server

Solution

A feature that would extend Zimic to this use case would be the introduction of remote HTTP interceptors. Remote interceptors are similar to our current interceptors, but they apply mocks to a remote Zimic server process, instead of the process where the interceptor is initialized.

Using the example above, the workflow using remote interceptors would be like:

In development or testing, a Zimic mock server would need to be started alongside the Next.js application. The Zimic server would be used to receive and apply mock definitions.
The Next.js application would route requests intent to the external service to the Zimic server.
The Vitest test would create a remote worker and interceptors, linking them to the Zimic mock server in use by the Next.js application.
When doing any operation on the remote interceptor, such as declaring mocks, the operation would be sent to the Zimic server to apply it. In other words, declaring a mock in the Vitest test would actually send it to the Zimic server. This would allow simulating scenarios of the external service responses in tests. For this to work, all methods of remote interceptors and request trackers would need to be asynchronous.
The external service would no longer be reached in tests, as the Vitest test would be able to apply mocks remotely to the Zimic mock server in use by the Next.js application. 🎉

API examples

Using local workers and interceptors:

type InterceptorSchema = HttpInterceptorSchema.Root<{
  '/': {
    GET: {
      response: {
        200: { body: { success: true } };
      };
    };
  };
}>;

const localWorker = createWorker({
  type: 'local',
});

await localWorker.start(); // starts the local worker, applies the mocks to the local process

// creates an HttpInterceptor
const localInterceptor = createHttpInterceptor<InterceptorSchema>({
  worker: localWorker,
  baseURL: 'http://localhost:3000',
});

// applying remote mocks is a asynchronous operation
const getTracker = localInterceptor.get('/').respond({
  status: 200,
  body: { success: true },
});

// mock applied to local process

const getRequests = getTracker.requests();
expect(getRequests).toHaveLength(1);

Using remote workers and interceptors:

type InterceptorSchema = HttpInterceptorSchema.Root<{
  '/': {
    GET: {
      response: {
        200: { body: { success: true } };
      };
    };
  };
}>;

const remoteWorker = createWorker({
  type: 'remote',
  serverURL: 'http://localhost:3001', // the URL of the zimic mock server
});

// start the zimic mock server with:
// zimic server start --port 3001 --on-ready 'npm test' --ephemeral true

await remoteWorker.start(); // starts the remote worker and links it to the zimic mock server

// creates a RemoteHttpInterceptor
const remoteInterceptor = createHttpInterceptor<InterceptorSchema>({
  worker: remoteWorker,
  // the application should use the base URL of the external service as http://localhost:3001/service1
  pathPrefix: '/service1',
});

// applying remote mocks is an asynchronous operation
const getTracker = await remoteInterceptor.get('/').respond({
  status: 200,
  body: { success: true },
});

// mock applied to remote server:
// any requests to http://localhost:3001 will be handled by the zimic mock server with the mock applied

// getting requests is also an asynchronous operation
const getRequests = await getTracker.requests();
expect(getRequests).toHaveLength(1);

Project setup

HTTP mock server

Discussion: #75

Consider removing the platform parameter from worker factories. We can infer the platform automatically.

Validate that the versions between the zimic client and the zimic server are equal on connection.
Think about easing the migration from local to remote (users have to add await to every mock applied)
- Codemod?

Examples projects with third-party integrations (part 1)

Example projects

HTTP interceptor defaults

The HTTP interceptor should support:
- Defining default handlers, validated statically based on the service schema in the HTTP interceptor factory

End-to-end tests with dependent code and third-party libraries

Add e2e tests using fetch
Add e2e tests using axios
Add e2e tests using superagent
Add e2e tests using node-fetch

v0.3.0 documentation

Document API changes introduced in v0.3.0
- README.md
- Code documentation with JSDoc
Add examples to headline links to README
Change examples in README to follow the new strict JSON validation.

Contributing guide

Expectation about no unused handlers

The HTTP interceptor should support:

A method to throw an error if not all handlers were used:

expectNoUnusedHandlers(): void;

Example:

afterAll(() => {
  authInterceptor.expectNoUnusedHandlers();
});

HTTP interceptor request match by path params

The HTTP request tracker should support:

Defining expanded route params to match requests

const getTracker = authInterceptor
  .get('/users/:id')
  .with({ pathParams: { id: user.id } })
  .respond({
    status: 200,
    body: user,
  });

// Code to test
const response = await getUserById(user.id);

expect(response.status).toBe(200);

const returnedUsers = (await response.json()) as User[];
expect(returnedUsers).toEqual([user]);

const getRequests = getTracker.requests();
expect(getRequests).toHaveLength(1);

// Simpler alternative:
// expect(getRequests[0].routeParams).toEqual({ id: user.id });

expect(getRequests[0].routeParams.id).toBe(user.id);

Defining inline route params to match requests

const getTracker = authInterceptor.get(`/users/${user.id}`).respond({
  status: 200,
  body: user,
});

// Code to test
const response = await getUserById(user.id);

expect(response.status).toBe(200);

const returnedUsers = (await response.json()) as User[];
expect(returnedUsers).toEqual([user]);

const getRequests = getTracker.requests();
expect(getRequests).toHaveLength(1);

// Simpler alternative:
// expect(getRequests[0].routeParams).toEqual({});

expect(getRequests[0].routeParams.id).toBe(undefined);

Include Bun and Deno in CI end-to-end tests

HTTP interceptor request match by headers

The HTTP request tracker should support:

Defining headers to match requests

Receiving a second, optional argument to whether the match should be exact or not (default: false)

const listTracker = authInterceptor
  .get('/users')
  .with({
    headers: { 'content-type': 'application/json' },
    exact: true,
  })
  .respond({
    status: 200,
    body: [user],
  });

Examples projects with third-party integrations (part 2)

Example projects

Improve example gitignore files
Try to improve types check and eslint to be more independent of the monorepo
Simplify example configs

How to use zimic to intercept Supabase Auth?

Hi, @diego-aquino

I'm trying to use zimic with supabase.

scenario:

const supabaseInterceptor = createHttpInterceptor<{
	'/auth/v1/admin/users': {
		POST: {
			request: {
				body: { email: '[email protected]'; password: '123456' }
			}
			response: {
				200: { body: { user: { id: '123' } } }
			}
		}
	}
}>({
	worker,
	baseURL: 'http://localhost:8000'
})

My supabase environtment:

SUPABASE ENVS

SUPABASE_URL=http://localhost:8000

Details:

node: 20.10.0
honojs: 4.0.0

Error message:

ConnectionRefused: Unable to connect. Is the computer able to access the url?
path: "http://localhost:8000/auth/v1/admin/users"

Keep going! amazing work here!

Access to raw intercepted requests and responses

Release action setup

Create partial release on GitHub after a (protected) partial tag is created (e.g. v0.1.0-canary.0)
Create full release on GitHub after a (protected) full tag is created (e.g. v0.1.0)
Create CLI to upgrade versions and create tags and release branches automatically
Create NPM release action (partial and full versions)

Base HTTP interceptor

Support to body, search params, route params and form data will be added in the future.

Reserve `zimic` on npm

HTTP interceptor request search params

Browser service worker init

Remove zimic test postinstall

HTTP interceptor request match by body

The HTTP request tracker should support:

Defining a body to match requests

Receiving a second, optional argument to whether the match should be exact or not (default: false)

const creationTracker = authInterceptor
  .post('/users')
  .with({
    body: creationPayload,
  }, { exact: true })
  .respond({
    status: 201,
    body: user,
  });

v0.1.0 documentation

v0.2.0 documentation

Browser service worker init not working on NPM

> pnpm zimic browser init public
[zimic] Copying the service worker script to ~/zimic/apps/zimic-test-client/public...
cli.js browser init <publicDirectory>

Initialize the browser service worker

Positionals:
  publicDirectory  The path to the public directory of your application
                                                             [string] [required]

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

[Error: ENOENT: no such file or directory, copyfile '~/zimic/node_modules/.pnpm/[email protected][email protected]/node_modules/zimic/node_modules/msw/lib/mockServiceWorker.js' -> '~/www/zimic/apps/zimic-test-client/public/mockServiceWorker.js'] {
  errno: -2,
  code: 'ENOENT',
  syscall: 'copyfile',
  path: '~/www/zimic/node_modules/.pnpm/[email protected][email protected]/node_modules/zimic/node_modules/msw/lib/mockServiceWorker.js',
  dest: '~/www/zimic/apps/zimic-test-client/public/mockServiceWorker.js'
}

HTTP interceptor request headers

Interceptor type schema auto-generation from OpenAPI/Swagger

Following the discussions on #21, Zimic will support inferring and generating interceptor type schema from OpenAPI/Swagger specifications. Learn more at the section "Alternative 3" of the summary comment.

HTTP interceptor request match by search params

The HTTP request tracker should support:

Defining search params to match requests

Receiving an optional argument to whether the match should be exact or not (default: false)

const listTracker = authInterceptor
  .get('/users')
  .with({
    searchParams: { name: nameToFilter },
    exact: true
  })
  .respond({
    status: 200,
    body: [user],
  });

Custom unhandled request strategies

An HTTP interceptor should support:
- A custom unhandled request strategy: 'ignore' | 'warn' or a function receiving a request. The default is 'warn'.
- When the modes are 'ignore' and 'warn', output structured logs containing all relevant fields of the request, to help developers know which specific requests were not matched. For example:
```
[zimic] Request did not match any filters: Request { headers: { 'content-type': 'application/json' }, body: 'message' }
```

v0.4.0 documentation

Create v1 API draft examples

Example 1

import * as crypto from 'crypto';
import { createHttpInterceptor } from './lib';
import { describe, beforeEach, it, expect, afterAll } from '../common/test';

interface User {
  id: string;
  name: string;
  email: string;
}

interface UserWithPassword extends User {
  password: string;
}

type UserCreationPayload = Omit<UserWithPassword, 'id'>;

interface LoginResult {
  accessToken: string;
  refreshToken: string;
}

interface RequestError {
  code: string;
  message: string;
}

interface ValidationError extends RequestError {
  code: 'validation_error';
}

interface UnauthorizedError extends RequestError {
  code: 'unauthorized';
}

interface NotFoundError extends RequestError {
  code: 'not_found';
}

interface ConflictError extends RequestError {
  code: 'conflict';
}

const authInterceptor = createHttpInterceptor<{
  '/users': {
    POST: {
      request: {
        body: UserCreationPayload;
      };
      response: {
        201: { body: User };
        400: { body: ValidationError };
        409: { body: ConflictError };
      };
    };

    GET: {
      request: {
        searchParams: {
          name?: string;
          email?: string;
        };
      };
      response: {
        200: { body: User[] };
      };
    };
  };

  '/users/:id': {
    GET: {
      request: {
        routeParams: { id: string };
      };
      response: {
        200: { body: User };
        404: { body: NotFoundError };
      };
    };
    PATCH: {
      request: {
        headers: { authorization: string };
        routeParams: { id: string };
        body: Partial<User>;
      };
      response: {
        200: { body: User };
        404: { body: NotFoundError };
      };
    };
    DELETE: {
      request: {
        headers: { authorization: string };
        routeParams: { id: string };
      };
      response: {
        204: { body: void };
        404: { body: NotFoundError };
      };
    };
  };

  '/session/login': {
    POST: {
      request: {
        body: {
          email: string;
          password: string;
        };
      };
      response: {
        201: { body: LoginResult };
        400: { body: ValidationError };
        401: { body: UnauthorizedError };
      };
    };
  };

  '/session/refresh': {
    POST: {
      request: {
        body: { refreshToken: string };
      };
      response: {
        201: { body: LoginResult };
        401: { body: UnauthorizedError };
      };
    };
  };

  '/session/logout': {
    POST: {
      request: {
        headers: { authorization: string };
      };
      response: {
        204: { body: void };
        401: { body: UnauthorizedError };
      };
    };
  };
}>({
  baseURL: 'https://localhost:3000',
  unhandledRequestStrategy: 'error',
  defaults: {
    '/users': {
      GET: {
        response: {
          status: 200,
          body: [],
        },
      },
    },

    '/users/:id': {
      GET: {
        response: {
          status: 404,
          body: {
            code: 'not_found',
            message: 'User not found',
          },
        },
      },
    },
  },
});

describe('Users', () => {
  const user: User = {
    id: crypto.randomUUID(),
    name: 'Name',
    email: '[email protected]',
  };

  beforeEach(() => {
    authInterceptor.clearHandlers();
  });

  afterAll(() => {
    authInterceptor.expectNoUnusedHandlers();
  });

  describe('User creation', () => {
    const creationPayload: UserCreationPayload = {
      name: user.name,
      email: user.email,
      password: 'password',
    };

    async function createUser(payload: UserCreationPayload) {
      return await fetch('https://localhost:3000/users', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(payload),
      });
    }

    it('should support creating users - alternative 1', async () => {
      const creationTracker = authInterceptor
        .post('/users')
        .with({
          body: creationPayload,
        })
        .respond({
          status: 201,
          body: user,
        });

      // Code to test
      const response = await createUser(creationPayload);

      expect(response.status).toBe(201);

      const createdUser = (await response.json()) as User;
      expect(createdUser).toEqual(user);

      const creationRequests = creationTracker.requests();
      expect(creationRequests).toHaveLength(1);

      // Simpler alternative:
      // expect(creationRequests[0].body).toEqual(creationPayload);

      expect(creationRequests[0].body.name).toBe(creationPayload.name);
      expect(creationRequests[0].body.email).toBe(creationPayload.email);
      expect(creationRequests[0].body.password).toBe(creationPayload.password);
    });

    it('should support creating users - alternative 2', async () => {
      const creationTracker = authInterceptor.post('/users').respond({
        status: 201,
        body: user,
      });

      // Code to test
      const response = await createUser(creationPayload);

      expect(response.status).toBe(201);

      const createdUser = (await response.json()) as User;
      expect(createdUser).toEqual(user);

      const creationRequests = creationTracker.requests();
      expect(creationRequests).toHaveLength(1);

      // Simpler alternative:
      // expect(creationRequests[0].body).toEqual(creationPayload);

      expect(creationRequests[0].body.name).toBe(creationPayload.name);
      expect(creationRequests[0].body.email).toBe(creationPayload.email);
      expect(creationRequests[0].body.password).toBe(creationPayload.password);
    });

    it('should return an error if the payload is not valid', async () => {
      // @ts-expect-error Forcing an invalid payload
      const invalidPayload: UserCreationPayload = {};

      const creationTracker = authInterceptor
        .post('/users')
        .with({
          body: invalidPayload,
        })
        .respond({
          status: 400,
          body: {
            code: 'validation_error',
            message: 'Invalid payload',
          },
        });

      // Code to test
      const response = await createUser(invalidPayload);

      expect(response.status).toBe(400);

      const creationRequests = creationTracker.requests();
      expect(creationRequests).toHaveLength(1);

      expect(creationRequests[0].body).toEqual(invalidPayload);
    });

    it('should return an error if the payload is not valid', async () => {
      const conflictingPayload: UserCreationPayload = creationPayload;

      const creationTracker = authInterceptor
        .post('/users')
        .with({
          body: conflictingPayload,
        })
        .respond({
          status: 409,
          body: {
            code: 'conflict',
            message: 'User already exists',
          },
        });

      // Code to test
      const response = await createUser(conflictingPayload);

      expect(response.status).toBe(409);

      const creationRequests = creationTracker.requests();
      expect(creationRequests).toHaveLength(1);

      expect(creationRequests[0].body).toEqual(conflictingPayload);
    });
  });

  describe('User list', () => {
    async function listUsers(filters: { name?: string; email?: string } = {}) {
      const searchParams = new URLSearchParams(filters);
      return await fetch(`https://localhost:3000/users?${searchParams}`, { method: 'GET' });
    }

    it('should list users filtered by name', async () => {
      const nameToFilter = 'nam';

      const listTracker = authInterceptor
        .get('/users')
        .with({
          searchParams: { name: nameToFilter },
        })
        .respond({
          status: 200,
          body: [user],
        });

      // Code to test
      const response = await listUsers({ name: nameToFilter });

      expect(response.status).toBe(200);

      const returnedUsers = (await response.json()) as User[];
      expect(returnedUsers).toEqual([user]);

      const listRequests = listTracker.requests();
      expect(listRequests).toHaveLength(1);

      // Simpler alternative:
      // expect(listInterceptions[0].searchParams).toEqual(
      //   new URLSearchParams({
      //     name: nameToFilter,
      //   }),
      // );

      expect(listRequests[0].searchParams.size).toBe(1);
      expect(listRequests[0].searchParams.get('name')).toBe(nameToFilter);
    });
  });

  describe('User get by id', () => {
    async function getUserById(userId: string) {
      return await fetch(`https://localhost:3000/users/${userId}`, { method: 'GET' });
    }

    it('should support getting users by id - alternative 1', async () => {
      const getTracker = authInterceptor
        .get('/users/:id')
        .with({ routeParams: { id: user.id } })
        .respond({
          status: 200,
          body: user,
        });

      // Code to test
      const response = await getUserById(user.id);

      expect(response.status).toBe(200);

      const returnedUsers = (await response.json()) as User[];
      expect(returnedUsers).toEqual([user]);

      const getRequests = getTracker.requests();
      expect(getRequests).toHaveLength(1);

      // Simpler alternative:
      // expect(getRequests[0].routeParams).toEqual({ id: user.id });

      expect(getRequests[0].routeParams.id).toBe(user.id);
    });

    it('should support getting users by id - alternative 2', async () => {
      const getTracker = authInterceptor.get<'/users/:id'>(`/users/${user.id}`).respond({
        status: 200,
        body: user,
      });

      // Code to test
      const response = await getUserById(user.id);

      expect(response.status).toBe(200);

      const returnedUsers = (await response.json()) as User[];
      expect(returnedUsers).toEqual([user]);

      const getRequests = getTracker.requests();
      expect(getRequests).toHaveLength(1);

      // Simpler alternative:
      // expect(getRequests[0].routeParams).toEqual({});

      expect(getRequests[0].routeParams.id).toBe(undefined);
    });

    it('should return an error if the user was not found', async () => {
      const getTracker = authInterceptor
        .get('/users/:id')
        .with({
          routeParams: { id: user.id },
        })
        .respond({
          status: 404,
          body: {
            code: 'not_found',
            message: 'User not found',
          },
        });

      // Code to test
      const response = await getUserById(user.id);

      expect(response.status).toBe(404);

      const getRequests = getTracker.requests();
      expect(getRequests).toHaveLength(1);

      // Simpler alternative:
      // expect(getRequests[0].routeParams).toEqual({});

      expect(getRequests[0].routeParams.id).toBe(user.id);
    });
  });

  describe('User deletion', () => {
    async function deleteUserById(userId: string) {
      return await fetch(`https://localhost:3000/users/${userId}`, { method: 'DELETE' });
    }

    it('should support deleting users by id', async () => {
      const deleteTracker = authInterceptor
        .delete('/users/:id')
        .with({ routeParams: { id: user.id } })
        .respond({
          status: 204,
        });

      // Code to test
      const response = await deleteUserById(user.id);

      expect(response.status).toBe(204);

      const deleteRequests = deleteTracker.requests();
      expect(deleteRequests).toHaveLength(1);

      // Simpler alternative:
      // expect(deleteRequests[0].routeParams).toEqual({ id: user.id });

      expect(deleteRequests[0].routeParams.id).toBe(user.id);
    });

    it('should return an error if the user was not found', async () => {
      const getTracker = authInterceptor
        .delete('/users/:id')
        .with({
          routeParams: { id: user.id },
        })
        .respond({
          status: 404,
          body: {
            code: 'not_found',
            message: 'User not found',
          },
        });

      // Code to test
      const response = await deleteUserById(user.id);

      expect(response.status).toBe(404);

      const getRequests = getTracker.requests();
      expect(getRequests).toHaveLength(1);

      // Simpler alternative:
      // expect(getRequests[0].routeParams).toEqual({});

      expect(getRequests[0].routeParams.id).toBe(user.id);
    });
  });
});

Example 2

import * as crypto from 'crypto';
import { createHttpInterceptor } from './lib';
import { describe, beforeEach, it, expect, afterAll } from '../common/test';

interface User {
  id: string;
  name: string;
  email: string;
}

interface UserWithPassword extends User {
  password: string;
}

type UserCreationPayload = Omit<UserWithPassword, 'id'>;

interface RequestError {
  code: string;
  message: string;
}

interface ValidationError extends RequestError {
  code: 'validation_error';
}

interface ConflictError extends RequestError {
  code: 'conflict';
}

const authInterceptor = createHttpInterceptor<{
  '/users': {
    POST: {
      request: {
        body: UserCreationPayload;
      };
      response: {
        201: { body: User };
        400: { body: ValidationError };
        409: { body: ConflictError };
      };
    };
  };
}>({
  baseURL: 'https://localhost:3000',
  unhandledRequestStrategy: 'error',
  defaults: {
    '/users': {
      POST: {
        response: {
          status: 400,
          body: {
            code: 'validation_error',
            message: 'Invalid payload',
          },
        },
      },
    },
  },
});

const user: User = {
  id: crypto.randomUUID(),
  name: 'Name',
  email: '[email protected]',
};

const creationPayload: UserCreationPayload = {
  name: user.name,
  email: user.email,
  password: 'password',
};

async function createUser(payload: UserCreationPayload) {
  return await fetch('https://localhost:3000/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });
}

describe('Users', () => {
  beforeEach(() => {
    authInterceptor.clearHandlers();
  });

  afterAll(() => {
    authInterceptor.expectNoUnusedHandlers();
  });

  describe('User creation', () => {
    it('should support creating users', async () => {
      const creationTracker = authInterceptor
        .post('/users')
        .with({
          body: creationPayload,
        })
        .respond({
          status: 201,
          body: user,
        });

      // Code to test
      const response = await createUser(creationPayload);
      expect(response.status).toBe(201);

      const creationRequests = creationTracker.requests();
      expect(creationRequests).toHaveLength(1);

      expect(creationRequests[0].body.name).toBe(creationPayload.name);
      expect(creationRequests[0].body.email).toBe(creationPayload.email);
      expect(creationRequests[0].body.password).toBe(creationPayload.password);
    });
  });
});

Example 3

import * as crypto from 'crypto';

import { createHttpInterceptor } from './lib';
import { describe, beforeEach, it, expect, afterAll } from '../common/test';

export interface UserCreationPayload {
  name: string;
  email: string;
  password: string;
}

export interface User {
  id: string;
  name: string;
  email: string;
}

export interface ValidationErrorResponse {
  code: 'validation_error';
  message: string;
}

export const authInterceptor = createHttpInterceptor<{
  '/users': {
    POST: {
      request: {
        body: UserCreationPayload;
      };
      response: {
        201: { body: User };
        400: { body: ValidationErrorResponse };
      };
    };
  };
}>({
  baseURL: 'http://localhost:3000',
  unhandledRequestStrategy: 'error',
  defaults: {
    '/users': {
      POST: {
        response: {
          status: 400,
          body: {
            code: 'validation_error',
            message: 'Validation error',
          },
        },
      },
    },
  },
});

async function createUser(payload: UserCreationPayload) {
  return fetch('https://localhost:3000/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });
}

describe('Users', () => {
  const user: User = {
    id: crypto.randomUUID(),
    name: 'Name',
    email: '[email protected]',
  };

  beforeEach(() => {
    authInterceptor.clearHandlers();
  });

  afterAll(() => {
    authInterceptor.expectNoUnusedHandlers();
  });

  describe('User creation', () => {
    it('should support creating users', async () => {
      const creationPayload: UserCreationPayload = {
        name: user.name,
        email: user.email,
        password: 'password',
      };

      const creationTracker = authInterceptor
        .post('/users')
        .with({
          body: creationPayload,
        })
        .respond({
          status: 201,
          body: user,
        });

      // Code to test
      const response = await createUser(creationPayload);
      expect(response.status).toBe(201);

      const creationRequests = creationTracker.requests();

      expect(creationRequests).toHaveLength(1);

      expect(creationRequests[0].body.name).toBe(creationPayload.name);
      expect(creationRequests[0].body.email).toBe(creationPayload.email);
      expect(creationRequests[0].body.password).toBe(creationPayload.password);
    });
  });
});

Example 4

import * as crypto from 'crypto';
import { createHttpInterceptor } from './lib';
import { describe, beforeEach, it, expect, afterAll } from '../common/test';

interface User {
  id: string;
  name: string;
  email: string;
}

interface UserWithPassword extends User {
  password: string;
}

type UserCreationPayload = Omit<UserWithPassword, 'id'>;

interface RequestError {
  code: string;
  message: string;
}

interface ValidationError extends RequestError {
  code: 'validation_error';
}

interface ConflictError extends RequestError {
  code: 'conflict';
}

const authInterceptor = createHttpInterceptor<{
  '/users': {
    POST: {
      request: {
        formData: UserCreationPayload;
      };
      response: {
        201: { body: User };
        400: { body: ValidationError };
        409: { body: ConflictError };
      };
    };
  };
}>({
  baseURL: 'https://localhost:3000',
  unhandledRequestStrategy: 'error',
});

const user: User = {
  id: crypto.randomUUID(),
  name: 'Name',
  email: '[email protected]',
};

const creationPayload: UserCreationPayload = {
  name: user.name,
  email: user.email,
  password: 'password',
};

async function createUser(payload: UserCreationPayload) {
  return await fetch('https://localhost:3000/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });
}

describe('Users', () => {
  beforeEach(() => {
    authInterceptor.clearHandlers();
  });

  afterAll(() => {
    authInterceptor.expectNoUnusedHandlers();
  });

  describe('User creation', () => {
    it('should support creating users', async () => {
      const creationTracker = authInterceptor
        .post('/users')
        .with({
          formData: creationPayload,
        })
        .respond({
          status: 201,
          body: user,
        });

      // Code to test
      const response = await createUser(creationPayload);
      expect(response.status).toBe(201);

      const creationRequests = creationTracker.requests();
      expect(creationRequests).toHaveLength(1);

      expect(creationRequests[0].formData.get('name')).toBe(creationPayload.name);
      expect(creationRequests[0].formData.get('email')).toBe(creationPayload.email);
      expect(creationRequests[0].formData.get('password')).toBe(creationPayload.password);
    });
  });
});

v1.1.0 documentation

v0.7.0 documentation

Service schema typegen brainstorming

Initial ideas

Alternative 1

Utility package to be installed in client apps, supporting schema typegen generation by CLI

Workflow:
1. [mocked service] Install the utility package and export the types of all endpoints, using a terminal command
2. [intermediate package] Commit/upload typegen files to a common package
3. [tested service] Install the intermediate package and import the typegen to use in the HTTP interceptor factories
Notices:
- Dependent of frameworks used in the mocked service (many adapters are necessary)
- Dependent of programming languages used in the mocked service (many implementations are necessary)

Alternative 2

Utility package to be installed in client apps, supporting schema typegen generation by using the app

Workflow:
1. [tested service] Install the utility package and use the service normally
2. [tested service] The utility package tracks the requests being made and saves the found types to a typegen file
3. [tested service] Import the typegen to use in the HTTP interceptor factories
Notices:
- Independent of frameworks used in the mocked service
- Independent of programming languages used in the mocked service
- Relies that the user runs the program "in real life", outside the mocked tests, such as e2e

Alternative 3

Runtime endpoint specification

Workflow:
1. [mocked service] Install a utility package that generates the specification based on the endpoints (e.g. OpenAPI)
2. [mocked service] Create an endpoint that serves the endpoint specification
3. [tested service] Terminal command (or automatically before tests) fetches the specification endpoint and creates the typegen
4. [tested service] Import the typegen to use in the HTTP interceptor factories
Notices:
- Dependent of frameworks used in the mocked service
- Dependent of programming languages used in the mocked service
- HTTP-only if OpenAPI is used
- Works the same as the Alternative 1, but excluding the intermediate package
- Might be the most feasible solution (see https://github.com/drwpow/openapi-typescript)

Include TypeScript versions since 4.7 in CI type tests (matrix)

Service schema typegen ideas

Definitions

Mocked service: application to which Zimic mocks are targeted
Client application: application that consumes the mocked service and where Zimic mocks are applied

Initial ideas

Alternative 1: Types inferred from source code

Assessment: promising, not feasible directly.

A utility package could be installed in a mocked service, allowing automatic schema type generation by a CLI. The generated types are exported to an intermediate package that must be imported by client apps.

Workflow:
1. [mocked service] Install the utility package.
2. [mocked service] Use helpers to "mark" endpoints and extract type schema? Infer type schema from framework utilities?
3. Idea 1: declare the schema manually and provide utilities to validate if the endpoints are following it (promising)
4. Idea 2: derive the schema from an OpenAPI specification and provide utilities to validate if the endpoints are following it
5. [mocked service] Generate type schema of all of the endpoints using a CLI.
6. [intermediate package] Commit and upload the generated types to a shared package.
7. [client app] Install the intermediate package and import the generated types when creating interceptors.
Pros:
- Type schema is derived directly from the source code in the mocked service.
- A static type check could be integrated to CI environments to verify if the mocks are using valid types.
Cons:
- Dependent of which framework or code patterns where used in the mocked service.
  - Adapters might be necessary.
  - Code markers might be necessary.
- Not easily portable to mocked services using programming languages different from TypeScript.
- Requires an intermediate types package.
- Does not work if the client app developer does not have access to the source code of the mocked service (e.g. GitHub API could not be used)

Alternative 2: Types inferred from real requests

Assessment: not promising, requires manual intervention and is error prone.

A utility package could be installed in client apps, allowing automatic schema type generation by inferring the types from real requests.

Workflow:
1. [tested service] Install the utility package.
2. [tested service] The client app makes requests to the mocked service, without any mocks applied. The requests reach the real service,
3. [tested service] The utility package tracks the sent requests and generates the type schema.
4. [tested service] The generated schema can be used when creating interceptors.
Pros:
- Type schema is derived directly from the behavior of the mocked service.
- Independent of frameworks used in the mocked service.
- Independent of programming languages used in the mocked service.
- Does not use intermediate packages.
- Does not require changes to the source code of the mocked service (e.g. GitHub API could be used).
Cons:
- Relies that the client app developer runs the program reaching the real mocked service at least once for each possible request and response types.
- Type schema cannot be easily generated and validated as part of a CI workflow.

Alternative 3: Types derived from endpoint specification

Assessment: most promising, will be implemented into Zimic.

Having access to the mocked service endpoint specification, Zimic could automatically generate the type schemas. The endpoint specification could follow the standard OpenAPI.

Workflow:
1. [mocked service] Provide a path to get the OpenAPI specification of the service endpoints.
2. [tested service] Fetch the OpenAPI specification and generate the type schema, by CLI or script.
3. [tested service] The generated schema can be used when creating interceptors.
Pros:
- Type schema is derived directly from the expected behavior of the mocked service.
- A static type check could be integrated to CI environments to verify if the mocks are using valid types.
- Independent of frameworks used in the mocked service.
- Independent of programming languages used in the mocked service.
- Does not use intermediate packages.
- Does not require changes to the source code of the mocked service (e.g. GitHub API could be used).
- There are already utility types that convert OpenAPI to TypeScript types (see https://github.com/drwpow/openapi-typescript and https://github.com/anymaniax/orval).
Cons:
- Requires the mocked service to provide an OpenAPi specification.
- Although OpenAPI is comprehensive, there are no guarantees that the code of the mocked service is following the specification, as it is not statically enforced. However, other programming languages do not have the TypeScript's rich ability to derive types, so this might not be a big problem.
- HTTP-only if OpenAPI is used.

Extra: OpenAPI auto-generation

There could be ways to infer the OpenAPI specification from the source code of the mocked service. By doing this, alternatives 1 and 3 are combined:

If the mocked service already has an OpenAPI specification, it could be used by client apps to generate the type schema for mocks.
If the mocked service does not have an OpenAPI specification, it could be generated from the source code and provided in one of the endpoints or file, which could be accessed by client apps to generate the type schema for mocks.

See:

Access to the intercepted requests

The HTTP request tracker should support:
- Accessing the data of the intercepted requests, to allow assertions in client code
This implementation should include tests in an example client, using all the implemented features and APIs. This is important to feel how intuitive the API is and ensure that current behaviors are not broken in the future.

diego-aquino / zimic Goto Github PK

zimic's Issues

Context

Proposal 1: mocks applied directly to the remote process

Solution

API

Proposal 2: Zimic mock server

Solution

API examples

Example projects

Example projects

scenario:

SUPABASE ENVS

Details:

Error message:

Example 1

Example 2

Example 3

Example 4

Initial ideas

Alternative 1

Alternative 2

Alternative 3

Definitions

Initial ideas

Alternative 1: Types inferred from source code

Alternative 2: Types inferred from real requests

Alternative 3: Types derived from endpoint specification

Extra: OpenAPI auto-generation

Recommend Projects

Recommend Topics

Recommend Org