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

``bash
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

$3

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:

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

$3

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.

$3

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.

`ts
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(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:

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

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:

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

expectAssignable({
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({
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:

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

License

MIT © Jest Community