waf_unit_test

Unit testing system for C/C++/D and interpreted languages providing test execution:

• in parallel, by using waf -j

• partial (only the tests that have changed) or full (by using waf --alltests)

The tests are declared by adding the test feature to programs:

def options(opt):
        opt.load('compiler_cxx waf_unit_test')
def configure(conf):
        conf.load('compiler_cxx waf_unit_test')
def build(bld):
        bld(features='cxx cxxprogram test', source='main.cpp', target='app')
        # or
        bld.program(features='test', source='main2.cpp', target='app2')

When the build is executed, the program ‘test’ will be built and executed without arguments. The success/failure is detected by looking at the return code. The status and the standard output/error are stored on the build context.

The results can be displayed by registering a callback function. Here is how to call the predefined callback:

def build(bld):
        bld(features='cxx cxxprogram test', source='main.c', target='app')
        from waflib.Tools import waf_unit_test
        bld.add_post_fun(waf_unit_test.summary)

By passing –dump-test-scripts the build outputs corresponding python files (with extension _run.py) that are useful for debugging purposes.

waflib.Tools.waf_unit_test.feature(*k)

Decorator that registers a task generator method that will be executed when the object attribute feature contains the corresponding key(s):

from waflib.TaskGen import feature
@feature('myfeature')
def myfunction(self):
        print('that is my feature!')
def build(bld):
        bld(features='myfeature')

Parameters

k (list of string) – feature names

waflib.Tools.waf_unit_test.after_method(*k)

Decorator that registers a task generator method which will be executed after the functions of given name(s):

from waflib.TaskGen import feature, after
@feature('myfeature')
@after_method('fun2')
def fun1(self):
        print('feature 1!')
@feature('myfeature')
def fun2(self):
        print('feature 2!')
def build(bld):
        bld(features='myfeature')

Parameters

k (list of string) – method names

waflib.Tools.waf_unit_test.taskgen_method(func)

Decorator that registers method as a task generator method. The function must accept a task generator as first parameter:

from waflib.TaskGen import taskgen_method
@taskgen_method
def mymethod(self):
        pass

Parameters

func (function) – task generator method to add

Return type

function

waflib.Tools.waf_unit_test.handle_ut_cwd(self, key)

Task generator method

Task generator method, used internally to limit code duplication. This method may disappear anytime.

waflib.Tools.waf_unit_test.make_interpreted_test(self)

Task generator method

Create interpreted unit tests.

feature

test_scripts

waflib.Tools.waf_unit_test.make_test(self)

Task generator method

Create the unit test task. There can be only one unit test task by task generator.

feature

test

waflib.Tools.waf_unit_test.add_test_results(self, tup)

Task generator method

Override and return tup[1] to interrupt the build immediately if a test does not run

class waflib.Tools.waf_unit_test.utest(*k, **kw)

Execute a unit test

color = 'PINK'

Color for the console display, see waflib.Logs.colors_lst

after = ['vnum', 'inst']

The instances of this class are executed after the instances of classes whose names are in this list

vars = ['UT_DEPS']

ConfigSet variables that should trigger a rebuild (class attribute used for waflib.Task.Task.sig_vars())

runnable_status()

Always execute the task if waf –alltests was used or no tests if waf --notests was used

get_test_env()

In general, tests may require any library built anywhere in the project. Override this method if fewer paths are needed

post_run()

Update the cache files (executed by threads). Override in subclasses.

run()

Execute the test. The execution is always successful, and the results are stored on self.generator.bld.utest_results for postprocessing.

Override add_test_results to interrupt the build

exec_command(cmd, **kw)

Wrapper for waflib.Context.Context.exec_command(). This version set the current working directory (build.variant_dir), applies PATH settings (if self.env.PATH is provided), and can run long commands through a temporary @argfile.

Parameters

cmd (list of string (best) or string (process will use a shell)) – process command to execute

Returns

the return code

Return type

int

Optional parameters:

1. cwd: current working directory (Node or string)

2. stdout: set to None to prevent waf from capturing the process standard output

3. stderr: set to None to prevent waf from capturing the process standard error

4. timeout: timeout value (Python 3)

get_cwd()

Returns

current working directory

Return type

waflib.Node.Node

hasrun

generator

env

waflib.ConfigSet.ConfigSet object (make sure to provide one)

inputs

List of input nodes, which represent the files used by the task instance

outputs

List of output nodes, which represent the files created by the task instance

dep_nodes

List of additional nodes to depend on

run_after

Set of tasks that must be executed before this one

hcode = b'\tdef run(self):\n\t\t"""\n\t\tExecute the test. The execution is always successful, and the results\n\t\tare stored on ``self.generator.bld.utest_results`` for postprocessing.\n\n\t\tOverride ``add_test_results`` to interrupt the build\n\t\t"""\n\t\tif hasattr(self.generator, \'ut_run\'):\n\t\t\treturn self.generator.ut_run(self)\n\n\t\tself.ut_exec = getattr(self.generator, \'ut_exec\', [self.inputs[0].abspath()])\n\t\tut_cmd = getattr(self.generator, \'ut_cmd\', False)\n\t\tif ut_cmd:\n\t\t\tself.ut_exec = shlex.split(ut_cmd % Utils.shell_escape(self.ut_exec))\n\n\t\treturn self.exec_command(self.ut_exec)\n'

String representing an additional hash for the class representation

sig_explicit_deps()

Used by waflib.Task.Task.signature(); it hashes waflib.Task.Task.inputs and waflib.Task.Task.dep_nodes signatures.

waflib.Tools.waf_unit_test.summary(bld)

Display an execution summary:

def build(bld):
        bld(features='cxx cxxprogram test', source='main.c', target='app')
        from waflib.Tools import waf_unit_test
        bld.add_post_fun(waf_unit_test.summary)

waflib.Tools.waf_unit_test.set_exit_code(bld)

If any of the tests fail waf will exit with that exit code. This is useful if you have an automated build system which need to report on errors from the tests. You may use it like this:

def build(bld):

bld(features=’cxx cxxprogram test’, source=’main.c’, target=’app’) from waflib.Tools import waf_unit_test bld.add_post_fun(waf_unit_test.set_exit_code)

waflib.Tools.waf_unit_test.options(opt)

Provide the --alltests, --notests and --testcmd command-line options.

Features defined in this module:

• test

• test_scripts