Configuration File

TSTyche can be configured 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, TSTyche searches for the configuration file in that directory.

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

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

Syntax

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

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

Schema

To enable in-editor validation, add the $schema key:

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

To pin it to a specific TSTyche version, add a version number:

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

To reference locally, point to node_modules:

{
  "$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.

When checkDeclarationFiles is enabled, all the .d.ts files in the project (not including files from the node_modules directories) are checked for type errors.

checkSuppressedErrors

• Default: true
• Type: boolean

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

To learn more, see the Expect Errors page.

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.

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 passes even when the return type accidentally 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>();

Adding .not.toBe<any>() solves this, but rejectAnyType does the same without the boilerplate.

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 passes even when the Result type accidentally 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>>();

Adding .not.toBe<never>() solves this, but rejectNeverType does the same without the boilerplate.

reporters

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

The list of reporters to use.

The following can be specified:

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

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

To learn more, see the Reporters page.

target

• Default: "*"
• Type: string

The TypeScript version or range of versions to test against.

The following can be specified:

• "*", uses the locally installed TypeScript if available, otherwise falls back to the latest version
• a minor release, like "5.6", resolves to the latest version in the series (for example, "5.6" resolves to version 5.6.3)
• a patch release, 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 against 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. Newly released versions are added to the list as soon as they become available.

To set an upper bound, the intersection of two ranges can be used: >=5.4 <5.6. In this case, 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

Examples:

• ? can be used to select files or directories that differ by only one character in their name: 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 can be specified:

• "findup", automatically discovers the nearest tsconfig.json file (default)
• "baseline", uses default compiler options
• a path, like "./tsconfig.test.json", loads a specific tsconfig.json file
• an inline JSON string, provides TSConfig directly

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.

{
  "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.