On this page
The short answerMap the Node reader journeyDistinguish ESM and CommonJSTest the installed package and versionType-check TypeScript snippetsExtract examples without changing their meaningCompare output without hiding changesHandle credentials, interaction and external statePut the result in contextMake checks part of release workRead reports and improve coverageHow DocsAlive fitsThe short answer
Test the JavaScript and TypeScript examples readers actually copy, using the Node version, module format and package version the page promises. Execute complete JavaScript programs in a clean project, type-check TypeScript examples with a deliberate compiler configuration, and check meaningful output and side effects. A type check does not execute code; a successful run does not prove the published types or every supported module format work.
Inventory Markdown and MDX fences, separate alternatives from ordered steps and retain the page location in failures. The Python guide covers a different ecosystem; the release checklist turns these choices into a pre-release record.
Map the Node reader journey
Start at the first documented prerequisite. Record the supported Node versions, package manager, package name, installation source and first successful result. A reader may copy an install command, create a file, choose a module format and run it in a new directory. Reproduce that sequence instead of running only a fragment inside the project's existing development environment.
List complete programs separately from fragments, output blocks and alternative tabs. A browser example may rely on DOM APIs unavailable in Node. A Node example may require a particular working directory or environment variable. Label the intended runtime and explain any prerequisites on the page. Test each supported alternative or mark the gap; running the default tab does not verify the others.
Use a fresh temporary project for the install and execution path. Keep test setup separate from instructions the reader must follow. If the harness creates a configuration file or installs an extra package, determine whether the page must tell the reader to do the same. A global executable or a parent directory's node_modules can otherwise make an incomplete example appear to work.
Distinguish ESM and CommonJS
Node supports both ECMAScript modules and CommonJS, and the way a file is interpreted affects its imports and exports. An .mjs file is treated as an ES module and a .cjs file as CommonJS; the meaning of .js depends on package configuration, including the type field. Package export maps and the package's published files also affect which entry points can be imported. Test the format the page shows in a project configured the way the page describes.
For a self-contained ES module, save this as example.mjs and run node example.mjs:
import { basename } from 'node:path';
console.log(basename('/tmp/example.txt'));
The stable output is example.txt. A CommonJS equivalent uses const { basename } = require('node:path') in an example.cjs file. These are separate examples, not interchangeable instructions for every package. A package may expose different entry points or support only one format. Do not promise a require path merely because an ESM import worked.
For a real library, install the target artifact and use the exact import or require statement shown in the docs. Confirm the package entry point resolves and the expected named or default export is available. Include any required top-level asynchronous handling appropriate to the format. An error such as a missing export can reflect packaging or module configuration, not just a typo in the snippet.
If the documentation supports both module systems, run both paths in clean projects. Check the minimum supported Node version as well as a current supported version. Tooling that transforms modules may accept an example that fails when run directly by Node; make the toolchain and its configuration part of the promise when that is the intended path.
Test the installed package and version
A checkout, a packed candidate and a public registry package are different targets. During development, a workspace dependency can provide fast feedback. Before release, create the package artifact that will be published, install it in a new project and execute the documented examples against that artifact. A post-release check of the public package verifies the installation path available to readers, but cannot block a release already made.
Record the package name, exact version or artifact, Node and package-manager versions, platform and registry. Confirm that the installed files and entry points are the intended ones. A monorepo can resolve a workspace package or undeclared dependency locally even though a user installing the published tarball cannot. Execute the test outside the source tree and avoid inheriting unrelated node_modules directories.
A lockfile improves reproducibility, but a permanently locked test may miss a newly released compatible dependency that breaks a reader's fresh install. Consider one reproducible release check and a separate scheduled fresh-resolution check within supported constraints. Report which one failed. Do not silently update dependency versions or snapshots without checking whether the resulting behavior remains the documented contract.
Type-check TypeScript snippets
A TypeScript example can fail before execution because an export, overload, generic constraint or configuration changed. Put a complete example in a temporary project with the intended package and TypeScript version, then run the project's configured compiler, commonly npx tsc --noEmit. Ensure a tsconfig.json includes the extracted file and reflects the module resolution and library settings the documentation expects. Inspect compiler output and confirm that the intended file was included.
Type-checking is distinct from executing JavaScript. --noEmit checks types and configuration without producing runnable output. To test runtime behavior, compile with a suitable configuration or use a documented execution tool, then run the resulting program against the same package. Record both checks. A snippet can satisfy the compiler and still fail at runtime, and JavaScript can run while its published declaration files reject a valid use.
For snippets illustrating a deliberate type error, make the expected failure explicit and verify the relevant diagnostic rather than treating any compiler failure as success. A missing dependency or bad compiler configuration should not count as the intended error. Likewise, a fragment requiring surrounding declarations should say so; a hidden harness can validate an idea without proving the block is independently copyable.
Test compiler and Node versions that the project supports. TypeScript module resolution settings interact with package exports and module format, so use representative consumer configurations rather than assuming the repository's internal configuration is universal. Where examples rely on DOM or other ambient types, state that requirement and include the correct libraries in the test environment.
Extract examples without changing their meaning
Use a format-aware extractor for Markdown or MDX, and retain page and line information. Identify language tags, filenames, expected output, tabs and includes. An example split across blocks may need shared state; alternatives should start independently. Preserve the order and context a reader sees, and avoid executing output blocks or placeholder fragments as though they were programs.
Check stable output exactly when it is part of the promise. For generated IDs or network responses, assert stable properties and explain what varies. Prefer controlled local fixtures for repeatable tests, but record their limitations. An example involving a live service needs a separately authorized integration check if live behavior is the claim. Never expose credentials in the page or logs.
Review what the extractor skipped, including unselected tabs and unsupported syntax. Compare the rendered page to the source when a component or include changes the snippet. For the operational consequences of gaps, see why broken examples hurt adoption.
Compare output without hiding changes
Output can be a contract, an illustration or a partial excerpt. The page should tell readers which. A stable string or a required field can be compared exactly; a generated identifier, timestamp or unordered collection may need a narrower assertion.
| Shown output | Useful check | Review question |
|---|---|---|
| Deterministic calculation | Compare the exact value | Is formatting part of the promise? |
| Generated identifier | Check presence and expected type or form | Does the page explain that it varies? |
| Timestamp | Check the relevant field and meaning | Is the timezone or format significant? |
| Unordered results | Compare the relevant members | Is ordering actually documented? |
| Error message | Check the failure status and meaningful message | Does the reader need the exact wording? |
| Partial output | Check the shown properties and label omissions | Could an ellipsis be mistaken for literal output? |
Normalize only known variable fields. Removing every differing line can hide a renamed field or a missing error. Keep expected and actual evidence so a reviewer can decide whether the documentation, the implementation or the comparison should change. If the README shows a representative response, say which values are examples and which shape or fields the user should rely on.
Output also includes files, exit codes and side effects. A command that prints success but returns a failure status can break a script; a quiet command can succeed. Check the behavior the page describes rather than assuming that text on stdout is the only useful result.
Handle credentials, interaction and external state
Not every README example should run in the same unattended job. A command may require a secret, open a browser, wait for input, start a long-running server or modify a remote resource. Identify these cases and select an appropriate separate check. Do not put real keys in documentation, fixtures or logs.
| Case | Safer coverage | Remaining question |
|---|---|---|
| Credential placeholder | Check the configuration shape with harmless values | Does an authorized live flow work? |
| Interactive prompt | Check an available non-interactive path separately | Is the interactive path still understandable? |
| Long-running process | Test a bounded readiness condition and stop it | Does the full workflow behave as described? |
| State-changing command | Use an isolated disposable target where appropriate | Was cleanup verified? |
| Remote dependency | Use a fixture for local behavior and record its scope | Does the deployed dependency agree? |
| Platform-specific command | Run on the relevant platform or record a gap | Which supported platforms remain untested? |
A timeout is evidence to investigate, not an automatic verdict that the README is wrong. The process may be waiting for a prompt, an external service may be unavailable, or the command may be intended to remain running. Preserve the command and environment with the result. For credentialed behavior, use a separate authorized environment and a narrowly scoped test account when appropriate.
DocsAlive classifies examples needing credentials rather than executing them with real keys, including customer-provided test credentials. Interactive, graphical, destructive and long-running commands need a deliberate separate strategy; a skip or timeout does not establish whether the reader's full path works.
Put the result in context
A green run describes a particular set of examples, an environment and a point in time. Keep those details with the result: the documentation revision, artifact and version, operating system, runtime, dependency source, and commands used to set up the environment. Record the examples that were executed, checked without execution, skipped or left outside the selection. This makes the result useful when a reader reports a different outcome later.
Separate a broken example from a test infrastructure problem, but investigate both. A registry outage can block a valid install; an incorrect package name can look similar in a short log. Preserve the original error and identify the failing step. If a retry succeeds, retain enough information to see that the first attempt failed. Repeated intermittent failures can still affect readers even when a later retry works.
Give each failure an owner and a path to resolution. A documentation change may be the right fix when the product behavior is intentional; a product change may be needed when the documented behavior is the supported contract. If the release proceeds with a known gap, record the affected path, reason, owner and follow-up date. A hidden skip is not the same as an explicit decision to accept a limitation.
Make checks part of release work
Run fast, relevant checks when a change is proposed, and run the complete release selection against the candidate artifact before publishing. The GitHub Actions guide explains how pull request checks and scheduled runs answer different questions. Scheduled runs are useful for detecting changes in external dependencies or installation paths even when no documentation file has changed.
A release gate needs a named decision maker, an identified artifact and an agreed failure policy. If the suite only runs after publication it can detect an issue, but it cannot prevent that release. After publication, a separate check of the public package or endpoint can verify the path readers actually use. Preserve the distinction between candidate and published checks in the report.
A matrix should reflect supported promises rather than every possible combination. Start with the primary onboarding path and the oldest and newest supported runtimes where appropriate. Add operating systems, package managers or version combinations when the documentation promises them or past failures justify them. Show the matrix and its omissions to reviewers, so a single successful Linux run is not mistaken for proof of every platform.
Keep setup explicit. A fixture, mock server or prepared file may be necessary for a repeatable test, but it can also conceal a prerequisite that the page fails to explain. List what the harness supplies and compare it with what the reader sees. If a local fixture replaces a remote service, a pass establishes behavior against that fixture, not availability or compatibility of the live service.
Read reports and improve coverage
A useful report identifies the page, example, category, expected behavior, actual result and environment. Review skips and warnings alongside failures. A syntax check, a type check and an execution check establish different things; label each accurately. An example that runs and exits successfully may still return the wrong value or write a file somewhere unexpected, so check the behavior the surrounding text promises.
Avoid changing expected output simply to make a run green. First decide whether the product behavior is correct for the target release and whether the changed output affects the reader's task. Compare stable values exactly when possible. For timestamps, generated identifiers and unordered results, assert stable properties and explain variability. Normalize only what is truly variable, since a broad replacement can hide a meaningful regression.
Track coverage as an inventory, not just a percentage. Record the important paths that have no automated check, their owners and the reason. A credentialed example may need a separate authorized integration environment; an interactive setup may require a manual rehearsal. Assign an owner and review the list each release. Do not put real credentials in documentation, logs or public pull requests.
How DocsAlive fits
DocsAlive extracts supported fenced examples and runs or checks them in page order, with a fresh container for each page. It selects one variant from each tab group. Python, JavaScript on Node 20, simple TypeScript, shell and curl or HTTP examples have the coverage described in the framework reference. Compiled-language examples are recognized but not executed yet, and credential-dependent examples are classified rather than executed with real keys.
Read report.md and report.json with the findings reference. A pass can represent execution or a syntax check, and skipped blocks and unselected tab variants remain coverage gaps. A person still needs to review the explanation, the reader journey and any behavior the automated checks do not cover. When a model provider is configured, DocsAlive can draft a small fix and re-run the fixed page, retaining the fix only if it passes; fix pull requests are drafts and are designed not to merge automatically.
See pricing for DocsAlive plans: Team is $299 per month and Growth is $699 per month. To discuss coverage for your documentation, contact us.
If your JavaScript docs are published with Docusaurus, see testing Docusaurus documentation examples.
For TypeScript examples specifically, see testing TypeScript documentation examples.
