Configuration File

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

Usage

To configure TSTyche add tstyche.config.json file to the root of the project. Or point to your configuration file using the --config command line option. The defaults are used, if a configuration file is not provided.

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 below pattern can be used to specify the version of TSTyche:

{
  "$schema": "https://tstyche.org/schemas/config-4.1.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:

// @ts-expect-error Cannot find name 'add'.
console.log(add);

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 rootPath directory. The matching is case insensitive.

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

plugins

• Default: []
• Type: Array<string>

The list of plugins to use.

The following can be specified:

• name of a package: "tstyche-plugin",
• or a path: "./custom-plugin.js".

{
  "plugins": ["tstyche-plugin", "./custom-plugin.js"]
}

To learn more, see the Plugins page.

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.

rootPath

• Default: the path to the directory from which the configuration file was loaded or the current directory
• Type: string

The path to a directory containing files of a test project.

To collect the test files, the file tree is walked starting from the rootPath directory. Later during the test run, the lookup of tsconfig.json for each test file starts at the directory containing the file and ends at the rootPath.

This means that all test files to be run and TSConfig files to load the compiler configuration from must be within the rootPath.

For instance, if you prefer to keep the TSTyche configuration file in a ./config directory:

• config
  • tstyche.json
• src
• package.json
• tsconfig.json

The rootPath should point to the root of the project:

{
  "rootPath": "../"
}

target

• Default: "*"
• Type: string

The range of TypeScript versions to be tested 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.0 <5.3. Here only 5.0, 5.1 and 5.2 are be included.

Ranges and versions can be combined:

{
  "target": ">=5.0 <5.3 || 5.4.2 || >5.5"
}

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 rootPath 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 look up strategy to be used to find the TSConfig file.

The following can be specified:

• "findup", find the nearest tsconfig.json that includes a particular test file,
• "ignore", do not look for any tsconfig.json and use default compiler options,
• or, if a path is specified, simply load tsconfig.json from that path.

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