Testing TypeScript documentation examples

The short answer

Test TypeScript documentation examples twice: type-check them in a deliberate consumer project, then execute the applicable reader journey in its intended runtime. tsc --noEmit checks a TypeScript program without emitting output files; it does not run the program. A runtime pass cannot establish that the published types are correct, and a type-checking pass cannot establish that the code behaves as promised.

DocsAlive handles ts and typescript fences by stripping simple type annotations and executing the resulting code on Node 20. Other TypeScript-only syntax is not judged. It does not run tsc or read tsconfig.json, so a passing example is not a type check and a type error can go unnoticed. Pair the scan with a tsc --noEmit step that your team owns. jsx and tsx are not judged yet and are classified as unsupported-syntax.

The JavaScript documentation testing guide covers runtime concerns that also matter after types disappear. Start with the docs testing overview and how it works, then use the framework reference to identify the Markdown pages in scope. For other authoring systems, see the Sphinx guide and ReadMe guide.

Why TypeScript examples break

A snippet makes several promises at once. Its import must resolve, the published declarations must describe the API correctly, the code must satisfy the reader's compiler settings, and the resulting program must work in its runtime. A change in any of these can break a reader's copy even if the prose looks unchanged. Check which promise failed before editing the page.

The TypeScript handbook explains that type annotations are erased and do not change runtime behavior. Consequently, code can execute after annotations are removed while a compiler would report an error about those annotations. The reverse is also possible: code can type-check but fail at runtime because a service, file, value or installed package behaves differently from the assumptions in the example.

Compiler options matter. Strictness affects the checks applied, while module settings affect the model used for modules and their resolution. A snippet checked inside the library's own source tree may have access to files, declarations or dependencies that a new consumer does not. A focused consumer project makes those assumptions visible and lets the test exercise the artifact a reader is meant to install.

Keep runtime and type results together in the review, but label them separately. A changed package export may appear as a resolution failure, a type error or a runtime import error depending on the path being checked. Reproduce the problem using the intended artifact before deciding whether to fix the documentation, the package, or the test setup. See JavaScript documentation testing for the runtime side of that investigation.

Decide what the compiler program includes

The compiler options reference describes tsc and its command-line options. The TSConfig reference describes files as an allowlist and include as patterns resolved relative to the configuration file. An allowlist is useful for a small set of snippets; patterns can cover a larger test directory. Verify that each important snippet is actually in the program before trusting a clean result.

noEmit prevents output such as JavaScript, source maps and declarations from being emitted. Running npx tsc --noEmit -p with a project directory checks the configured program without running its code. Keep the configuration and the set of included examples under review, especially when pages are renamed or examples move. A successful check on an empty or incomplete selection is not evidence about an omitted page.

The strict setting enables a family of stronger type checks. Select settings that reflect the reader environment you intend to support, and record them with the result. A stricter consumer configuration can expose an example that only works under more permissive assumptions. If the supported audience uses more than one configuration, decide which configurations deserve separate coverage and state the limits of each result.

Make the environment explicit

The TSConfig module option sets the program's module system; moduleResolution selects how module references are resolved. Choose the pair for the actual consumer environment. A snippet that uses an import has to be checked under a configuration consistent with how the reader will find and load that package. An error can arise from the example, the package's published entry points or a mismatch between the test and the documented environment.

target affects which JavaScript features are transformed in compiler output, while lib selects available library type definitions. Since noEmit produces no runtime output, a clean check does not demonstrate that the target runtime provides each API. Match the definitions and runtime assumptions to the environments the page promises. Test actual runtime behavior separately rather than inferring support from declarations alone.

The types option can restrict which listed type packages enter global scope. skipLibCheck skips checking declaration files, trading some type-system accuracy for speed. These choices change what a clean result means. In particular, if your goal is to assess a package's published declarations, consider whether skipping declaration checks hides evidence you want. Record the decision instead of copying a configuration without understanding the coverage.

isolatedModules warns about certain code that cannot be correctly interpreted by a single-file transpilation process. verbatimModuleSyntax makes the distinction between type imports and value imports relevant to emitted module syntax. erasableSyntaxOnly restricts TypeScript-specific constructs to syntax that can be erased without runtime semantics. These options address different concerns; none turns a runtime scan into a TypeScript compiler check. The TSConfig reference explains the details and should be consulted when choosing settings.

Build a clean consumer project

