This document explains how to write tests for the TypeScript compiler, language service, and related tooling. It covers test organization, different test types, test metadata syntax, baseline management, and debugging strategies. For information about setting up your environment and running tests, see Development Workflow.
TypeScript uses a comprehensive test suite to validate compiler behavior, language service features, and build system functionality. Tests are written as TypeScript source files with metadata annotations and validated against baseline outputs. This page explains:
Tests are organized hierarchically by category and purpose in the tests/ directory.
Test Categories:
| Directory | Purpose | Example Files |
|---|---|---|
tests/cases/compiler/ | General compiler functionality, edge cases, and bug fixes | Individual .ts files testing specific features |
tests/cases/conformance/ | Spec compliance tests organized by language feature | Tests under subdirectories like types/, expressions/, etc. |
tests/cases/fourslash/ | Language service tests (completions, navigation, refactorings) | Tests using Fourslash mini-language |
tests/baselines/reference/ | Expected baseline outputs for comparison | .js, .d.ts, .errors.txt, .types, .symbols files |
tests/baselines/local/ | Generated outputs from test runs | Same structure as reference, compared during test execution |
Sources: src/compiler/types.ts228-266 src/services/services.ts212-214
The test infrastructure bridges the gap between raw test files and the internal compiler API to generate verifiable artifacts.
Sources: src/compiler/program.ts42-50 src/compiler/emitter.ts66-77 src/harness/harnessLanguageService.ts1-20
Compiler and conformance tests are TypeScript source files. Each test file should demonstrate a specific behavior or fix.
Location Guidelines:
tests/cases/compiler/): Bug fixes, edge cases, general functionality.tests/cases/conformance/): Spec compliance, organized by language area such as classes/, types/, or expressions/.Tests support metadata tags using the format // @metaDataName: value. These tags are parsed into CompilerOptions src/compiler/types.ts90
Common Metadata Tags:
| Tag | Purpose | Code Reference |
|---|---|---|
@target | Set compilation target | ScriptTarget |
@module | Set module system | ModuleKind |
@lib | Specify library files | lib options |
@strict | Enable strict mode | strict flag |
@noEmit | Skip JS emission | noEmit flag |
@declaration | Generate .d.ts | declaration flag |
@filename | Multi-file delimiter | Test Harness |
Example Test with Metadata:
Sources: src/compiler/commandLineParser.ts1-100 src/compiler/program.ts26-31
Use the @filename tag to simulate multiple source files. The test harness splits the content and creates a virtual file system for the Program src/compiler/program.ts264
Sources: src/compiler/moduleNameResolver.ts1-50 src/compiler/resolutionCache.ts1-30
Fourslash tests validate language service features like completions src/services/completions.ts35 navigation src/services/goToDefinition.ts127 and refactorings src/services/services.ts268
Fourslash tests use a custom syntax with markers to indicate cursor positions and ranges.
Fourslash Syntax Elements:
| Syntax | Purpose |
|---|---|
/**/ | Anonymous marker (cursor position) |
/*name*/ | Named marker for specific locations |
| `[ | text |
verify. | Verification command suite |
Example Fourslash Test:
Sources: tests/cases/fourslash/fourslash.ts1-50 src/harness/fourslashImpl.ts1-100
The test system compares generated outputs against reference baselines to detect regressions.
| File Type | Contents | Source Entity |
|---|---|---|
.js | Emitted JavaScript | Emitter src/compiler/emitter.ts1 |
.errors.txt | Diagnostic messages | Diagnostic src/compiler/diagnosticMessages.json1 |
.types | Type information | TypeChecker src/compiler/checker.ts1 |
.symbols | Symbol information | Binder src/compiler/binder.ts1 |
Sources: src/compiler/program.ts66-71 src/compiler/checker.ts148-156
tests/baselines/local/.tests/baselines/reference/.hereby baseline-accept.Sources: CONTRIBUTING.md255-270
Use the hereby task runner to execute tests.
Sources: CONTRIBUTING.md180-204
To debug, use the --inspect or -i flag to allow debugger attachment.
The LanguageService src/services/services.ts212 and Program src/compiler/program.ts264 can be inspected during execution to verify AST src/compiler/types.ts228 and Symbol src/compiler/types.ts228 states.
Sources: CONTRIBUTING.md206-214
Refresh this wiki