Doctests in Lino¶
- tested document¶
A documentation page that contain blocks of Python code marked by a
>>>in the beginning of each line, and which is getting tested using Python's doctest command as part of a test suite.
doctest command extracts code snippets from any text file, executes
them checks whether their output is the same as the one displayed in the
When you want to use
doctest for testing Django code, you need to specify
a Django settings module. Here is an example of how you do that:
>>> import lino >>> lino.startup('lino_book.projects.min1.settings') >>> from lino.api.doctest import *
Yes, this is one of the important reasons why we have demo projects. The Developer Guide repository contains over 1000 documents, and many of them (actually about 176) contain doctest snippets.
Most tested documents use the database of some demo project. When your
developer environment is installed, you can re-play
the instructions on such pages interactively in a Django
on the project they use.
They require of course that the demo project has been populated
inv prep, not on a temporary test database as the Django
test runner creates it.
The advantage of this method (compared to using the Django test runner) is that they don't need to populate the database (load the demo fixtures) for each test run. A limitation of this method is of course that they may not modify the database. That's why we sometimes call them static or passive. They just observe whether everything looks as expected. When you want to test something that modifies the database, you don't write a tested document but a Django test case.
The test suite of a repository with tested documents has a file
test_docs.py in its
tests directory, which calls
atelier.test.make_docs_suite() to automatically create a unit test for
every document in the doctree. A simple
test_docs.py file looks like
from atelier.test import make_docs_suite def load_tests(loader, standard_tests, pattern): suite = make_docs_suite("docs") return suite
The initialization code usually imports and calls
imports everything (
*) from the
lino.api.doctest module (which
contains a selection of the most frequently used commands used in doctests).