vitest-utils

Shared utilities for the Vitest testing framework used across MapColonies packages.

Install

npm install --save-dev @map-colonies/vitest-utils
Copy

Peer dependencies (vitest, jest-openapi, jest-extended) are optional — install only what you use.

API documentation

Check the autogenerated documentation here.

Usage

reporters

A pre-configured reporters array for vitest.config.ts. Includes default and html reporters, and automatically adds github-actions when running in CI.

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import { reporters } from '@map-colonies/vitest-utils';

export default defineConfig({
  test: {
    reporters,
  },
});
Copy

getPathAlias

Converts compilerOptions.paths from a tsconfig.json into a Vitest resolve.alias map, keeping path aliases in sync between TypeScript and test runs.

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import { getPathAlias } from '@map-colonies/vitest-utils';
import tsconfigJson from './tsconfig.json';

export default defineConfig({
  resolve: {
    alias: getPathAlias(tsconfigJson, __dirname),
  },
});
Copy

setupOpenapi

Patches Vitest's expect into the global scope so that jest-openapi matchers (e.g. toSatisfyApiSpec) work inside Vitest tests. Resets the global after setup to avoid conflicts.

Recommended: call it from a Vitest setup file so it runs once for the entire suite.

// tests/setup.ts
import { setupOpenapi } from '@map-colonies/vitest-utils';

setupOpenapi('/absolute/path/to/openapi.yaml');
Copy

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    setupFiles: ['./tests/setup.ts'],
  },
});
Copy

Then use the matcher in your tests:

it('should satisfy the OpenAPI spec', async function () {
  const response = await supertest(app).get('/resource');
  expect(response).toSatisfyApiSpec();
});
Copy

Alternatively, call it inside a beforeAll when you need per-suite control:

beforeAll(function () {
  setupOpenapi('/absolute/path/to/openapi.yaml');
});
Copy

vitest-extended (side-effect import)

Registers all jest-extended matchers into Vitest's expect. Import it once from a setup file.

// tests/setup.ts
import '@map-colonies/vitest-utils/extended';
Copy

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    setupFiles: ['./tests/setup.ts'],
  },
});
Copy