Additional doctest caveats

Doctests have some additional disadvantages that we haven't necessarily run into or noticed yet. Some of these are just things we need to watch out for if we want to make sure our doctests will work properly in a wide variety of environments and as code surrounding our code changes. Others are more serious issues that are most easily solved by switching to unit tests instead of doctests for at least the affected tests. In this section, we will list many of the additional doctest issues to watch out for, and give guidance on what to do to avoid or overcome them.

Beware of environmental dependence

It is very easy for doctests to be unintentionally dependent on implementation details of code other than the code that is actually being tested. We have some of this already in the save override tests, though we have not tripped over it yet. The dependence we have is actually a very specific form of environmental dependence—database dependence. As database dependence is...