Your README's code examples are untested — here's how I test mine in any language
Your README is full of code — shell commands, config snippets, >>> sessions, example output. And unlike the rest of your codebase, none of it is tested. A flag gets renamed, an output format changes, a default shifts, and your examples rot silently. The worst part: the first thing a new user does is copy your first example and run it — straight into something broken. I maintain a small CLI called…
Your README contains many examples, such as shell commands, config snippets, and session outputs. However, none of these examples are tested. If a flag gets renamed, an output format changes, or a default shifts, your examples will become outdated. The worst part is that a new user will often be the first to copy your first example and run it, leading to broken functionality.
To address this issue, I created a tool called mdoctest. It treats fenced code blocks in your Markdown as executable tests, ensuring that the output still matches what you documented. This tool is not limited to Python and can run commands in a persistent shell, preserving environment variables and functions across a session. mdoctest also supports backslash-continued commands, here-documents, and real-world noise like timestamps and temporary file paths.
The tool can automatically fix outdated examples by re-running commands and rewriting the expected output in place. It provides a pre-commit hook and a GitHub Action to handle real-world noise and ensure that your examples remain up-to-date.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
