Test Organization

Relevant source files

This document describes how tests are organized in the TypeScript compiler repository. It covers the directory structure, test categories, test configuration, and how tests are executed. For information about baseline testing specifically, see Baseline Testing. For information about Fourslash testing for language service features, see Fourslash Testing.

Test Categories and Directory Structure

Tests in the TypeScript repository are organized into several categories based on their purpose and scope.

Title: Test Directory and Data Flow

Sources: Herebyfile.mjs532-551 scripts/build/tests.mjs22-23

Test Case Categories

The repository contains the following test categories:

Category	Location	Purpose
Unit Tests	`src/testRunner/unittests/`	Test individual functions and classes in isolation
Compiler Tests	`tests/cases/compiler/`	Test compiler behavior and code generation
Conformance Tests	`tests/cases/conformance/`	Verify compliance with ECMAScript and TypeScript specifications
FourSlash Tests	`tests/cases/fourslash/`	Test language service features (completions, navigation, etc.)
ESLint Rule Tests	`scripts/eslint/tests/`	Test custom ESLint rules

Sources: Herebyfile.mjs553-557 package.json89-93

Test Execution Infrastructure

The test execution system is built around Mocha as the test runner, with custom infrastructure for configuration and parallel execution.

Title: Test Infrastructure Code Entities

Sources: Herebyfile.mjs679-684 scripts/build/tests.mjs34-188 package.json47-84

Test Runner Entry Points

The primary test runner is built from the src/testRunner project and output to built/local/run.js. This file serves as the entry point for all Mocha-based tests.

Title: Test Runner Build Pipeline

Sources: Herebyfile.mjs534-551 package.json93

Test Configuration System

Tests are configured through a combination of command-line options and a dynamically generated test.config file.

Command-Line Options

The test infrastructure accepts numerous command-line options that control test execution:

Option	Type	Purpose
`--tests=<pattern>`	string	Run tests matching the specified pattern
`--failed`	boolean	Run only tests listed in `.failed-tests`
`--light`	boolean	Run tests in light mode (fewer verifications, faster)
`--dirty`	boolean	Skip cleaning test output directories before running
`--workers=<count>`	number	Number of parallel workers for test execution
`--timeout=<ms>`	number	Override default test timeout (default: 40000ms)
`--coverage`	boolean	Generate code coverage reports using c8
`--keepFailed`	boolean	Keep tests in `.failed-tests` even if they pass
`--shards=<count>`	number	Total number of shards for distributed testing
`--shardId=<id>`	number	1-based ID of this shard

Sources: scripts/build/options.mjs1-92 scripts/build/tests.mjs35-48

Test Configuration File

The writeTestConfigFile() function generates a test.config JSON file that passes configuration from the build system to the test runner.

Sources: scripts/build/tests.mjs209-226 scripts/build/tests.mjs87-89

The configuration file contains:

test: Array of test patterns to run
light: Boolean indicating light mode
workerCount: Number of parallel workers
timeout: Test timeout in milliseconds
shards: Total number of shards
shardId: Current shard identifier

Test Execution Flow

Tests are executed through hereby tasks that coordinate building the test infrastructure and running Mocha.

Title: Execution Workflow

Sources: scripts/build/tests.mjs34-188 Herebyfile.mjs679-684

Parallel Test Execution

When running tests in parallel, the system creates a temporary folder to store task configurations and divides the work among multiple workers:

Generate unique task configuration folder: /tmp/ts-tests<N>/
Determine worker count (defaults to CPU count - 1)
Partition tests across workers
Execute workers in parallel
Aggregate results

Sources: scripts/build/tests.mjs69-81

Test Baseline System

Tests generate output files that are compared against reference baselines to detect regressions. Baseline files include:

.js: The emitted JavaScript code tests/baselines/reference/conditionalTypes1.js1-210
.errors.txt: Compiler diagnostic messages tests/baselines/reference/conditionalTypes1.errors.txt1-87
.types: Type information for all expressions tests/baselines/reference/conditionalTypes1.types1-272
.symbols: Symbol information and definitions tests/baselines/reference/conditionalTypes1.symbols1-160

Sources: scripts/build/tests.mjs22-23 scripts/build/tests.mjs190-193

Coverage Reporting

Code coverage is collected using c8 (the native V8 coverage tool) and reported using monocart-coverage-reports.

Sources: scripts/build/tests.mjs147-158 package.json58 .c8rc.json1-8

Coverage configuration is defined in .c8rc.json:

Reporters: lcovonly, cobertura, v8, v8-json, codecov
Source: src/ directory
Exclude: **/node_modules/**, built/**, tests/**