6. Context

When you create a test, you choose arguments for the test. The test class uses this information to run the test. However, the test class may sometimes need information that is not available when the test is created. For example, if you are writing compiler tests to verify conformance with the C programming language specification, you do not know the location of the C compiler itself. The C compiler may be installed in different locations on different machines.

A context gives users a way of conveying this kind of information to tests. The context is a set of key/value pairs. The keys are always strings. The values of all context properties provided by the user are strings. In general, all tests in a given use of QMTest will have the same context. However, when a resource is set up, it may place additional information in the context of those tests that depend upon it. The values inserted by the resource may have any type, so long as they can be "pickled" by Python.

All context properties whose names begin with "qmtest." are reserved for use by QMTest. The values inserted by QMTest may have any type. Test and resource classes should not depend on the presence or absence of these properites.

To understand how a context is used during the execution of a test let us start by creating a somewhat less trivial test:

> qmtest create --id compile test 
    compilation_test.CompilationTest(executable="compile", source_files="['/path/to/compile.cc']")"
    

When run, this test will compile /path/to/compile.cc and run the resulting executable. The test passes if compilation succeeds, and the program exit status indicates success.

The compilation_test.CompilationTest test class requires that the compiler be available in the context with the key CompilationTest.compiler_path. You can provide a context variable to QMTest either through a context file or on the command-line using the -c option. For example:

> qmtest run -c CompilationTest.compiler_path=g++ compile
    

will run the test using the g++ compiler, while:

> qmtest run -c CompilationTest.compiler_path=/bin/CC compile
    

will run the test with the /bin/CC compiler.