How to Make Doctests Easy in Python with Gitpod and VS Code
If you're writing doctests in Python using Gitpod or VS Code, you don’t need much to get started. Python’s built-in doctest module lets you write examples in your function’s docstring using the familiar >>> prompt, and then run those examples as tests. This is great for small, focused functions or when you want your documentation to double as lightweight tests.
As your examples grow or get more complex, maintaining doctests can get tedious. To make things easier, try using the autoDocstring extension in VS Code. It won’t generate doctests for you, but it does provide a helpful template for docstrings, so you don’t have to type out the formatting every time. Good syntax highlighting also helps make the >>> prompts and expected outputs easier to read.
For running doctests, I recommend using pytest instead of the standard doctest runner. With pytest, you get clearer output, better error handling, and the ability to run both doctests and regular unit tests together. Just install pytest (pip install pytest) and run your tests with pytest --doctest-modules. This command will find and run all doctests in your Python files, making the process smoother than using python -m doctest file.py.
If you need more advanced features—like approximate comparisons for floating-point numbers or skipping certain tests—check out pytest-doctestplus. It builds on top of doctest and adds useful options, especially for scientific or data-heavy projects. Although it’s developed by the Astropy community, it works well in any Python project.
Whether you’re working in Gitpod or locally in VS Code, both environments support running tests from the terminal. Just remember to save your files before running tests, as unsaved changes might not be picked up.
In summary, doctests are a simple and effective way to combine documentation and testing. Start with the standard library for minimal setup, and add tools like pytest and helpful VS Code extensions as your needs grow. That said, writing and maintaining doctests can be a little annoying when your examples grow or involve more complex behavior. If you're using Gitpod or VS Code, there are a few things you can do to make life easier. First, use an extension like autoDocstring in VS Code. It won’t write the doctests for you, but it gives you a nice starting template, so you don’t have to keep typing out the docstring formatting manually. Pair that with good syntax highlighting, and the pain of dealing with the >>> and result lines gets smaller. When it comes to actually running the doctests, I usually recommend using pytest instead of the built-in doctest runner. pytest has better output, handles errors more gracefully, and you can run both doctests and traditional unit tests together. All you need to do is install pytest (just pip install pytest), and then run your test suite with pytest --doctest-modules. This will go through all your .py files and run any doctests it finds in docstrings. It feels smoother than running python -m doctest file.py, especially when you're running tests frequently. If you want even more flexibility — for example, support for approximate comparisons with floats or skipping certain tests — you might look into pytest-doctestplus. It’s built on top of doctest and adds some handy features, especially if you're working in a scientific or data-heavy project where outputs can vary a little bit. It's developed by the Astropy community but works great in general Python projects too. All of this works pretty seamlessly whether you're using Gitpod in the browser or working locally in VS Code. Both environments support the terminal well, so running pytest or python -m doctest directly from the command line is easy. Just make sure you save your files before testing — VS Code sometimes doesn’t pick up unsaved changes when you're running tests in the terminal. In the end, doctests are great for lightweight testing and documentation in one place, and you don’t need anything too fancy to use them effectively. Stick with the standard library if you want minimal setup, or layer on pytest and a couple of nice extensions in VS Code to make things smoother.