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…
The article discusses the issue of untested code examples in README files and introduces a tool called mdoctest to address this problem. mdoctest treats fenced code blocks in Markdown as executable tests, running them and checking if the output matches the documented output. It supports any language, runs commands in a persistent shell, and can automatically fix the expected output when changes are made.
The tool also integrates with pre-commit hooks and GitHub Actions to highlight drifts on PR files. The author, Ingrid Owusu, highlights the benefits of using mdoctest, such as making keeping documentation correct a one-liner and integrating it into CI pipelines.
Brief written by urgent.news from Dev.to's own syndicated text. Machine-written — may contain errors; check the original before relying on it.
