Walkthrough

A tour of the features that set TSTyche apart.

Test Against Specific TypeScript Versions

TSTyche has everything needed to test against specific TypeScript versions:

tstyche --target 5.4

The above command runs tests using TypeScript 5.4.5. You can specify a range of versions as well:

tstyche --target '>=5.6'

To learn more, see the TypeScript Versions page.

Expect Errors

Testing invalid code with @ts-expect-error is a popular approach, but it casts too wide a net. Any error on the following line will make the test pass, even the wrong one. TSTyche ships with ability matchers like .not.toBeCallableWith() that communicate the intent of a test. For cases where the error message itself matters, TSTyche also reads the message after @ts-expect-error and verifies it matches the actual error.

To learn more, see the Expect Errors page.

Reject Unexpected any and never

When a type unexpectedly resolves to any or never, tests may still pass, silently masking the issue. TSTyche rejects these types automatically, without repetitive .not.toBe<any>() or .not.toBe<never>() checks.

To learn more, see the rejectAnyType and rejectNeverType options.

Generate Tests

When testing a type against many inputs, writing out each test by hand is repetitive. TSTyche can generate tests from a template file. Place the // @tstyche template directive at the top and export the test text as default:

// @tstyche template
 
let testText = `import { expect, test } from "tstyche";
`;
 
for (const source of ["string", "number"]) {
  testText += `test("is ${source} a string?", () => {
  expect<${source}>().type.toBe<string>();
});
`;
}
 
export default testText;

To learn more, see the Template Test Files page.

Run Programmatically

To run TSTyche from within a script or a runtime test, the tstyche/tag entry point provides a tagged template function with a zx inspired API.

import test from "node:test";
import tstyche from "tstyche/tag";
 
test("generate types", async () => {
  const fixtureUrl = getFixtureUrl(import.meta);
 
  // ...
 
  await tstyche`--quiet --root ${fixtureUrl}`;
});

To learn more, see the Programmatic Usage page.

Integrate into Unit Tests

When a test requires complex setup, duplicating it in a separate type test file adds unnecessary overhead. TSTyche assertions can be mixed directly into existing unit tests:

export function toMilliseconds(value: number) {
  if (typeof value === "number" && !Number.isNaN(value)) {
    return value * 1000;
  }
 
  throw new Error("Not a number");
}

import assert from "node:assert";
import test from "node:test";
import * as tstyche from "tstyche";
import { toMilliseconds } from "../toMilliseconds.js";
 
test("toMilliseconds", () => {
  const sample = toMilliseconds(10);
 
  assert.equal(sample, 10_000);
  tstyche.expect(sample).type.toBe<number>();
 
  // Will pass as a type test and not throw at runtime
  tstyche.expect(toMilliseconds).type.not.toBeCallableWith("20");
});

Use the testFileMatch configuration option to include files in the test run:

{
  "testFileMatch": ["**/*.test.ts", "**/*.tst.ts"]
}