Package detail

tstyche

tstyche28.9kMIT4.0.2

Everything You Need for Type Testing.

typescript, types, test, runner

readme

TSTyche

Everything You Need for Type Testing.

TSTyche is a type testing tool for TypeScript. It ships with describe() and test() helpers, expect style assertions and a mighty test runner.

Helpers

If you are used to test JavaScript, a simple type test file should look familiar:

import { expect, test } from "tstyche";

function isSameLength<T extends { length: number }>(a: T, b: T) {
  return a.length === b.length;
}

test("isSameLength", () => {
  expect(isSameLength([1, 2], [1, 2, 3])).type.toBe<boolean>();
  expect(isSameLength("one", "two")).type.toBe<boolean>();

  expect(isSameLength).type.not.toBeCallableWith(1, 2);
});

To organize, debug and plan tests TSTyche has:

test(), it() and describe() helpers,
with .only, .skip and .todo run mode flags.

Assertions

The assertions can be used to write type tests (like in the above example) or mixed in your unit tests:

import assert from "node:assert";
import test from "node:test";
import * as tstyche from "tstyche";

function toMilliseconds(value: number) {
  if (typeof value === "number" && !Number.isNaN(value)) {
    return value * 1000;
  }

  throw new Error("Not a number");
}

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");
});

Here is the list of all matchers:

.toBe(), .toBeAssignableTo(), .toBeAssignableWith() compare types or types of expression,
.toAcceptProps() checks the type of JSX component props,
.toBeApplicable ensures that the decorator function can be applied,
.toBeCallableWith() checks whether a function is callable with the given arguments,
.toBeConstructableWith() checks whether a class is constructable with the given arguments,
.toHaveProperty() looks up keys on an object type,
.toRaiseError() captures the message or code of a type error.

Runner

The tstyche command is the heart of TSTyche. For example, it can select test files by path, filter tests by name and pass them through a range of TypeScript versions:

tstyche query-params --only multiple --target '>=5.0 <5.3'

This simple! (And it has watch mode too.)

Documentation

Visit tstyche.org to view the full documentation.

Feedback

If you have any questions or suggestions, start a discussion or open an issue on GitHub. Preferring a chat? Join our Discord server.

License

MIT © TSTyche

changelog

Changelog

4.0.2 - 2025-06-17

Fixed

Always erase the // @ts-expect-error directives in the ability layer (#513)

4.0.1 - 2025-06-14

Fixed

