Literate testing with pytest-bashdoctest helps keep your Bash examples up-to-date
October 11, 2025 | View Comments
"Examples are priceless. Examples that don't work are worse than worthless." -- Tim Peters
I recently built an extensive API at work using FastAPI. One of the most imporant parts of creating an API is of course presenting it to users. And while FastAPI's automatic generation of Swagger docs is of course great; it ties into type annotations and can be extended to include examples; there's maybe two fundamental limitations with serving your API's documentation like this:
- it's not as accessible as your README.md or your MkDocs/Docusaurus/Sphinx docs
- examples and API docstrings can easily drift from reality (unless you make the effort to test them)
Why doctest for Bash?
pytest-bashdoctest is a package that I recently published that tries to fix that. In the spirit of Python's doctest it allows you to execute Bash examples in your documentation and automatically check them against the output in your documentation. This allows you to make sure that your examples are always up-to-date and working. These tests are also easy to write: write your curl calls, execute them in your terminal, then paste the results back into your documentation.
Example: Keeping a curl block honest
Here's an example from pytest-bashdoctest's own README.md:
```bash
$ curl -s "https://api.github.com/users/dnouri"
{
"login": "dnouri",
...
"avatar_url": "https://avatars.githubusercontent.com/u/...?v=4",
...
"created_at": "2009-...-...T...Z",
...
}
```
Notice how the use of ellipsis (...), same as with doctest, allows you to ignore parts of the output that are variable or you're not interested in.
The idea of pytest-bashdoctest of course extends to documenting your CLI as well.
Running your tests is as easy as:
pytest --bashdoctest README.md -v
Who is this for?
pytest-bashdoctest is for anyone maintaining API or CLI documentation that includes real commands:
- API and platform teams who publish curl examples that must not drift.
- CLI developers who want README examples to stay correct.
- Docs-as-code workflows using MkDocs, Docusaurus, or Sphinx, where Markdown lives next to code.
If you already use pytest in your CI pipeline, adding doctest-like coverage for Bash examples takes only a few minutes.
Running in CI and more
Check out the documentation for more details on how to configure pytest-bashdoctest, how to use a pytest fixture to set up the environment before you execute these tests, and the package's own CI configuration for how you might run this as part of your CI pipeline.
Warning
pytest-bashdoctest executes shell commands (shell=True). Prefer running it in CI against trusted docs. Keep examples non-destructive and fast; interactive commands will hang; default timeout is =30s.