How do I type-check Vitest or Jest test files in JavaScript?

The short answer

Import the test functions from vitest in each test file, and make sure jsconfig.json includes the tests:

import { describe, expect, it } from "vitest";
import { formatPrice } from "./price.js";

describe("formatPrice", () => {
  it("formats cents as dollars", () => {
    expect(formatPrice(1999)).toBe("$19.99");
  });

  it("uses the currency it is given", () => {
    expect(formatPrice(500, "EUR")).toBe("€5.00");
  });
});

import { describe, expect, it } from "vitest";
import { formatPrice } from "./price.js";

describe("formatPrice", () => {
  it("formats cents as dollars", () => {
    expect(formatPrice(1999)).toBe("$19.99");
  });

  it("uses the currency it is given", () => {
    expect(formatPrice(500, "EUR")).toBe("€5.00");
  });
});

describe, it and expect come with their types from the vitest package, and the calls into price.js are checked like any other code: a wrong argument in a test is an error before the test runs.

Why it works

Vitest ships its own type declarations, so an import is enough for tsc to find them; nothing extra goes in types. The test file is a normal module in the program, so everything it calls is checked against the JSDoc of the code under test. That is often where checking pays off first: tests call your functions in many ways.

If you prefer the global style (globals: true in the Vitest config), tell tsc about the globals by listing vitest/globals in types:

import { formatPrice } from "./price.js";

describe("formatPrice", () => {
  it("formats cents as dollars", () => {
    expect(formatPrice(1999)).toBe("$19.99");
  });
});

The same thing in TypeScript

The TypeScript equivalent tab of the first example is the same test as a .ts file. It imports ./price.js, the JavaScript module, which a TypeScript project can do with allowJs.

What goes wrong

Globals used without their types are unknown names. With a types list in the config, describe and it are TS2593, whose message suggests installing a test runner’s types, and expect is TS2304. The type error in the call to formatPrice is reported as well:

import { formatPrice } from "./price.js";

describe("formatPrice", () => {error TS2593: Cannot find name 'describe'. Do you need to install type definitions for a test runner? Try `npm i --save-dev @types/jest` or `npm i --save-dev @types/mocha` and then add 'jest' or 'mocha' to the types field in your tsconfig.
  it("formats cents as dollars", () => {error TS2593: Cannot find name 'it'. Do you need to install type definitions for a test runner? Try `npm i --save-dev @types/jest` or `npm i --save-dev @types/mocha` and then add 'jest' or 'mocha' to the types field in your tsconfig.
    expect(formatPrice("19.99")).toBe("$19.99");error TS2304: Cannot find name 'expect'.error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
  });
});

Gotchas

• TS2582 or TS2593. Without a types list the same missing globals are TS2582; with one, TS2593. Both mean “these names come from a test runner’s types”.
• Include the test files. A jsconfig.json whose include lists only src/**/*.js leaves test/ unchecked; add the test folder, or use a pattern that covers it.
• Matchers are loosely typed. expect(value).toBe(other) accepts any other, so assertions do not catch type mismatches the way calls to your code do.