Is type testing with TypeScript worth it?

Recently I posted about this commenting on Type-Testing, and it went so well! I was really happy about all the comments and questions people left there.

Because of the reach and because many people had some really relevant questions, I decided to write a longer article about the topic, explaining more deeply how everything works and what this type-testing thing is.

Type-Testing?#

That’s right, there’s another way to do tests that isn’t a unit test or an integration test. These are type tests.

The idea of type testing is being able to test whether the typing you’ve given to a certain function or file is correct. Think of it as a test, but for your types instead of your code.

Ideally a type test won’t even run. All the code will just be compiled by TypeScript and that result will be shown to you to indicate whether your typing is correct or not. This ensures that whoever uses the application has a guarantee that the types match what’s being provided.

How to test types#

There are several ways to do this. The simplest is basically to call the typing of the application you want to test, and make heavy use of directives like // @ts-expect-error that will act as a negative test, ensuring that your type is also providing an error when expected.

Let me talk about this PR again, but I recently added typing for a library that didn’t have native typing through .d.ts files in DefinitelyTyped. In the test files, we have to import our types and test them as if we were calling the application:

1
import keychain = require('keychain');
2

3
/**
4
 * setPassword
5
 */
6

7
// @ts-expect-error
8
// Errors when doesn't have the required properties
9
keychain.setPassword({ account: 'some-account' }, err => {
10
    if (err) {
11
        err; // $ExpectType KeychainError
12
    }
13
});

Another way, a bit more complicated, is to create your own utility types for testing. Imagine we’re creating a small framework that will help you test types:

1
type Expect<T extends true> = T
2
type Equal<X, Y> = X extends Y ? (Y extends X ? true : false) : false
3

4
type test = Expect<Equal<typeof 1, number>>
5

6
// @ts-expect-error
7
type test_error = Expect<Equal<typeof 1, string>>

Testing libraries#

Another way (much easier) is to use testing libraries, like vitest, which have type assertions. So we can do something like this:

1
import { assertType, expectTypeOf } from 'vitest'
2
import { suaLib } from 'lib'
3

4
test('Tipos certos', () => {
5
  expectTypeOf(suaLib).toBeFunction()
6
    expectTypeOf(suaLib).parameter(0).toMatchTypeOf<{ x: 1 }>()
7
})

But vitest isn’t the only one that does this. Another very interesting library that’s made specifically for this deserves its own section.

TSD#

TSD is a type testing library focused specifically on testing declaration files .d.ts (we talked about them in #TypeScriptWeek). The big idea of this package is that you can use it as if it were TypeScript’s native compiler, but with one advantage: your code won’t be executed at all.

It looks for files with the .test-d.ts extension. These files aren’t executed and certainly not compiled in the native way. What will happen is that TSD will look for assertions like expectError or expectType and analyze their results against the types you wrote in your original file.

Additionally, it will look in the same folder (or in a specified path) for the corresponding .d.ts file so it can test.

An example can be the very type file I wrote for Keychain:

1
// Type definitions for keychain 1.4
2
// Project: https://github.com/drudge/node-keychain
3
// Definitions by: Lucas Santos <https://github.com/khaosdoctor>
4
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
5

6
declare namespace keychainTypes {
7
    interface KeyChainBaseOptions {
8
        account: string;
9
        service: string;
10
        password: string;
11
        type?: 'generic' | 'internet';
12
    }
13

14
    type KeychainErrorCodes =
15
        | 'UnsupportedPlatform'
16
        | 'NoAccountProvided'
17
        | 'NoServiceProvided'
18
        | 'NoPasswordProvided'
19
        | 'ServiceFailure'
20
        | 'PasswordNotFound';
21

22
    type KeychainErrorType = `${KeychainErrorCodes}Error`;
23

24
    class KeychainError extends Error {
25
        code: KeychainErrorCodes;
26
        type: KeychainErrorType;
27
    }
28
}
29

30
declare function getPassword(
31
    options: Pick<keychainTypes.KeyChainBaseOptions, 'account' | 'service'>,
32
    callback: (err: keychainTypes.KeychainError, password: string) => void,
33
): void;
34

35
declare function setPassword(
36
    options: keychainTypes.KeyChainBaseOptions,
37
    callback: (err: keychainTypes.KeychainError) => void,
38
): void;
39

40
declare function deletePassword(
41
    options: Pick<keychainTypes.KeyChainBaseOptions, 'account' | 'service'>,
42
    callback: (err: keychainTypes.KeychainError) => void,
43
): void;
44

45
declare const keychain: typeof keychainTypes & {
46
    getPassword: typeof getPassword;
47
    setPassword: typeof setPassword;
48
    deletePassword: typeof deletePassword;
49
};
50

51
export = keychain;

We can put this file in a folder named index.d.ts, then we create a file index.test-d.ts with the following content:

1
import { expectType } from 'tsd'
2
import keychain from '.'
3

4
expectType<string>(keychain.getPassword({
5
  account: 'account',
6
  service: 'service',
7
}, (err, password) => { }))

If we run npx tsd at the root, we’ll get an error output, because we’re not expecting a string. If we change the code to:

1
import { expectType } from 'tsd'
2
import keychain from '.'
3

4
expectType<void>(keychain.getPassword({
5
  account: 'account',
6
  service: 'service',
7
}, (err, password) => { }))

We’ll get the direct output of our types.

Test types? But that’s what types are for#

One of the main questions and comments (even complaints) on the post was about whether or not we need to test types. I think what I heard most, both in this post and in my talks about this topic, is the following phrase:

Why would I test my types if my types already serve to test whether I’m sending everything right?

And that’s completely correct! We don’t always need to test our types. In fact, this kind of test isn’t very useful when we’re building commercial applications or even APIs.

The main use of type tests is when we have external libraries that will be used by other people, or when we’re manually adding a declaration file (the famous .d.ts files) to a function or library that doesn’t have native types.

An example of this is exactly the PR I opened on DefinitelyTyped, to type the Keychain library, which didn’t have native typing. In that PR we have this file. It’s exactly a type test because, for this kind of project (which is essentially a repository of external types), it makes total sense that we test our types.

The same goes, for example, if you’re developing a library that will be used by other people and you want to ensure that your changes will continue to maintain the use of the library the way you envisioned it, especially when you don’t have unit tests.

Type tests vs other tests#

Some people told me it would make sense to completely replace (in cases like this library one) unit tests and use only type tests, because they’re practically instant and can test the library’s usage.

I honestly don’t recommend it. Unit tests are more focused on testing the responses and direct usage of your application or library. Type tests don’t focus on the result, but rather on the usage, so you need to test that incorrect usages are also showing errors, as I do here:

1
// @ts-expect-error
2
// Another error when missing options
3
keychain.setPassword({ account: 'some-account', password: 'some-pass' }, err => {
4
    if (err) {
5
        err; // $ExpectType KeychainError
6
    }
7
});

Conclusion, is it worth it?#

You’re probably expecting a conclusion, so here goes the famous word that any senior will say: it depends.

Type tests are another kind of test, meaning other files, other logic, another way of thinking that need to be written by you (or by ChatGPT). In other words, it takes time.

However, having type tests adds an extra layer of protection. They will ensure in a quite lightweight way that your types are correct and that they work as expected, both for you and for everyone else who uses them.

So, like anything else, we have a trade-off: more development time for greater security in the application.

I personally don’t think it’s worth writing type tests for any application by default. Mainly because it will take more time and dedication. I believe type tests will show themselves to be necessary when you have a problem with untested types. Remember: don’t optimize prematurely.

What is type-testing with TypeScript? Is it an anti-pattern? Is it worth it?