Détail du package

tstyche

tstyche16.7kMIT3.5.0

The Essential Type Testing Tool.

typescript, types, test, runner

readme

TSTyche

version license install-size coverage

The Essential Type Testing Tool.

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 firstItem<T>(target: Array<T>): T | undefined {
  return target[0];
}

test("firstItem", () => {
  expect(firstItem(["a", "b", "c"])).type.toBe<string | undefined>();

  expect(firstItem()).type.toRaiseError("Expected 1 argument");
});

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 functional tests:

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

function secondItem<T>(target: Array<T>): T | undefined {
  return target[1];
}

test("handles numbers", () => {
  assert.strictEqual(secondItem([1, 2, 3]), 2);

  tstyche.expect(secondItem([1, 2, 3])).type.toBe<number | undefined>();
});

Here is the list of all matchers:

  • .toBe(), .toBeAssignableTo(), .toBeAssignableWith() compare types or types of expression,
  • .toAcceptProps() checks JSX component props type,
  • .toHaveProperty() looks up keys on an object type,
  • .toRaiseError() captures the type error message or code,
  • .toBeString(), .toBeNumber(), .toBeVoid() and 9 more shorthand checks for primitive types.

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 https://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

Releases

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 identicality 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

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.