Subsections


4. Testing

Use sage -t <file> to test that the examples in <file> behave exactly as claimed. This will test files of the following types: .py .pyx .sage .tex. See Section 3.3 for a discussion of how to include examples in documentation strings and what conventions to follow.


4.1 Testing .py, .pyx and .sage files

Run sage -t <filename.py> to test that all code examples in filename.py. Similar remarks apply to .sage and .pyx files.

When you run sage -t <filename.py>, SAGE makes a copy of <filename.py> with all the sage prompts replaced by >>>, then uses the standard Python doctest framework to test the documentation. More precisely, the Python script local/bin/sage-doctest implements documentation testing. It does the following when asked to test a file foo.py or foo.sage.

  1. Creates the directory .doctest if it doesn't exist and the file .doctest/foo.py.

  2. The file .doctest/foo.py contains functions for each docstring in foo.py, but with all SAGE preparsing applied and with from sage.all import * at the top. The function documentation is thus standard Python with >>> prompts.

  3. sage-doctest then runs SAGE's Python interpreter on .doctest/foo.py.

Note: Note that line numbers in the errors you might see apply to the file .doctest/foo.py, not to the original file foo.py! If you get errors, feel free to inspect .doctest/foo.py; it is never automatically deleted by SAGE.

Your file passes these tests if the code in it will run when entered at the sage: prompt with no special imports. Thus users are guaranteed to be able to exactly copy code out of the examples you write for the documentation and have them work.

4.2 Testing LaTeX Documentation

Run sage -t <filename.tex> to test the examples in verbatim environments in LaTeX documentation. Put %skip on the line right before a verbatim environment to have that example skipped when testing the file.

SAGE creates a file .doctest/filename.py and tests it just as for .py, .pyx and .sage files. In order to skip testing of a block of code in a verbatim environment, put the LaTeX comment %skip on the previous line.

One difference is that in LaTeX files one often inserts explanatory texts between different verbatim environments. To link together verbatim environments use the %link comment. For example4.1

    \begin{verbatim}
    sage: a = 1
    \end{verbatim_}%link

    Next we add 1 to \code{a}.
    %link
    \begin{verbatim}
    sage: 1 + a
    2
    \end{verbatim_}

See $SAGE_ROOT/doc/tut/tut.tex for many examples of how to include automated testing in LaTeX documentation for SAGE.



Footnotes

... example4.1
I have changed verbatim to verbatim0 here since I don't know how to include endverbatim in a verbatim environment.
See About this document... for information on suggesting changes.