Using headers

HTTP headers are key-value pairs that contain additional information about a request or a response. They are commonly used to pass metadata, such as a content type, authentication tokens, or caching directives.

Using request headers

To use headers in your intercepted requests, declare their types in your schema.

schema.ts

import { HttpSchema } from '@zimic/http';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    GET: {
      request: {
        headers: {
          authorization: string;
          'accept-language'?: string;
        };
      };
      response: {
        200: { body: User[] };
      };
    };
  };
}>;

Then, the request headers will be available in the headers property, such as in handler.with(), computed responses, and handler.requests. The headers are typed and validated according to your schema, providing type safety and autocompletion.

Local interceptor

const handler = interceptor
  .get('/users')
  .with({
    headers: {
      authorization: 'Bearer my-token',
      'accept-language': 'en',
    },
  })
  .respond((request) => {
    console.log(request.headers.get('authorization'));
    console.log(request.headers.get('accept-language'));

    return {
      status: 200,
      body: users,
    };
  })
  .times(1);

// Run the application and make requests...

console.log(handler.requests); // 1
console.log(handler.requests[0].headers.get('authorization'));
console.log(handler.requests[0].headers.get('accept-language'));

Remote interceptor

const handler = await interceptor
  .get('/users')
  .with({
    headers: {
      authorization: 'Bearer my-token',
      'accept-language': 'en',
    },
  })
  .respond((request) => {
    console.log(request.headers.get('authorization'));
    console.log(request.headers.get('accept-language'));

    return {
      status: 200,
      body: users,
    };
  })
  .times(1);

// Run the application and make requests...

console.log(handler.requests); // 1
console.log(handler.requests[0].headers.get('authorization'));
console.log(handler.requests[0].headers.get('accept-language'));

Using response headers

Similarly to requests, you can declare the types of response headers in your schema.

schema.ts

import { HttpSchema } from '@zimic/http';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    GET: {
      response: {
        200: {
          headers: {
            'content-type': 'application/json';
            'content-language'?: string;
          };
          body: User[];
        };
      };
    };
  };
}>;

When sending a response to an intercepted request, you can set the headers in the handler.respond method with the headers property.

Local interceptor

interceptor
  .get('/users')
  .respond({
    status: 200,
    headers: {
      'content-type': 'application/json',
      'content-language': 'en',
    },
    body: users,
  })
  .times(1);

Remote interceptor

await interceptor
  .get('/users')
  .respond({
    status: 200,
    headers: {
      'content-type': 'application/json',
      'content-language': 'en',
    },
    body: users,
  })
  .times(1);

Using cookies

Cookies can store data on the client side and are often used for authentication, session management, and tracking user preferences.

Since cookies are a type of header, you can use them in the same way as other headers, declaring them in your schema and accessing them in requests and responses.

schema.ts

import { HttpSchema } from '@zimic/http';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    GET: {
      request: {
        // For cookies sent in requests by the client
        headers: { cookie?: string };
      };
      response: {
        200: {
          // For cookies returned in responses by the server
          headers: { 'set-cookie'?: string };
          body: User[];
        };
      };
    };
  };
}>;

Local interceptor

import { createHttpInterceptor } from '@zimic/interceptor';

const interceptor = createHttpInterceptor<Schema>({
  baseURL: 'http://localhost:3000',
});

interceptor
  .get('/users')
  .with({
    headers: { cookie: 'sessionId=1e9f65ab; theme=dark' },
  })
  .respond((request) => {
    console.log(request.headers.get('cookie'));

    return {
      status: 200,
      headers: { 'set-cookie': 'sessionId=1e9f65ab; theme=dark' },
      body: users,
    };
  })
  .times(1);

Remote interceptor

import { createHttpInterceptor } from '@zimic/interceptor';

const interceptor = createHttpInterceptor<Schema>({
  baseURL: 'http://localhost:3000',
});

await interceptor
  .get('/users')
  .with({
    headers: { cookie: 'sessionId=1e9f65ab; theme=dark' },
  })
  .respond((request) => {
    console.log(request.headers.get('cookie'));

    return {
      status: 200,
      headers: { 'set-cookie': 'sessionId=1e9f65ab; theme=dark' },
      body: users,
    };
  })
  .times(1);

INFO: Cookies in browsers

Cookies are automatically sent by a browser, so you don't need to manually set them when making requests. For more information about cookies, see the MDN documentation.

WARNING: HttpOnly cookies

Cookies marked with the HttpOnly flag are not accessible via client-side JavaScript. Even though they may be in your schema and included in the requests, you won't be able to access them in interceptors running on a browser, only on the server.