TypeScript Project

A project with a TSConfig file and TypeScript installed in this guide is referred as a TypeScript project.

TSTyche is build to test projects of any size and complexity. To learn more, see the Introduction page.

TSConfig File

To load the compiler options for a test file, TSTyche searches for the nearest tsconfig.json which includes the file in question. If a particular test file is not included in any of TSConfig files found in enclosing directories, the default compiler options will be set.

To specify the path to tsconfig.json explicitly, pass it with the --tsconfig command line option or use the tsconfig configuration option.

The test runner always prints the path of the TSConfig file. To inspect the compiler configuration, copy the path and pass it to tsc together with the --showConfig option:

tsc --project ./typetests/tsconfig.json --showConfig

Language Service Plugins

To work smoothly with Svelte, Vue or similar projects a code editor needs an additional extension to be installed. Usually the extension provides a TypeScript language service plugin (opens in a new tab), which helps the editor to reason about typings of a project.

TSTyche makes sure the plugins are loaded, but they must be installed and explicitly listed in a TSConfig file. For example, if your type tests import from .svelte files, install the typescript-svelte-plugin package:

npm add -D typescript-svelte-plugin

And add it to the language service plugins (opens in a new tab) list in tsconfig.json:

{
  "compilerOptions": {
    "plugins": [{ "name": "typescript-svelte-plugin" }]
  }
}

File Structure

An important step in type testing is take care that any accidental typings do not leak into test files. The following strategies help to ensure isolation of your tests.

Dedicated Directory

It is recommended to keep type test files in a dedicated directory. For instance, you can name it __typetests__:

- MethodLikeKeys.tst.ts
- tsconfig.json
MethodLikeKeys.ts

package.json

tsconfig.json

Here the root tsconfig.json specifies the compiler configuration of the project. Extend from it and reuse the configuration for type testing:

./src/__typetests__/tsconfig.json

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "noEmit": true,
    "strict": true,
    "types": []
  },
  "include": ["./"],
  "exclude": []
}

The above configuration prevents loading global scope typings from @types/* packages and makes it easy to include only the files you need for type testing.

By convention it is recommended to suffix the functional tests with .test.* and the type tests with .tst.*. The latter ones are only statically analyzed and are not meant to be executed, hence the missing e in the suffix.

Shared Directory

It is also possible to keep functional and type tests in a single shared directory:

- MethodLikeKeys.tst.ts
- secondItem.test.ts
- tsconfig.json
MethodLikeKeys.ts
secondItem.ts

package.json

tsconfig.json

tstyche.config.json

Remember to specify the types list of the compilerOptions. Keep it as minimal as possible to avoid any global typings leaking into your type tests:

./src/__tests__/tsconfig.json

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "noEmit": true,
    "strict": true,
    "types": [] // prefer explicitly importing testing APIs
  },
  "include": ["./"],
  "exclude": []
}

To use type testing assertions in functional tests as well, configure TSTyche to include them in the test run:

./tstyche.config.json

{
  "testFileMatch": ["**/*.test.ts", "**/*.tst.ts"]
}

Next to Source Files

Isolation of type tests placed next to source files is complicated, but not impossible. A hypothetical project could look like this:

MethodLikeKeys.ts
MethodLikeKeys.tst.ts
secondItem.ts
secondItem.test.ts

package.json

tsconfig.json

tsconfig.test.json

tstyche.config.json

The references field could be used to define the project in the root tsconfig.json:

./tsconfig.json

{
  "compilerOptions": {
    // ...
    "composite": true
  },
  "include": ["./src"],
  "exclude": ["**/*.test.*", "**/*.tst.*"],
  "references": [{ "path": "./tsconfig.test.json" }]
}

And tsconfig.test.json can extend it like this:

./tsconfig.test.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "strict": true,
    "types": [] // prefer explicitly importing testing APIs
  },
  "exclude": []
}

JavaScript Project Reporters