Ensuring Typescript Code Quality With expect-type

Hi, my name's Misha Koletsky. I'm a software engineer and I'm the author of Expect Type, a library for type-level testing in TypeScript. So, what is it? It is a library available through npm that allows you to write tests for your types. So, if you're familiar with writing tests for runtime behavior, this is much the same thing, and it will be very familiar syntax to anyone who's familiar with the Expect functionality of Jest or VTest, but this lets you write tests for the actual types of your TypeScript code instead of the runtime behavior or the actual values.

This is useful for making sure that your types are what you think they are, but it also makes sure that they stay what you want them to be as time goes on. So, it can help protect you against colleagues or your future selves from making a mistake to regress types, to add anys and that sort of thing as your code base evolves. This also is a really good way to improve your own TypeScript skills. So, if you want to learn more about TypeScript and evaluate how TypeScript interacts with your code base, this is a really good way of doing it and kind of documenting how TypeScript works on your team.

All of this comes with no build step. So, there's no extra CLI that you need to run. There's no IDE VS code extension that you need to install or anything like that. Everything will just show up in whatever IDE you use, and the errors, if there are any, will show up when you run TSC, the TypeScript CLI, which hopefully you're already doing if you're using TypeScript. There are no dependencies, so there's no bloat that it adds to your node modules. If you look at the GitHub after this talk, you'll see it's just a handful of TypeScript files. There are some gnarly generics in its implementation, but none of that should be anything that you need to worry about as a user of expect type. There's no multi-megabyte patch version of TypeScript that ships with it. It's just pretty simple types. And there's also no runtime overhead. So, we have seen some teams using expect type in their production code, in fact. It doesn't have to be run as part of a test suite.

So, if you have very, very complex, generic, inferred types that it's very hard to access from other modules, including test code, you can actually just put expect type assertions right in your production code, and there's no performance concern because all of the functions that come with the library are no upset runtime. So, you don't need any special compiler tricks in order to avoid performance overhead. And like mentioned, there are no dependencies either.

This is what basic usage looks like. The main export is this expect type of function that you will pass a value to, and then you'll basically make assertions on that value. So here, we're saying that we expect 42 to be a number. We expect hello to be a string, which is obviously something that you would expect. In real life, you wouldn't test literal values, but you would import something, say, from your production code, and make sure that a certain value is a number or is a string. It can also do complex types. So, here's a barely more complex example of a coffee order.

We probably want to go further than just saying the coffee order is an object. We want to make sure that it's an object of a certain type. So here, we write an assertion that says that the coffee order has two properties, one which is called type, which is a string, and one which is called quantity, which is a type number.

There are lots more features. So, pretty much every feature you can think of in TypeScript, anything that has native functionality, you can test with expect type. So, a pretty commonly used one that there's an example of here is that we have two values, both of which have legs, but have other properties that maybe aren't relevant to this test. So, you can write, we've written two assertions here of the same form. One, we've made sure that horse has type of legs number, and so does a table. But obviously, we don't need to worry about those extra properties like a table usually doesn't have a name and a horse usually doesn't have a material. So, this is similar to just to match object helper, if you're familiar with that. More advanced features of TypeScript are supported as well.

So, here we've got a type guard function where we're making sure that the input to a function is of type date. So, you can check that the function returns a Boolean, but you can also check that it guards inputs of type date. There are lots of examples like this. There's a similar asserts helper. It's really worth exploring the documentation to find them all. And generic type testing as well. So, you don't have to pass a value into the expect type of function, you can just pass a generic type that doesn't actually exist at runtime at all. So, here we've got a magic box which has contents and its locked property. And here we're passing it as a generic type into the expect type of function and we're making sure that the contents property has type number.

And here we're passing it as a generic type into the expect type of function and we're making sure that the contents property has type number.

There are tons more, like I said, it's worth reading the documentation. There are easy to understand examples for pretty much everything you might want to do in TypeScript.

I want to talk briefly about integration with test frameworks as well. It only relies on TypeScript, so you can use it with Jest or Mocha or Playwright or any test framework you like. But there is a built-in support for expect type of in VTest, which you get some niceties from. It's, you use it in the exact same way, but VTest will keep track of when you've called expect type of and map it to the test that is calling that function so that you can see errors associated with test names, which can be useful once your test suite gets large and more complicated.

So this is something worth using. If you're using VTest, you can export the expect type of function directly from VTest. You don't actually need to install the expect type library if you're using VTest.

Some best practices that I've picked up from years of both building and using expect type of, don't use it all the time. Only test things that it's actually helpful to test. And a good rule of thumb for this is that libraries should usually have type tests to make sure that the consumers of those libraries can use them in the correct way. But applications probably shouldn't. If you're writing a type level test to say, my React component returns a React node, that's probably not the most useful thing to do. It's not 100% rule, but basically, it's probably not worth the time to test most application code.

But obviously, applications can have utility functions that have properties in common with libraries too. So don't. So take this with a pinch of salt. Look for edge cases. So the toEqual type of helper that you saw earlier can catch any never nullable properties, read-only properties. So that's something that's really important to check for in your type tests. So that's where it comes in useful. And then make sure that you're actually running it as part of your CI pipelines. So all you need to do is run TSC, which you should be doing anyway for your code base. And then any expect type assertions will show up as errors in your CI pipelines as well. You'll hopefully see them before it makes it to CI if you're using an IDE that supports TypeScript.

Another tip is to make generics specific. This is sometimes how I phrase it. But you can see an example here. So rather than testing a generic type directly, you'd want to use an example of the generic type. So let's say you're the author of a library called Zod, which is a way of doing runtime validations with strong TypeScript support. Rather than trying to test the z.object helper, here in this example we're creating a person schema. And then we're making sure that it returns the type that you'd expect from that schema. That tends to be a much better way to use expect type than to try and actually test a kind of a raw generic function.

I'll show a quick demo just so that you can see what the errors look like because a lot of this code is, you can see what the assertions look like, but you actually want to see what it looks like when something goes wrong. So let's split this in two. So here we've got an assertion saying that this add function has parameters of type number number, which looks like an appropriate test, but it's failing. And if we look at this error message, we can see why. It's a little squished on my screen, so let's close that.

Number number doesn't satisfy the constraint zero number one. And then there's a little bit of an art to reading the error message, but basically it's that bottom line that's the important part. Type number is not assignable to expected number, it's the actual string. So that tells us something's gone wrong in the code that we wrote. Oh yeah, in our add function, we accidentally said that we'd be adding together a number and a string. This should be number.

And then we should see that the error goes away once stack splits update. The second assertion, you can see that it's saying returns to be Boolean. This is just to show you another example of an error message and how you need to read them. And this is basically saying expect type of Boolean has of number has no call signatures. So you can see that's because we should obviously be returning a number instead, and then the error goes away.

That's just a very quick example of how to read the error messages. There's tons more that's coming from expect type. If you're interested in some more advanced options of how you can test your types, then you can come and take a look at some of these proposals. I've got all the links here. So it's where you'd expect to find it on NPM, on GitHub. There's documentation for it on the Vitest website, and I'm also available on X under mmcalc. Thanks very much. Bye-bye.