jest-runner-tsd

Run your TypeScript type tests using Jest.

Note: the jest-runner-tsd is using tsd-lite instead of tsd. Both of them have the same type testing logic, but tsd-lite makes it easier to test projects written in TypeScript (or types generated by your library).

Most important differences (for the full list see tsd-lite repo):

• tsd-lite has no additional rules or checks;
• jest.config is used to discover test files;
• tsconfig.json provides configuration for TS compiler. For details see Configuration section;
• the type assertions must be imported from tsd-lite package.

Install

yarn add --dev jest-runner-tsd @tsd/typescript
# or
npm install --save-dev jest-runner-tsd @tsd/typescript

Remember to install @tsd/typescript package. It is a required peer dependency.

Note that @tsd/typescript will be used to compile type tests. Generally it is recommended to match versions of @tsd/typescript and typescript in a project, but you may choose to test on different version too.

Configuration

Jest

First of all, you should configure Jest to discover your test files. For example, if the files have .test.ts suffix and live inside __typetests__ directories, set up jest.config.tsd.js like this:

module.exports = {
  displayName: {
    color: 'blue',
    name: 'types',
  },
  runner: 'jest-runner-tsd',
  testMatch: ['**/__typetests__/*.test.ts'],
};

TS Compiler

Your test files will be compiled using the TypeScript compiler (similar to tsc), but, instead of emitting JS code, tsd-lite will analyze types and diagnostics returned by the compiler.

To compile each test file, tsd-lite will read the nearest tsconfig.json and will pass the configuration to the compiler. Hence, you may have a configuration for the whole project, or a group of test files, or just a particular test file.

For example, if your project already includes a tsconfig.json in the root directory, but you prefer to have different configuration for testing, simply add another tsconfig.json to a directory with the test files. It may override or extend your root configuration.

Tip: run yarn tsc -p path/to/__typetests__ --showConfig to print the configuration which applies to the test files.

Note: if tsconfig.json is not found, the compiler will fall back to the default configuration.

Optionally Strict

Just like TypeScript, tsd-lite is optionally strict. In contrary, the vanilla tsd is strict by default. If you are migrating your test suite, remember to set "strict": true in tsconfig.json.

import { expectType } from 'tsd-lite';

declare const loggedInUsername: string;

const users = [
  { name: 'Oby', age: 12 },
  { name: 'Heera', age: 32 },
];

const loggedInUser = users.find(u => u.name === loggedInUsername);

expectType<number>(loggedInUser.age);

The assertion in this example fails with "strict": true, but passes with "strict": false.

Writing Tests

Let's say you defined a JsonObject type:

// JsonObject.ts
type JsonValue = string | number | boolean | JsonObject | Array<JsonValue>;

export interface JsonObject {
  [key: string]: JsonValue;
}

It is relatively complex, so it is worth adding a type test to prevent mistakes and regression in the future:

// __typetests__/JsonObject.test.ts
import { expectAssignable, expectNotAssignable } from 'tsd-lite';
import type { JsonObject } from '../JsonObject.js';

expectAssignable<JsonObject>({
  caption: 'test',
  count: 100,
  isTest: true,
  location: { name: 'test', start: [1, 2], valid: false, x: 10, y: 20 },
  values: [0, 10, 20, { x: 1, y: 2 }, true, 'test', ['a', 'b']],
});

expectNotAssignable<JsonObject>({
  filter: () => {},
});

Tip: For the full list of type testing assertions see the documentation of tsd-lite.

Running Tests

If all is set, simply run yarn jest --config jest.config.tsd.js command. Or better include a script in package.json:

"scripts": {
  "test:types": "jest --config jest.config.tsd.js"
}

License

MIT © Jest Community