This page is about how we do testing beyond the doctests inside the source files. The techniques here are useful during development (when writing them in docstrings are not practical), as well as having potential of being much more thorough than doctests. Furthermore, functional tests have a tendency to grow into paedagogic examples.

Note that Sage does not have a system for putting such extra, complicated and/or exhaustive tests inside Sage in a controlled and sensible way. To run the Sage doctests, see Howto_Documentation.

#Sheets#

There is a folder experiments at the base of the repository. This contains .sheet files. These are clear-text variants of the Sage Notebook documents, containing blocks of Sage experimentation code.

These blocks are syntactically separated by lines beginning with ### followed by a short description. The idea is that such blocks, one by one, can be evaluated in a Sage shell and one can then check the output, e.g. using assert statements. In particular, the files are not necessarily meant to be run in their entirety. This makes it a very useful tool for rapidly doing unit-tests, for instance.

#Test sheets and automatic test suite#

All sheets in the /experiments folder whose name begins with test_ should be considered as unit-tests. The blocks in these files should be a type of unit-tests which throws exceptions whenever a test fails. In particular, they shouldn't print anything which needs human verification.

The reason is the low-tech automated test suite in the form of the Sage script /sheet_test.sage. The script is run using

./sage sheet_test.sage

This opens each file experiments/test_*.sheet and runs each block in this file in order. If ever an exception is thrown when evaluating some block, the exception is printed to the terminal together with location information. The remaining blocks of this file are skipped (todo: tell jsrn if it would be more clever to actually continue here). In any case, the script continues with the remaining files.

One can tell the test suite to ignore a block by writing

on the line immediately after the ### which defines the block.

#Working with sheet files#

On my (jsrn) setup, working with such "sheet" files is very practical. I run Sage from within Emacs, and using the sage-mode package, I can send an entire block of code to it using a keyboard shortcut (C-Enter on my machine): if I have the cursor in some sheet file, this command will send the block I'm currently standing in (search back and forth for ###) to the Sage shell, and advance the cursor to the next block.

The following in your .emacs should activate all functionality after installing sage-mode:

(setq sage-path "<path-to-sage-dir>")
(setq sage-mode-path "/<some-path>/sage-mode/emacs")
(add-to-list 'load-path sage-mode-path)
(require 'sage "sage")
(require 'sage-view "sage-view")
(require 'sage-blocks "sage-blocks")
(setq sage-view-anti-aliasing-level 4
      sage-view-scale 1.0
      sage-view-default-commands t
      sage-view-scale-factor 1)
(add-hook 'sage-startup-after-prompt-hook 'sage-view)
(setq sage-command (cl-concatenate 'string sage-path "/sage"))
(sage-blocks-default-keybindings)

The blocks-functionality is in sage-blocks. Other shortcuts for operating (e.g. moving block-by-block) are listed in the source file.

David is running a similar setup for gVim using vim-ipython. Ask him about the setup if interested.