Create a small project for documentation examples outside the package's internal source context. Install the same artifact a reader is instructed to use, along with the compiler and declarations needed for that scenario. Pin the dependency selection through the project's normal lockfile and record what was installed. If a page documents a browser path and another documents a Node path, consider separate configurations that reflect those different environments.

Copy or extract each complete snippet into a file in that project, retaining the source page and line in the test inventory. Preserve imports and the order of steps where the page presents a sequence. If the page gives an intentionally incomplete fragment, supply a clearly identified harness around it and distinguish the harness from text the reader copies. Do not let a helper silently provide an import or variable that the page should have explained.

Set files or include to cover the intended snippets and choose compiler options deliberately. Confirm that a known error in a representative snippet is reported before relying on the check, then remove that temporary change. That simple coverage check helps reveal an incorrect path or configuration. Review the actual diagnostic, affected snippet and package artifact whenever the check fails.

If examples are copied into test files, establish a process to keep them synchronized with the published page. If a harness extracts them, inspect its output when the page format changes. Either way, trace a diagnostic back to the original source. An independently maintained test can otherwise pass after the documentation has drifted. Use the docs testing checklist to assign an owner for the mapping.

Write examples for both checks

This fictional page excerpt uses a simple annotation. The package name is illustrative, so a real test must install the actual documented package and use its real API.

# Show a greeting

```ts
import { greet } from "@acme/docs-demo";
const audience: string = "reader";
console.log(greet(audience));
```

The product can strip the simple string annotation and attempt to execute the block on Node 20. Whether it passes depends on the installed package and setup. That runtime result says nothing about whether greet accepts a string according to its declarations. Include the snippet in your consumer project and type-check it as well. Keep setup supplied to the scanner visible so it does not obscure an instruction the reader needs.

A second example uses an interface and a generic. It belongs in a compiler-owned check; the product does not judge this TypeScript-only syntax.

# Keep a value

```ts
interface Result<T> {
  value: T;
}

function wrap<T>(value: T): Result<T> {
  return { value };
}

const result: Result<string> = wrap("ready");
console.log(result.value);
```

A type check can verify the relationships in that example under the chosen configuration. It still does not execute console.log or compare its result. If the printed value is part of the promise, run an appropriate runtime test too. A separate test can use the actual build path and runtime supported by the project. The JavaScript guide discusses the corresponding execution concerns.

Run the checks in CI

The following outline assumes the repository has a lockfile, a prepared consumer project at docs-typecheck, and the product CLI available. Replace the directory with the actual project. The command uses --noEmit explicitly so the type-checking step is clear in the CI log.

npm ci
npx tsc --noEmit -p docs-typecheck
docsalive scan . --execute --include 'docs/**' --out docs-test-report

The first command prepares the repository's locked dependencies. The second checks the consumer program selected by its configuration. The third scans eligible Markdown pages and executes supported planned blocks. Adapt dependency installation to where your consumer project keeps its lockfile, and ensure the fictional package above has been replaced by the actual artifact. The CLI reference documents --docs-dir, repeatable --setup and report options.

Review type diagnostics and the scan report separately. A runtime pass may represent a stripped example, not a type check; a skip identifies a coverage gap. Track the package artifact, compiler configuration, runtime environment and page revision for each run. When a release changes declarations or exports, repeat the checks against the artifact readers will actually receive. Also run relevant checks on documentation changes so a broken example does not wait for a release.

Trace the reader's complete path

A single code block may be preceded by an installation command, configuration instructions and a statement about the environment. Test the setup as well as the block when it is part of the page's promise. The installation guide helps separate a package installation problem from a later example failure. If a test harness installs the package first, document that setup and compare it with the instructions a reader sees.

Within a page the product keeps planned blocks in order and uses a fresh container. This helps preserve earlier variables for later examples without carrying state from an unrelated page. It does not establish a journey that spans pages, browser-specific behavior or every tab choice. For those cases, design a separate test with the required state and retain the result beside the compiler and scan reports.

Check output only where the page makes a stable claim, and investigate changes before updating the expected text. A type-correct value can still be the wrong value for the example. Conversely, an incidental difference in output does not necessarily mean the documented API is wrong. Use the source location, actual result and intended behavior to make that decision. The guide index and free tools guide provide additional starting points for complementary checks.

Review compiler and runtime results together

