Documentation/Nightly/Developers/Tutorials/SelfTestModule

Goal

After review and work by the slicer community, a framework is in place that supports Built In Self Tests for slicer.

Important features include:

• Tests are available as part of the binary distributions of slicer, so users can confirm correct behavior on their systems
• The same tests are run as part of the nightly test process and submitted to the slicer dashboard.
• Developers can efficiently develop the tests by reloading python scripts without needing to exit slicer.

This page provides an overview of the implementation and use of these scripts.

The approach described here can be used in a number of ways:

• When developing a new scripted module, you can create a test script at the same time. This way you can use the script to help you test the code as you develop it (by reloading and testing as you write the code without even exiting slicer) and also verify that your code still works as you refactor and improve the code. Plus, you can easily test the code on multiple platforms without a lot of tedious clicking to reload data.
• Self Tests of the core slicer functionality can be used equally in build-time and run-time scenarios.
• Any type of module or extension can also include self tests (and should!).

Caveats

This project is actively evolving and is being worked on and some of the implementation details will change in future versions.

These instructions assume you are working with a local build of slicer.

Creating the Skeleton

Use the ModuleWizard

Start by using the module wizard to create a new scripted module.

Give the module a descriptive name based on the functionality you intend to test. If the module is created to recreated the steps described in a bug report, append the bug report name to the end of the test. For example, one test is sceneImport2428.py which tests issue #2428.

At first, put the new module in a dedicated directory:

cd <Slicer source dir>
./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/ScriptedLoadableExtensionTemplate --target ../NeurosurgeryTutorial NeurosurgeryTutorial

This will create a new extension directory with a skeleton NeurosurgeryTutorial.py file ready to work on.

Edit the new module

In the editor, change a few of the fields:

Change:

   parent.categories = ["Examples"]

to:

   parent.categories = ["Testing.TestCases"]

Also change the contributor names, the acknowledgement text, and any other general fields to customize the module.

Configure Slicer

In slicer, go into the Application Settings->Module Settings and add a path to the NeurosurgeryTutorial directory and restart slicer.

Restart Slicer and Test

When slicer comes back up you should find your module in the Modules->Testing->TestCases menu.

If you click the Reload and Test button, a default test will run and it should pass.

You are now ready to customize this test for your own use.

Test Data

Test data should be uploaded slicer's midas instance. If you need to upload new data, consult the midas documentation to get an account and request access to the NA-MIC community.

Toward the bottom of your python script (in the method test_NeurosurgeryTutorial1) you can see how data is downloaded from midas and loaded into slicer. In the template, a single volume file is downloaded:

   downloads = (
       ('http://slicer.kitware.com/midas3/download?items=5767', 'FA.nrrd', slicer.util.loadVolume),
       )

other self test scripts load multiple datasets and/or scene files.

Writing/Refining the Code

Note that you can click the Reload and Test button as many times as you want and to re-run the test.

Now, you can experiment with changing the code. Add another line to the beginning of the test_NeurosurgeryTutorial1 method like:

self.delayDisplay("My modified test")

Save the file and click Reload and Test. You should see your new message as a dialog and you should also see it printed in the console.

From here, you "only" need to implement the python code that performs your test. For that, you can rely on the python wrappings of Qt, VTK, numpy, etc.

Adding the Result to Slicer

When you are satisfied that your test captures the intended functionality, you can add it to the main repository (or, if you don't have write access, coordinate with a developer who does have write access).

To make this a self test, copy the NeurosurgeryTutorial.py into Applications/SlicerApp/Testing/Python/ and edit the Applications/SlicerApp/Testing/Python/CMakeLists.txt file.

In the SelfTests section, add a line like:

slicer_add_python_unittest(SCRIPT NeurosurgeryTutorial.py)

and add NeurosurgeryTutorial.py to the KIT_PYTHON_SCRIPTS list.

That's it!

Now your test will be run as part of the nightly dashboard process and will be available to users so they can verify that your code is operating as designed on their platform.