Some tests take a lot of work to set up. For example, a database test that checks the result of SQL queries may require that the database first be populated with a substantial number of records. If there are many tests that all use the same set of records, it would be wasteful to set up the database for each test. It would be more efficient to set up the database once, run all of the tests, and then remove the databases upon completion.

You can use a resource to gain this efficiency. If a test depends on a resource, QMTest will ensure that the resource is available before the test runs. Once all tests that depend on the resource have been run QMTest will destroy the resource.

Just as every test is an instance of a test class, every resource is an instance of a resource class. The resource class explains how to set up the resource and how to clean up when it is no longer needed. The arguments to the resource class are what make two instances of the same resource class different from each other. For example, in the case of a resource that sets up a database, the records to place in the database might be given as arguments. Every resource has a name, using the same format that is used for tests.

Under some circumstances (such as running tests on multiple targets at once), QMTest may create more than one instance of the same resource. Therefore, you should never depend on there being only one instance of a resource. In addition, if you have asked QMTest to run tests concurrently, two tests may access the same resource at the same time. You can, however, be assured that there will be only one instance of a particular resource on a particular target at any one time.

Tests have limited access to the resources on which they depend. A resource may place additional information into the context (Section 6, “Context”) that is visible to the test. However, the actual resource object itself is not available to tests. (The reason for this limitiation is that for a target consisting of multiple processes, the resource object may not be located in the same process as the test that depends upon it.)

Setting up or cleaning up a resource produces a result, just like those produced for tests. QMTest will display these results in its summary output and record them in the results file.

Building on the previous example of a CompilationTest, let us consider a situation where some test application should be run multiple times with different arguments. The test application, however, needs to be compiled first. In order to avoid recompiling the application for each test, you can create a resource that compiles the application once. Then, tests that depend on this resource can assume that the application has already been built. The following commands:

> qmtest create --id applet resource
    compilation_test.CompiledResource(executable="applet", source_files="['/path/to/applet.cc']")
> qmtest create --id run_applet_0 test
    compilation_test.ExecutableTest(args="['0']", resources="['applet']")
> qmtest create --id run_applet_1 test
    compilation_test.ExecutableTest(args="['1']", resources="['applet']")
    

create a resource (named "applet") for the application and two tests ("run_applet_0" and "run_applet_1"), both of which make use of "applet", but which pass it different command-line options.

> qmtest run -c CompilationTest.compiler_path=g++ run_applet_0 run_applet_1
--- TEST RESULTS -------------------------------------------------------------

  Setup applet                                  : PASS

  run_applet_0                                  : PASS

  run_applet_1                                  : PASS

  Cleanup applet                                : PASS