# Chapter 20: Unit testing with Leo

This chapter describes how you can execute Python unit test from within Leo outlines.

Contents

- Chapter 20: Unit testing with Leo
  - Overview
  - Using @test nodes
  - Using @suite nodes
  - How the unit test commands work

## Overview

Leo's unit test commands run the unit tests created by @test and @suite nodes. run-unit-tests and run-unit-tests-locally run all unit tests in the presently selected part of the Leo outline; run-all-unit-tests and run-all-unit-tests-locally run all unit tests in the entire Leo outline.

You must be running Leo from a console to see the output the unit tests. Leo's unit test commands run all the unit tests using the standard unittest text test runner, and the output of the unit tests appears in the console.

test/unitTest.leo contains many examples of using @test and @suite nodes.

## Using @test nodes

@test nodes are nodes whose headlines start with @test. The unit test commands convert the body text of @test nodes into a unit test automatically. That is, Leo's unit test commands automatically create a unittest.TestCase instances which run the body text of the @test node. For example, let us consider one of Leo's actual unit tests. The headline is:

    @test consistency of back/next links

The body text is:

    if g.unitTesting:
        c,p = g.getTestVars() # Optional: prevents pychecker warnings.
        for p in c.allNodes_iter():
            back = p.back()
            next = p.next()
            if back: assert(back.getNext() == p)
            if next: assert(next.getBack() == p)

When either of Leo's unit test commands finds this @test node the command will run a unit test equivalent to the following:

    import leoGlobals as g

    class aTestCase (unittest.TestCase):
        def shortDescription():
            return '@test consistency of back/next links'
        def runTest():
            c,p = g.getTestVars()
            for p in c.allNodes_iter():
                back = p.back()
                next = p.next()
                if back: assert(back.getNext() == p)
                if next: assert(next.getBack() == p)

As you can see, using @test nodes saves a lot of typing:

- You don't have to define a subclass of unittest.TestCase.
- Within your unit test, the c, g and p variables are predefined, just like in Leo scripts.
- The entire headline of the @test node becomes the short description of the unit test.

Important note: notice that the first line of the body text is a guard line:

    if g.unitTesting:

This guard line is needed because this particular @test node is contained in the file leoNodes.py. @test nodes that appear outside of Python source files do not need guard lines. The guard line prevents the unit testing code from being executed when Python imports the leoNodes module; the g.unitTesting variable is True only while running unit tests.

Note: Leo predefines the c, g, and p variables in @test and @suite nodes, just like in other scripts. Thus, the line:

    c,p = g.getTestVars()

is not needed. However, it prevents pychecker warnings that c and p are undefined.

## Using @suite nodes

@suite nodes are nodes whose headlines start with @suite. @suite nodes allow you to create and run custom subclasses of unittest.TestCase.

Leo's test commands assume that the body of an suite node is a script that creates a suite of tests and places that suite in g.app.scriptDict['suite']. Something like this:

    if g.unitTesting:
        __pychecker__ = '--no-reimport' # Prevents pychecker complaint.
        import unittest
        c,p = g.getTestVars() # Optional.
        suite = unittest.makeSuite(unittest.TestCase)
        << add one or more tests (instances of unittest.TestCase) to suite >>
        g.app.scriptDict['suite'] = suite

Note: as in @test nodes, the guard line, 'if unitTesting:', is needed only if the @suite node appears in a Python source file.

Leo's test commands first execute the script and then run suite in g.app.scriptDict.get('suite') using the standard unittest text runner.

You can organize the script in an @suite nodes just as usual using @others, section references, etc. For example:

    if g.unitTesting:
        __pychecker__ = '--no-reimport'
        import unittest
        c,p = g.getTestVars() # Optional.
        # children define test1,test2..., subclasses of unittest.TestCase.
        @others
        suite = unittest.makeSuite(unittest.TestCase)
        for test in (test1,test2,test3,test4):
            suite.addTest(test)
        g.app.scriptDict['suite'] = suite

## How the unit test commands work

The run-all-unit-tests-locally and run-unit-tests-locally commands run unit tests in the process that is running Leo. These commands can change the outline containing the unit tests.

The run-all-unit-tests and run-unit-tests commands run all tests in a separate process, so unit tests can never have any side effects. These commands never changes the outline from which the tests were run. These commands do the following:

1. Copy all @test, @suite and @unit-test nodes (including their descendants) to the file test/dynamicUnitTest.leo.
2. Run test/leoDynamicTest.py in a separate process.
   - leoDynamicTest.py opens dynamicUnitTest.leo with the leoBridge module. Thus, all unit tests get run with the nullGui in effect.
   - After opening dynamicUnitTest.leo, leoDynamicTest.py runs all unit tests by executing the leoTest.doTests function.
   - The leoTests.doTests function searches for @test and @suite nodes and processes them generally as described above. The details are a bit different from as described, but they usually don't matter. If you really care, see the source code for leoTests.doTests.