Writing test is, essentially, making assertions. Most of the time, these assertions aim to check the runtime logic we implemented. But in some situations, we implement our own build-time logic: our own types. This article covers different use cases and tools we can use to write safer types.
Testing declarations files
Declarations files must be written manually for JavaScript modules with no types for them to be used in a TypeScript project.
Writing declarations is a tedious task and mistakes can be made. The DefinitelyTyped project (which provides many TypeScript declarations under the @types alias on npm) recommends writing tests to prevent these mistakes.
Declarations files tests in DefinitelyTyped rely on the project's internal tool: dtslint. Tests are a bit different from what we are used to in a test framework like Jest. They are like regular TypeScript files, but annotated with comments that do the actual assertion:
import { f } from "my-lib";
f(1);
f("one");
dtslint provides an environment that compares the declarations files with those tests.
For declarations files located on your project, DefinitelyTyped advises using the lib tsd instead. Both dtslint and tsd are meant to test declarations files only. In the next sections, we are going to explore other tools for other use cases.
Testing advanced types
Let's take the following custom type guard :
function isFish(animal: Fish | Bird): pet is Fish {
return (animal as Fish).swim !== undefined;
}
Like any other function, we would test its logic like so :
const someFish = new Fish();
expect(isFish(someFish)).toBe(true);
But in addition to runtime logic, custom type guards also bring build-time logic to the table: the type predicate. When used in a condition, this function can narrow its input to the type suggested after the keyword is.
Using ts-expect
This can be tested using ts-expect. This tool offers a "dumb" function and two generics that raise errors at compilation time if type constraints are not satisfied.
import { expectType } from "ts-expect";
if(isFish(animal)) {
expectType<Fish>(animal);
}
In this test, we check that animal is properly narrowed to Fish. If it compiles, that means the test is valid. Because this helper relies on a basic type inference from TypeScript, errors are easy to understand.
Because this logic is not meant to be executed, I would recommend writing it in dedicated test files. You would compile them using tsc with the --noEmit flag to prevent any output.
Using expect-type
expect-type is also interesting because it features an API similar to jest.
import { expectTypeOf } from 'expect-type';
if(isFish(animal)) {
expectTypeOf(animal).toEqualTypeOf<Fish>();
}
This library can be confusing because you can either pass an object as an argument to the function or pass a type using the generic of the function. Errors can also be a bit confusing compared to ts-expect.
Assertions that should not be satisfied
It can be useful to test the opposite assertion: to expect that a type does not satisfy another. Typescript, since version 3.9, provides a very powerful directive:
if(isFish(animal)) {
expectType<Fish>(animal);
expectType<Bird>(animal);
}
If for any reason the line following the directive doesn't raise an error, the comment itself will raise the error: Unused '@ts-expect-error' directive. ts(2578) . This can prevent your code to be "poisoned" with any declarations.
While this directive can be used with both libraries, expect-type provides the .not word to do "negative assertions" :
expectTypeOf(animal).not.toEqualTypeOf<Bird>();
tl;dr
You can use tsd to test your declarations files. If you want to test advanced types like custom type guards or bespoke generics, use can use ts-expect or expect-type. The @ts-expect-error directive can also be used to make sure your types are strict enough.
