Configuration File

The behavior of TSTyche can be customized through a configuration file.

Usage

To configure TSTyche add a tstyche.json file to the project.

By default, the configuration file is loaded from the current directory. When the --root command line option is set, the configuration file is searched for in that directory.

Use the --config command line option to point to a specific configuration file explicitly.

If no configuration file is discovered or provided, the built-in defaults are used.

Syntax

The configuration file must contain an object. Comments, unquoted keys, single quotes or trailing commas are allowed:

{
  // The list of glob patterns to match the test files
  testFileMatch: [
    '**/*.test.ts',
    '**/*.tst.ts',
  ],
}

Schema

In-editor validation can be enabled by adding the $schema key:

{
  "$schema": "https://tstyche.org/schemas/config.json"
}

The following pattern can be used to specify the version of TSTyche:

{
  "$schema": "https://tstyche.org/schemas/config-7.0.json"
}

The schema can also be referenced locally:

{
  "$schema": "./node_modules/tstyche/schemas/config.json"
}

Options

Options passed through the command line override the ones from the configuration file.

Relative paths are resolved relative to the configuration file.

checkDeclarationFiles

• Default: true
• Type: boolean

Check declaration files for type errors.

To maximize performance TSTyche only checks types of test and fixture files. When checkDeclarationFiles is enabled, type errors are also reported for declaration and ambient files. In other words, all .d.ts files of the projected are checked. The files within the node_modules directory are not checked.

It is recommended to enable this option when a project has handcrafted or generated type declarations.

checkSuppressedErrors

• Default: true
• Type: boolean

Check errors silenced by @ts-expect-error directives in the test files.

When this option is enabled, the runner reads the text after @ts-expect-error and checks if it matches the actual error message:

let config: { timeout?: number } = {};
 
// @ts-expect-error  Object literal may only specify known properties
config = { silent: true };

If a message does not match or is not specified, an error is reported.

Use ... to truncate long error messages:

// @ts-expect-error  Argument of type ... is not assignable to parameter of type 'never'.

To ignore a directive, append the ! character after it:

// @ts-expect-error!  This is wrong.

failFast

• Default: false
• Type: boolean

Stop running tests after the first failure.

fixtureFileMatch

• Default: ["**/__fixtures__/*.{ts,tsx}", "**/fixtures/*.{ts,tsx}"]
• Type: Array<string>

The list of glob patterns to match the fixture files. The patterns are matched with the portion of the path relative to the root directory. The matching is case insensitive.

To maximize performance TSTyche only checks types of test and fixture files.

quiet

• Default: false
• Type: boolean

Silence all test runner output except errors and warnings.

rejectAnyType

• Default: true
• Type: boolean

Reject the any type passed as an argument to the expect() function or a matcher.

For instance, the following test is passing even when the return type by mistake resolves to any:

import { query } from "query";
import { expect } from "tstyche";
 
expect(query({ payload: "sample" })).type.toBeAssignableTo<string>();
expect(query({ payload: 123 })).type.toBeAssignableTo<number>();

This issue can be solved by adding .not.toBeAny() check. rejectAnyType does the same, but without repetitive boilerplate code.

rejectNeverType

• Default: true
• Type: boolean

Reject the never type passed as an argument to the expect() function or a matcher.

For instance, the following test is passing even when the Result type by mistake resolves to never:

import { type Result, getResult } from "result";
import { expect } from "tstyche";
 
expect(getResult("sample")).type.toBe<Result<string>>();
expect(getResult(123)).type.toBe<Result<number>>();

This issue can be solved by adding .not.toBeNever() check. rejectNeverType does the same, but without repetitive boilerplate code.

reporters

• Default: ["list", "summary"]
• Type: Array<string>

The list of reporters to use.

The following can be specified:

• built-in reporter: "list" or "summary",
• name of a package: "tstyche-reporter",
• or a path: "./custom-reporter.js".

{
  "reporters": ["list", "tstyche-reporter", "./custom-reporter.js"]
}

To learn more, see the Reporters page.

target

• Default: "*"
• Type: string

The range of TypeScript versions to test against.

The following can be specified:

• "*", uses the locally installed TypeScript if available, otherwise falls back to the latest version of TypeScript,
• minor releases, like "5.6", resolves to the latest version in the series (for example, "5.6" resolves to version 5.6.3),
• patch releases, like "5.8.2",
• "beta", "latest", "next" or "rc" distribution tags  of the typescript package.

To specify multiple versions, provide a single string with versions separated by ||:

{
  "target": "5.6 || 5.8.2 || latest"
}

Ranges

Version ranges allow testing on a range of TypeScript versions. The range must be specified using an operator and a minor version.

Supported operators:

• >, greater than,
• >=, greater than or equal,
• <, less than,
• <=, less than or equal.

For example, the range >=5.5 gets expanded to: 5.5, 5.6, 5.7 and so on. In the future this list will include newly released versions as well.

To set an upper bound, the intersection of two ranges can be used: >=5.4 <5.6. Here only 5.4 and 5.5 are included.

Ranges and versions can be combined:

{
  "target": ">=5.4 <5.6 || 5.6.2 || >=5.7"
}

testFileMatch

• Default: ["**/*.tst.*", "**/__typetests__/*.test.*", "**/typetests/*.test.*"]
• Type: Array<string>

The list of glob patterns to match the test files. The patterns are matched with the portion of the path relative to the root directory. The matching is case insensitive.

Brace expansion of comma separated lists is supported. For example, ["**/tests/*.{ts,tsx}"] or ["**/tests/*.ts{,x}"] both expand to ["**/tests/*.ts", "**/tests/*.tsx"].

The following wildcards can be used:

• / matches a path separator,
• ? matches any single character excluding path separators,
• * matches zero or more characters excluding path separators,
• ** matches zero or more characters including path separators.

Usage examples:

• ? can be used to select files or directories that differ in their name by only a character: typetests/?at.tst.ts would match typetests/bat.tst.ts or typetests/cat.tst.ts, but not typetests/at.tst.ts,
• * can be used to select files within a directory: *.tst.ts would match Options.tst.ts, but not Options.test.ts or json/Options.tst.ts,
• ** can be used to select files within nested directories: packages/**/typetests/*.test.ts would match packages/typetests/api.test.ts, packages/core/typetests/awaitable.test.ts or packages/parsers/json/typetests/JsonObject.test.ts.

tsconfig

• Default: "findup"
• Type: string

The TSConfig to load. The following is possible:

• automatically discover the nearest tsconfig.json file (default),
• use default compiler options,
• load a specific tsconfig.json file,
• provide the TSConfig as an inline JSON string.

Discover

By default, TSTyche searches for the nearest tsconfig.json that includes the file in question.

{
  "tsconfig": "findup"
}

Example output:

uses TypeScript 5.9.3 with ./typetests/tsconfig.json

Use Defaults

Skip TSConfig lookup and use default compiler options.

{
  "tsconfig": "baseline"
}

Example output:

uses TypeScript 5.9.3 with baseline TSConfig

Custom TSConfig

Specify a custom tsconfig.json path.

{
  "tsconfig": "./tsconfig.test.json"
}

Example output:

uses TypeScript 5.9.3 with ./tsconfig.test.json

Inline JSON

Provide an inline TSConfig string. The implementation creates a synthetic TSConfig file in the root directory.

{
  "tsconfig": "{\"extends\":\"./tsconfig.json\",\"compilerOptions\":{\"lib\":[\"es2020\"]},\"include\":[\"**/*\"]}"
}

Example output:

uses TypeScript 5.9.3 with inline TSConfig

verbose

• Default: false
• Type: boolean

Enable detailed logging.