Do not report unmatched conditional tests or assertions (#500)

4.0.0 - 2025-06-02

If you are upgrading from previous version, please be sure to read the release notes page.

Added

New! Add the // @tstyche if directive, which makes it possible to skip tests or assertions conditionally (#490, #493)
New! Add template test file support (#468, #469, #470)
New! Add the when() utility and the .isCalledWith() action (#460, #466, #480)
New! Add the .toBeConstructableWith() matcher (#451, #456, #457, #479, #483)
New! Add the .toBeCallableWith() matcher (#447, #448, #449, #453, #456, #457, #479, #483)
New! Add the .toBeApplicable matcher (#100)
Add collect:* events (#411)

Fixed

Handle unexpected trailing tokens in JSON (#496)
Allow skipping target type errors (#495)
Allow adding notes to the directive comments (#492)
Do not typecheck already seen test files (#475)
Always use default compiler options when file is not included (#473)
Do not reverse diagnostics of the ability layer (#446)

Changed

Breaking! Move test tree validation logic to the Collect class (#471)
Breaking! Remove config details from summary and Result (#459)
Breaking! Always take compiler as the first constructor argument (#445)
Breaking! Remove primitive type matchers (#442)
Breaking! Exclude whitespace when comparing diagnostic messages (#427)
Breaking! Add the minorVersions property to store manifest (#425)
Breaking! Make default compiler options strict (#424)
Breaking! Drop support for TypeScript <=4.6 (#423, #476)
Breaking! Enable the rejectAnyType and rejectNeverType options by default (#422)
Breaking! Enable the checkSourceFiles option by default (#421)
Breaking! Require passing resolvedConfig to ExpectService constructor (#420)
Breaking! Rename AssertionNode and TestTreeNode classes (#419)
Breaking! Drop support for Node.js 18 (#418)
Breaking! Rename the --fetch command line option (#417)
Breaking! Remove the .toMatch() matcher (#416)
Breaking! Remove Store.getSupportedTags() method (#415)
Breaking! Remove Version.isVersionTag() method (#414)

4.0.0-rc.1 - 2025-05-25

Added

If you are upgrading from previous version, please be sure to read the release notes page.

Added

New! Add the // @tstyche if directive, which makes it possible to skip tests or assertions conditionally (#490, #493)

Fixed

Allow adding notes to the directive comments (#492)

4.0.0-rc.0 - 2025-05-15

Release candidate based on 4.0.0-beta.10.

4.0.0-beta.10 - 2025-05-14

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

Prepend semicolon only before expression statements in the ability layer (#483)

4.0.0-beta.9 - 2025-05-08

If you are upgrading from previous version, please be sure to read the release notes page.

Added

Bring back support for TypeScript >=4.7 (#476)
Add validation for when() target (#480)

Fixed

Handle trailing commas in the ability layer text (#479)

Changed

Breaking! Move test tree validation logic to the Collect class (#471)

4.0.0-beta.8 - 2025-05-05

If you are upgrading from previous version, please be sure to read the release notes page.

Added

Add validation for template test files (#470)

Fixed

Do not typecheck already seen test files (#475)
Always use default compiler options when file is not included (#473)
Normalize template test file specifier (#469)

4.0.0-beta.7 - 2025-05-04

If you are upgrading from previous version, please be sure to read the release notes page.

Added

New! Add template test file support (#468)
New! Add the when() utility and the .isCalledWith() action (#460, #466)

Changed

Breaking! Remove config details from summary and Result (#459)

4.0.0-beta.6 - 2025-04-15

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

Allow passing property access expressions to the .toBeCallableWith() and .toBeConstructableWith() matchers (#457)

4.0.0-beta.5 - 2025-04-15

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

Insert missing semicolons in the ability layer text (#456)

4.0.0-beta.4 - 2025-04-14

If you are upgrading from previous version, please be sure to read the release notes page.

Added

New! Add the .toBeConstructableWith() matcher (#451)

Fixed

Improve validation of the source node passed to .toBeCallableWith() (#449, #453)

4.0.0-beta.3 - 2025-04-11

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

Relax validation of the target of .toBeCallableWith() matcher (#448)

4.0.0-beta.2 - 2025-04-11

If you are upgrading from previous version, please be sure to read the release notes page.

Added

New! Add the .toBeCallableWith() matcher (#447)

Fixed

Do not reverse diagnostics of the ability layer (#446)

Changed

Always take compiler as the first constructor argument (#445)

4.0.0-beta.1 - 2025-04-06

If you are upgrading from previous version, please be sure to read the release notes page.

Added

New! Add the .toBeApplicable matcher (#100)

4.0.0-beta.0 - 2025-03-30

If you are upgrading from previous version, please be sure to read the release notes page.

Added

Add collect:* events (#411)

Changed

Breaking! Remove primitive type matchers (#442)
Breaking! Exclude whitespace when comparing diagnostic messages (#427)
Breaking! Add the minorVersions property to store manifest (#425)
Breaking! Make default compiler options strict (#424)
Breaking! Drop support for TypeScript 4.x (#423)
Breaking! Enable the rejectAnyType and rejectNeverType options by default (#422)
Breaking! Enable the checkSourceFiles option by default (#421)
Breaking! Require passing resolvedConfig to ExpectService constructor (#420)
Breaking! Rename AssertionNode and TestTreeNode classes (#419)
Breaking! Drop support for Node.js 18 (#418)
Breaking! Rename the --fetch command line option (#417)
Breaking! Remove the .toMatch() matcher (#416)
Breaking! Remove Store.getSupportedTags() method (#415)
Breaking! Remove Version.isVersionTag() method (#414)

3.5.0 - 2025-01-14

Added

Make code frame output configurable (#407, #408)

3.4.0 - 2025-01-11

Fixed

Simplify complex unions and intersections for .toBe() checks (#394)

Changed

Respect non-interactive environments in watch mode (#405)

3.3.1 - 2024-12-31

Fixed

Treat intersections or unions of identical types as identical to its constituent type (target types) (#393)

3.3.0 - 2024-12-30

Fixed

Print error codes at the end of the first line of diagnostics (#391)

Changed

Treat intersections or unions of identical types as identical to its constituent type (source types) (#392)

3.2.0 - 2024-12-23

Fixed

Emit the project:uses event only once per project (#386)

Added

New! Add the checkSourceFiles option (#388, #390)
Expose the SelectHookContext type (#387)

3.1.1 - 2024-12-05

Fixed

Allow specifying unsupported versions in target ranges (#383)

3.1.0 - 2024-12-03

Changed

Deprecate the Version.isVersionTag() method (#379)
Deprecate the Store.getSupportedTags() method (#377)

Added

New! Support testing against TypeScript version ranges (#377)
New! Add the rejectAnyType and rejectNeverType configuration options (#370, #373)
Add the --list command line option (#364, #366)

3.0.0 - 2024-11-05

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

Take into account exactOptionalPropertyTypes option when comparing types (#357)
Always resolve test file paths (#346)
Mark not existing test file as failed (#341)
Fix relative path normalization logic (#317)
When requested, always suppress fetch errors (#275)

Changed

Breaking! Rename the TSTYCHE_TYPESCRIPT_MODULE environment variable (#356)
Breaking! Use import.meta.resolve() (#355)
Breaking! Rename TargetResult.target property (#339)
Breaking! Rename the Options class (#334)
Breaking! Make the Config class not instantiable (#332)
Breaking! Make the Select class not instantiable (#331)
Breaking! Remove the TSTyche class (#330)
Breaking! Make the Store class not instantiable (#329)
Breaking! Make the OutputService class not instantiable (#328)
Breaking! Rename the ListReporter class (#326)
Breaking! Rename the EventHandler.on() method (#323)
Breaking! Deprecate the .toMatch() matcher (#315)
Breaking! Remove ConfigService constructor arguments (#297)
Breaking! Rename Task, TaskResult, Runner classes and task:* events (#296)
Breaking! Remove InputService constructor options (#294)
Breaking! Remove OutputService constructor options (#293)
Breaking! Rename the project:uses event (#290)
Breaking! Rename the store:adds event (#289)
Breaking! Remove the deprecated .toBeAssignable() and .toEqual() matchers (#286)
Breaking! Drop support for Node.js 16 (#285)
Breaking! Directly fetch and extract tarballs of typescript packages (#269, #291)

Added

Add index signature checks for the .toHaveProperty() matcher (#362)
Allow .toRaiseError() to take regular expressions (#358)
New! Add the tsconfig configuration option (#343)
New! Add support for custom reporters (#327)
New! Add support for plugins (#322, #324, #337, #349, #350, #352)
New! Add omit() and pick() utilities (#314)
Add the JsonScanner class (#310)
Add prune() method to StoreService class (#298)
Add the LockService class (#281)
Add the Fetcher class (#274)
New! Add the TSTYCHE_NPM_REGISTRY environment variable (#266, #282)

3.0.0-rc.2 - 2024-11-02

If you are upgrading from previous version, please be sure to read the release notes page.

Added

Add index signature checks for the .toHaveProperty() matcher (#362)

3.0.0-rc.1 - 2024-10-31

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

Take into account exactOptionalPropertyTypes option when comparing types (#357)

Added

Allow .toRaiseError() to take regular expressions (#358)

3.0.0-rc.0 - 2024-10-30

If you are upgrading from previous version, please be sure to read the release notes page.

Changed

Breaking! Rename the TSTYCHE_TYPESCRIPT_MODULE environment variable (#356)
Breaking! Use import.meta.resolve() (#355)

3.0.0-beta.6 - 2024-10-27

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

Always resolve test file paths (#346)

Changed

Require plugins to have name property (#349, #352)

Added

Pass context to the select hook (#350)

3.0.0-beta.5 - 2024-10-23

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

Mark not existing test file as failed (#341)

Changed

Rename TargetResult.target property (#339)

Added

New! Add the tsconfig configuration option (#343)

3.0.0-beta.4 - 2024-10-17

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

Remove environment options to ResolvedConfig (reverts #299) (#336)

Changed

Breaking! Rename the Options class (#334)
Breaking! Make the Config class not instantiable (#332)
Breaking! Make the Select class not instantiable (#331)
Breaking! Remove the TSTyche class (#330)
Breaking! Make the Store class not instantiable (#329)
Breaking! Make the OutputService class not instantiable (#328)
Breaking! Rename the ListReporter class (#326)
Breaking! Rename the EventHandler.on() method (#323)

Added

New! Add support for custom reporters (#327)
New! Add support for plugins (#322, #324, #337)

3.0.0-beta.3 - 2024-10-07

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

Fix relative path normalization logic (#317)

Changed

Breaking! Deprecate the .toMatch() matcher (#315)

Added

New! Add omit() and pick() utilities (#314)

3.0.0-beta.2 - 2024-10-05

If you are upgrading from previous version, please be sure to read the release notes page.

Added

Add the JsonScanner class (#310)

3.0.0-beta.1 - 2024-08-25

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

Write typescript packages atomically (#291)

Changed

Breaking! Remove ConfigService constructor arguments (#297)
Breaking! Rename Task, TaskResult, Runner classes and task:* events (#296)
Breaking! Remove InputService constructor options (#294)
Breaking! Remove OutputService constructor options (#293)
Breaking! Rename the project:uses event (#290)
Breaking! Rename the store:adds event (#289)

Added

Add environment options to ResolvedConfig (#299)
Add prune() method to StoreService class (#298)

3.0.0-beta.0 - 2024-08-12

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

When requested, always suppress fetch errors (#275)

Changed

Breaking! Remove the deprecated .toBeAssignable() and .toEqual() matchers (#286)
Breaking! Drop support for Node.js 16 (#285)
Breaking! Directly fetch and extract tarballs of typescript packages (#269)

Added

Add the LockService class (#281)
Add the Fetcher class (#274)
New! Add the TSTYCHE_NPM_REGISTRY environment variable (#266, #282)

2.1.1 - 2024-07-27

Fixed

Mark warning locations in yellow (#262)
Support .toAcceptProps() on TypeScript 4.5 and below (#261)

2.1.0 - 2024-07-15

Fixed

Allow empty config file (#239)
Handle not supported matchers (#227)

Changed

Show related diagnostics, when provided by TypeScript (#242)
Mark the entire locations in diagnostic messages (#238, #247, #251, #253, #255)
In watch mode, return the list of test files as an async iterable (#233, #232)

Added

New! Add the .toAcceptProps() matcher (#237)

2.0.0 - 2024-06-10

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

Always allow passing cancellationToken as an argument (#206)
Breaking! Always set the configFilePath property in the resolved config (#203)
Breaking! Do not return the Result from test runner (#188)
Collect and handle nested expect() assertions (#156)

Changed

Breaking! Use fetch() global (#214)
Breaking! Use the jsx-runtime transform for output components (#199, #219)
Breaking! Drop support for Node.js 14 (#198)
Breaking! Deprecate .toEqual() in favour of .toBe() (#151)
Breaking! Deprecate .toBeAssignable() in favour of .toBeAssignableWith() (#142)

Added

Add the DiagnosticOrigin class (#216)
Add the TestFile class (#189)
New! Add the watch mode (#170, #173, #204, #208, #213, #218)
Add the SelectService class (#165)
New! Add .toBe() matcher (#151)
New! Add .toBeAssignableTo() and .toBeAssignableWith() matchers (#141)

2.0.0-rc.2 - 2024-06-08

If you are upgrading from previous version, please be sure to read the release notes page.

Added

Exit the watch mode when q is pressed (#218)

2.0.0-rc.1 - 2024-06-04

If you are upgrading from previous version, please be sure to read the release notes page.

Fixed

Show deprecation warnings for each test file (#217)

2.0.0-rc.0 - 2024-06-03

If you are upgrading from previous version, please be sure to read the release notes page.

Changed

Add the DiagnosticOrigin class (#216)
Breaking! Use fetch() global (#214)

Fixed

Allow ./ in the beginning of the testFileMatch patterns (#215)

2.0.0-beta.1 - 2024-05-27

If you are upgrading from previous version, please be sure to read the release notes page.

Changed

Breaking! Always set the configFilePath property in the resolved config (#203)
Breaking! Use the jsx-runtime transform for output components (#199)
Breaking! Drop support for Node.js 14 (#198)
Breaking! Do not return the Result from test runner (#188)

Fixed

Always allow passing cancellationToken as an argument (#206)
Support the failFast option in the watch mode (#204)
Make sure recursive watch is available (#200)

Added

New! Watch the TSTyche config file for changes (#208, #213)
Add the TestFile class (#189)

2.0.0-beta.0 - 2024-03-28

If you are upgrading from previous version, please be sure to read the release notes page.

Changed

Breaking! Allow selecting test files with any extensions (#153)
Breaking! Deprecate .toEqual() in favour of .toBe() (#151)
Breaking! Deprecate .toBeAssignable() in favour of .toBeAssignableWith() (#142)

Added

Do not allow --watch in CI environments (#173)
New! Add the watch mode (#170)
Add the SelectService class (#165)
Collect and handle nested expect() assertions (#156)
New! Add .toBe() matcher (#151)
New! Add .toBeAssignableTo() and .toBeAssignableWith() matchers (#141)

1.1.0 - 2024-02-27

Added

New! Support for Node.js 14 (#136)
Add the CancellationToken class (#135)

Fixed

Improve behavior of timeout errors (#133, #134)

1.0.0 - 2024-02-20

Stable release based on 1.0.0-rc.2.

1.0.0-rc.2 - 2024-02-14

Fixed

Use the isTypeRelatedTo() method directly, to make strict subtype checks possible (#127, #126)

1.0.0-rc.1 - 2024-02-10

Changed

Breaking! Remove the disableTestFileLookup option in favor of testFileMatch: [] (#121)

Added

New! Set module: "preserve" in the default compiler options for inferred project that are using TypeScript 5.4 and up (#111)

Fixed

Do not select test files, if testFileMatch is an empty list (#120)

1.0.0-rc - 2024-01-28

Changed

Breaking! Replace the allowNoTestFiles option with disableTestFileLookup (#104)

Added

New! Set default compiler options for inferred (e.g. JavaScript) projects (#93)
Add the TSTYCHE_NO_INTERACTIVE environment variable (#88)
Add the TSTYCHE_TYPESCRIPT_PATH environment variable (#84)

Fixed

Only select TypeScript and JavaScript files for test run (#105)

1.0.0-beta.9 - 2024-01-05

Fixed

Fix "target": ["current"] support for TypeScript 5.2 and below (#83)

1.0.0-beta.8 - 2024-01-05

Changed

Breaking! Make "target": ["current"] the default instead of "target": ["latest"] (#81, #80, #66)
New! Load the installed TypeScript package for type testing instead of installing another copy to the store (#71, #64)

Added

Add the Path class (#59)

Fixed

Correctly handle command line options that do not take a value (#58)

1.0.0-beta.7 - 2023-12-29

Changed

Breaking! Add new Expect class to validate provided values and orchestrate matchers logic (#39)

Added

New! Load local language service plugins to support files like .svelte or .vue (#56)

Fixed

Make the source argument checks stricter for the .toHaveProperty() matcher (#46)

1.0.0-beta.6 - 2023-12-03

Added

New! Add .toHaveProperty() matcher (#36)

Fixed

Accept template literals as arguments of the .toRaiseError() matcher (#38)

1.0.0-beta.5 - 2023-11-27

Changed

Breaking! Move retry logic to the Lock class (#31)
Bring back support for Node.js 16 (#28, #27)

Added

New! Add support for the current target tag (#33)

Fixed

Allow .raiseError() to take template literals as arguments (#35)

1.0.0-beta.4 - 2023-11-24

Added

Use Node.js Fetch API (#23)

Removed

Breaking! Remove the context() helper (#24)
Breaking! Drop support for Node.js 16 (#22)
Breaking! Rename methods of the StoreService class (5d74201)

Fixed

Tune up behavior of .skip and .only run mode flags (#25)
Clean up error messages of primitive type matchers (#21)
Normalize installationPath path output (#19)

1.0.0-beta.3 - 2023-11-13

Fixed

Support 'node10' and 'node16' resolutions (7dd805a, 9c83e79)

1.0.0-beta.2 - 2023-11-12

Fixed

Support 'node10' resolution (#7)

1.0.0-beta.1 - 2023-11-09

Fixed

Include 'cjs' files in the published package (90b6473)

1.0.0-beta.0 - 2023-11-09

First pre-release.