lread.test-doc-blocks

Reitit fork

This version has the following changes:

• Uses [matcher-combinators](https://github.com/nubank/matcher-combinators)

• Emits (is (match? expected actual)) assertions for the code blocks

• Doesn’t quote the expected value (so it can contain code)

• includes require: [matcher-combinators.matchers :as mcm]

• Supports =thrown-match⇒ which uses thrown-match? matcher

===

Test AsciiDoc and CommonMark code blocks found in articles and docstrings

🔥	While likely not malicious, sample code in docs could illustrate, for example, how to wipe a drive. So be deliberate and careful about what docs you run through test-doc-blocks.

Table of Contents

• Reitit fork
• Status
• Rationale
• Docs
• Used to Test Docs In…​
• Versioning
• People
  • Contributors
  • Current Maintainers
• License

Status

Folks have been using test-doc-blocks for years without issue.

Rationale

I wanted to make sure the code examples I provided in rewrite-clj v1 documentation do not mislead and function as expected for those who dare to try them. You might want the same for your library.

Docs

• User Guide

• Developer Guide

Used to Test Docs In…​

• etaoin - Pure Clojure Webdriver protocol implementation

• honeysql - Turn Clojure data structures into SQL

• malli - High-performance data-driven data specification library for Clojure/Script

• oksa - Generate GraphQL queries using Clojure data structures

• rewrite-clj - Rewrite Clojure Code and EDN!

• test-doc-blocks - Test AsciiDoc and CommonMark code blocks found in articles and docstrings (meta, right?)

Have an update? Let us know!

Versioning

Test-doc-block versioning scheme is: major.minor.release-test-qualifier

• major increments when the API has been broken - something, as a rule, we’d like to avoid.

• minor increments to convey significant new features have been added.

• release starting with v1.1, the test-doc-blocks release count over the life of test-doc-blocks.

• test-qualifier is absent for stable releases. Can be alpha, beta, rc1, etc.

People

Contributors

Current Maintainers

License

Copyright © 2025 Lee Read, all rights reserved.

Distributed under the EPL License, same as Clojure. See LICENSE.

Based on concepts in @seancorfield’s readme, which is distributed under EPL v1.0 or later.