Testing Type-Safe Code: Validating TypeScript Expectations

Previously in this course, we performed a final refactoring of the task client to ensure our API layer was clean and DRY. While we’ve built a robust system, we’ve relied on our own eyes to verify that our complex generics and utility types work as intended. Today, we add a final layer of safety: Testing Type-Safe Code.

We aren't talking about runtime unit tests that check if a function returns 5. We are talking about "type tests"—checks that run during compilation to ensure that our types are correctly enforced and that our complex generic transformations don't break as the project evolves.

Why Test Types?

When you build complex utility types or generic API wrappers, it’s easy to accidentally broaden a type (e.g., changing a specific TaskStatus to string) without the compiler complaining. Type tests provide a safety net, ensuring that your abstractions hold up over time. Just as you need refactoring with confidence when changing logic, you need type testing when changing your data schemas.

Using expect-type for Validation

To test types, we use the expect-type library. It allows us to write assertions that check if a variable matches a specific type. If the type doesn't match, the build fails.

First, install the dependency in your project: npm install --save-dev expect-type

A Concrete Example: Testing Our API Response

In our ongoing Task API client, we have a generic ApiResponse<T> wrapper. Let’s create a test file named api.types.test.ts to verify that our wrapper correctly maps data.

TYPESCRIPT
import { expectTypeOf } from CE9178">'expect-type';
import { ApiResponse } from CE9178">'./api-client'; // The type we want to test

interface Task {
  id: string;
  title: string;
}

// 1. Test that the wrapper correctly assigns the generic
type TaskResponse = ApiResponse<Task>;

// 2. Write the type assertion
const response: TaskResponse = { data: { id: CE9178">'1', title: CE9178">'Test' }, status: 200 };

expectTypeOf(response.data).toMatchTypeOf<Task>();
expectTypeOf(response.status).toBeNumber();

If you were to change ApiResponse<T> to return any instead of T, expectTypeOf(response.data).toMatchTypeOf<Task>() would immediately fail during your CI build. This is the ultimate form of Quality and Validation for your type system.

Hands-on Exercise

Locate your Task interface defined in our project. Create a test file task.types.test.ts.

1. Create a variable that represents a partial task update (using the Partial utility we learned earlier).
2. Use expectTypeOf to assert that the properties in your partial object are indeed optional.
3. Attempt to assert that an object with a missing required field matches the full Task interface—watch the test fail.

Common Pitfalls

• Testing for any: Avoid using expectTypeOf(...).toBeAny(). Your goal is to enforce specificity, not verify that you've successfully bypassed the type system.
• Over-testing: You don't need to test every single inferred variable. Focus your type tests on your core domain models, generic wrappers, and complex utility types where a regression would have a high impact.
• Confusing Runtime and Compile-time: Remember that expectTypeOf does not exist at runtime. If you need to validate data coming from an API at runtime, you should look into schema validation libraries like Zod, as type tests only protect you while the code is being written and compiled.

FAQ

Does this slow down my build? Minimal. Since these are compile-time checks, they are processed alongside your standard TypeScript compilation.

Can I use these with Jest? Yes. You can place these tests inside your standard .test.ts files alongside your runtime unit tests.

What happens if I forget to run these? Since these are type-level assertions, they are checked every time you run tsc. If they fail, your build fails.

Recap

We’ve moved from basic annotations to advanced generic patterns, and now to Testing our types. By using expect-type, you treat your type definitions with the same rigor as your business logic, ensuring that your API client stays strictly typed even as your application grows.

Up next: We will explore how to manage environment variables with types, ensuring our configuration settings are as safe as our API responses.