When a check fails, capture the diagnostic and the exact snippet before changing configuration. A module resolution error may mean that the example names the wrong export, the installed artifact lacks a file, or the consumer project represents a different environment from the page. Reproduce with the intended artifact and follow the evidence to the responsible source. Changing an option solely to silence the error can make the test less representative of readers.

When a type check succeeds but execution fails, inspect the actual runtime inputs and dependencies. Types describe constraints checked by the compiler; they do not guarantee that a remote service is available or that a local file exists. If execution succeeds but the compiler reports an error, inspect the declarations and settings as well as the snippet. Both results are useful and can be true at the same time.

Make the test inventory part of review. For each example record the source page, consumer file, configuration, installed artifact and runtime check, if any. Include a separate entry for fragments and unsupported syntax. Check the mapping when a code block is edited or moved. This prevents a stale copied snippet from passing while the published instruction has changed, and gives the maintainer a direct path from a diagnostic to the text a reader will copy.

Triage failures before changing a page

A failing block is a starting point for investigation. Read the actual error, the documented prerequisites, the selected block and the environment together. A missing package in the test environment may point to an omitted installation instruction, an intentional prerequisite, or an incorrect setup choice. Reproduce the smallest reader journey before deciding which explanation fits.

A timeout, runtime error or external network result can need human review. An output difference may reflect a changing timestamp or ordering, but it may also reveal a change that matters to readers. Keep the expected and actual output with the finding. Do not update a result merely to turn a report green; establish what the page promises first.

The report makes these decisions easier to trace. Its JSON findings identify the page, line, language, status, category and reason, with a hint and evidence where supplied. The summary includes a count of likely documentation bugs. A pass can mean execution or a syntax check, while warn, fail and skip each require their own interpretation. Read the plan and the reason rather than treating all statuses as equivalent.

A reproducible fix should identify the installed artifact and any setup provided outside the page. Run the relevant check again after changing the source, and look for the next failure in the same sequence. If a page depends on an earlier page, test that longer journey separately: a fresh environment per page makes missing local setup easier to spot, but it does not establish the whole cross-page path.

Checklist for a documentation example test

The docs testing checklist helps turn that inventory into a repeatable review. The installation testing guide is useful when the first failure is in setup. For the wider relationship between builds, sources and reader-visible pages, see static-site documentation testing.

What this does not replace

DocsAlive does not run tsc, read tsconfig.json, render a site or check links. It strips simple TypeScript annotations and executes the result on Node 20; other TypeScript-only syntax is not judged. jsx and tsx are not judged yet. A pass is not a type check, and an error in types can go unnoticed. Own a separate compiler step and test other runtimes and reader paths as needed.

Human review still matters for whether the instructions are understandable, the output is meaningful and the reader can complete the task. A successful isolated block does not prove that a whole tutorial is coherent. Keep build, link, accessibility and visual review wherever they apply, and assign an owner to every important path the automated report did not cover.

For a starting point, the free health check lets you send a public repository you own or maintain; the team runs the engine on up to 40 of its docs pages and emails the real report within 2 business days; the checkout is deleted after the run. Pricing is Open source $0/month, Team $299/month, Growth $699/month, and Scale from $1,499/month.

The sources we checked

FAQ

Does tsc --noEmit run a snippet?

No. It checks the selected program without emitting output files. Run a separate runtime check to establish behavior.

Does a product pass prove that types are correct?

No. Simple annotations are stripped before execution, and the product does not run the compiler or read tsconfig.json. A type error can go unnoticed.

What happens to an interface or generic?

Other TypeScript-only syntax is not judged by the product. Include the example in a compiler-owned check and arrange a runtime check where behavior matters.

Are jsx and tsx tested?

They are not judged yet and are classified as unsupported-syntax. Use a separate suitable check and record the gap.

Why use a consumer project?

It makes the installed artifact, dependencies and compiler settings explicit. It can expose assumptions that a test inside the library's own source tree might conceal.

Which compiler options should I use?

Choose settings that represent the documented reader environment, including program selection, strictness and module resolution. Record the configuration so the meaning of a pass is clear.

Is one Node execution enough for every reader?

No. The product executes supported TypeScript fences on Node 20 after stripping simple annotations. Test other promised environments and runtime paths separately.

How do I keep the test aligned with the page?

Map every checked snippet back to its source and review that mapping when pages change. If a harness supplies missing context, record it explicitly.