Testing#

The release gate tests the supported profile, compatibility baseline, security policy, renderer parity, real content, malformed input, complexity limits, bundle budgets, declarations, build output, and package contents.

Full verification#

pnpm run verify

This runs tests, typechecking, a production build, docs validation, compatibility accounting, bundle measurement, benchmarks, and an npm package dry run.

Downstream corpus testing#

Point the corpus suite at one or more content directories:

MARKDOWN_CORPUS_DIRS=../tanstack.com/src/blog:../tanstack.com/docs \
  pnpm run test:corpus

Each Markdown file is tested in core and docs-extension modes for deterministic AST output, deterministic HTML output, React SSR success, and expected renderer structure. Focused adapter fixtures additionally prove Octane static SSR parity.

Practical compatibility audit#

pnpm run corpus:audit:tanstack
pnpm run corpus:audit:external

The TanStack audit discovers local sibling repositories, scans their tracked Markdown and MDX files, and records each Git revision and dirty state. The external audit checks out exact commits from twenty representative documentation and blog repositories. MDX is inventoried but not parsed.

Both audits parse every Markdown file twice with the docs profile, verify deterministic AST and HTML output, inventory syntax usage, and compare rendered output with Marked. Marked is a differential reference, not a correctness oracle. Reports separate exact output, serialization differences, structural differences with equivalent text, and rendered-content differences.

The external audit runs in CI and fails on parser errors, nondeterminism, or any unexplained target-profile content difference. The local TanStack audit enforces the same rule when the sibling repositories are available.

• TanStack repository corpus
• External docs and blogs corpus

Triage policy#

1. Parse errors or nondeterministic output are always defects.
2. Content differences in docs, blogs, or READMEs that use only the supported profile must be fixed or explained before release.
3. Serialization and structure differences are reviewed but do not imply incorrect output.
4. MDX, site templates, opt-in HTML, and documented unsupported syntax measure demand; they do not expand the profile automatically.

A syntax rule enters the profile only when real target content needs it, the behavior can be covered across renderers, and its parser and bundle cost are justified. CommonMark examples remain edge-case accounting rather than the product roadmap.

Compatibility accounting#

pnpm run conformance

The command compares output against CommonMark 0.31.2 examples, preserves every established match as a regression baseline, and updates the generated report. It is not a claim of full conformance.

Selected official GFM examples separately cover tables, task lists, and strikethrough in the supported profile.

Comparing a change#

Compare the working tree with a Git revision or a saved directory containing src/, using the same compiler and runtime:

node --import tsx scripts/compare-revision.mjs main

The script measures minified, gzip, and Brotli sizes, lists gained and lost CommonMark matches, and alternates old and new implementations over nine timing samples. It includes React and Octane node creation and SSR, and retains the medians and every sample in artifacts/audit-comparison.json. Run it without other CPU-heavy work. Small timing differences can still be noise, and Node results do not establish browser performance.

Size tests protect both narrow imports and the complete namespace of every public entry point. Their ceilings are the smaller audited working tree, not the earlier npm release. A smaller gzip bundle does not excuse growth in minified or Brotli bytes.

After running both corpus audits, add --corpus to compare both revisions in core and docs-extension modes against the same source files and Marked version. Use --no-bench when checking only output and size. Review changed output even when a file already differs from Marked. The corpus classification is a triage tool, not proof that two outputs behave identically.

Resilience#

The suite includes fixed-seed generated malformed documents and adversarial cases such as unmatched delimiters, deep blockquotes, nested lists, and parser depth exhaustion. Performance thresholds are generous enough for CI variation but strict enough to catch accidental superlinear behavior.

Synchronous hang regressions, including oversized numeric code-line ranges, run in a subprocess with a deadline. An ordinary test timeout cannot interrupt a blocked JavaScript event loop.

The AI streaming profile renders every character prefix of a representative response and verifies deterministic output, React/HTML parity, safe handling of executable URLs and raw HTML, unfinished-fence behavior, trailing-placeholder suppression, and bounded progressive rendering.

Documentation coverage#

pnpm run docs:verify checks that:

• every docs page is in docs/config.json
• every navigation target exists
• local links and anchors resolve
• every page has frontmatter
• every package entry point appears in the API index
• every exported declaration name appears in its reference page

When adding public API, update declarations and reference documentation in the same change.

Skill version coverage#

pnpm run test:skills validates each shipped Intent skill and requires its embedded package metadata, package-qualified examples, cache keys, and source artifacts to match package.json.

pnpm version runs pnpm run skills:sync-version after changing the package version. The normal verification gate fails instead of publishing stale skill guidance when those files drift.