This page provides an overview of how the TypeScript repository is built and tested. It covers the hereby task runner, the major build outputs it produces, and the categories of tests the repository runs. For detailed coverage of individual topics, see:
For information about CI workflows that invoke the build and test system, see CI and Release Workflows.
The build system is driven by `hereby` a JavaScript task runner. All task definitions live in Herebyfile.mjs The test runner is Mocha, invoked via scripts in scripts/build/tests.mjs Source is compiled using esbuild for bundling and the TypeScript compiler (bootstrapped from the Last Known Good, or LKG, build) for type checking.
The two primary entry points for contributors are:
# Build the full compiler and services
npm run build:compiler # calls: hereby local
# Build and run all tests
npm test # calls: hereby runtests-parallel --light=false
The local task (the default hereby task, Herebyfile.mjs666-671) is the standard full build. It produces the following files under built/local/:
| Output File | Task Name | Source Entrypoint |
|---|---|---|
built/local/tsc.js | tsc | src/tsc/tsc.ts |
built/local/typescript.js | services | src/typescript/typescript.ts |
built/local/typescript.d.ts | dts-services | bundled from built/local/typescript/typescript.d.ts |
built/local/tsserver.js | tsserver | src/tsserver/server.ts |
built/local/tsserverlibrary.js | lssl | re-exports typescript.js |
built/local/typingsInstaller.js | typings-installer | src/typingsInstaller/nodeTypingsInstaller.ts |
built/local/watchGuard.js | watch-guard | src/watchGuard/watchGuard.ts |
built/local/run.js | tests | src/testRunner/_namespaces/Harness.ts |
built/local/lib.*.d.ts | lib | src/lib/*.d.ts |
Sources: Herebyfile.mjs416-670
The following diagram shows how the major build tasks in Herebyfile.mjs depend on each other. Task names correspond directly to hereby task names and exported task() calls.
Diagram: Major build task dependencies in Herebyfile.mjs
Sources: Herebyfile.mjs45-671
Tests are loaded by the test runner entry point at src/testRunner/runner.ts Runner instances are registered via createRunner() src/testRunner/runner.ts58-74 Each runner extends the abstract RunnerBase class src/harness/runnerbase.ts22-65
TestRunnerKind | Runner Class | Test Location |
|---|---|---|
conformance | CompilerBaselineRunner(Conformance) | tests/cases/conformance/ |
compiler | CompilerBaselineRunner(Regressions) | tests/cases/compiler/ |
fourslash | FourSlashRunner(Native) | tests/cases/fourslash/ |
fourslash-server | FourSlashRunner(Server) | tests/cases/fourslash/server/ |
project | ProjectRunner | tests/cases/projects/ |
transpile | TranspileRunner | inline test cases |
unittest | (Mocha suites directly) | src/testRunner/unittests/ |
Sources: src/testRunner/runner.ts58-74 src/harness/runnerbase.ts7-9
Diagram: Test runner class hierarchy and parallel execution architecture
Sources: src/testRunner/runner.ts261-277 src/testRunner/parallel/host.ts36-42 src/testRunner/parallel/worker.ts20-25 src/harness/runnerbase.ts22-53
When workerCount > 1, the main process becomes the Parallel.Host and forks N child processes that each run as a Parallel.Worker. The host distributes test files to workers via IPC using test or batch message types, and workers report back result or progress messages. Worker count defaults to os.cpus().length - 1 (or all CPUs in CI). See scripts/build/options.mjs33
The table below lists the hereby tasks most relevant to day-to-day development. Run hereby --tasks to see the full list.
| Task | npm script alias | Description |
|---|---|---|
local | npm run build:compiler | Full compiler + services build (default) |
min | — | Builds only tsc and tsserver |
tests | npm run build:tests | Builds the test runner (run.js) |
runtests | — | Builds tests and runs them serially |
runtests-parallel | npm test | Builds tests and runs them with multiple workers |
lint | npm run lint | Runs ESLint on compiler and scripts |
check-format | — | Checks formatting with dprint |
format | npm run format | Applies dprint formatting |
knip | npm run knip | Finds unused exports and dependencies |
generate-diagnostics | — | Regenerates diagnosticInformationMap.generated.ts |
baseline-accept | — | Accepts new test baselines |
watch-local | — | Watch mode for the full build |
Sources: Herebyfile.mjs45-870 package.json89-101
Build scripts read command-line options from scripts/build/options.mjs These can be passed directly to hereby:
| Option | Default | Description |
|---|---|---|
--tests / -t | — | Regex filter for test names |
--workers / -w | cpus - 1 | Number of parallel worker processes |
--light | true | Skips some slower verification steps |
--dirty | false | Skips cleaning output directories before running |
--coverage | false | Collects V8 coverage via c8 |
--bundle | true | Uses esbuild for bundling (disable with --no-bundle) |
--typecheck | true | Runs TypeScript type checking |
--failed | false | Reruns only tests recorded in .failed-tests |
--shards / --shardId | — | Splits the test suite across CI shards |
--runners | — | Comma-separated list of runner kinds to run |
Sources: scripts/build/options.mjs1-91
Herebyfile.mjs # Task definitions (hereby entry point)
scripts/
build/
options.mjs # CLI argument parsing for build/test scripts
tests.mjs # runConsoleTests(), writeTestConfigFile()
utils.mjs # exec(), rimraf(), needsUpdate(), memoize()
projects.mjs # buildProject(), watchProject(), cleanProject()
localization.mjs # localizationDirectories list
src/
testRunner/
runner.ts # TestConfig, createRunner(), startTestEnvironment()
parallel/
host.ts # Parallel.Host.start() — manages worker processes
worker.ts # Parallel.Worker.start() — runs tests in child process
harness/
runnerbase.ts # RunnerBase abstract class, TestRunnerKind type
built/
local/ # All build outputs (git-ignored)
tests/
baselines/
reference/ # Committed baseline files
local/ # Generated baselines (git-ignored, compared to reference)
cases/ # Test input files
Sources: .gitignore3-16 Herebyfile.mjs1-50 src/testRunner/runner.ts1-20
Herebyfile.mjs task coverage, bundler configuration, and watch modebaseline-accept, and CI validationRefresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.