10. qmtest run

10.1. Summary

Run tests or test suites.

10.2. Synopsis

qmtest run [ option ...] [ test-name | suite-name ...]

10.3. Description

The qmtest run command runs tests and displays the results. If no test or suite names are specified, QMTest runs all of the tests in the test database. If test or suite names are specified, only those tests or suites are run. Tests listed more than once (directly or by inclusion in a test suite) are run only once.

The run command accepts these options:

-a name=value , --annotate name=value

Annotate the test run by inserting the named annotation name with the value value into all result streams.

This option may be specified multiple times.

-c name=value , --context name=value

Add a property to the test execution context. The name of the property is name, and its value is set to the string value.

This option may be specified multiple times.

-C file, --load-context file

Read properties for the test execution context from the file file.

The file should be a text file with one context property on each line, in the format name=value. Leading and trailing whitespace on each line are ignored. Also, blank lines and lines that begin with "#" (a hash mark) are ignored as comments.

This option may be specified more than once, and used in conjunction with the --context option. All of the context properties specified are added to the eventual context. If a property is set more than once, the last value provided is the one used.

If this option is not specified, but a file named context exists in the current directory, that file is read. The properties specified in this file are processed first; the values in this file can be overridden by subsequent uses of the --context option on the command line.

-f format, --format format

Control the format used when displaying results. The format specified must be one of full, brief, stats, batch, or none. The brief format is the default if QMTest was invoked interactively; the batch format is the default otherwise. In the full format, QMTest displays any annotations provided in test results. In the brief mode only the causes of failures are shown; detailed annotations are not shown. In the stats format, no details about failing tests are displayed; only statistics showing the number of passing and failing tests are displayed. In the batch mode, the summary is displayed first, followed by detailed results for tests with unexpected outcomes. In the none mode, no results are displayed, but a results file is still created, unless the --no-output option is also provided.

-j count, --concurrency count

Run tests in multiple count concurrent processes on the local computer. On multiprocessor machines, the processes may be scheduled to run in parallel on different processors. QMTest automatically collects results from the processes and presents combines test results and summary. By default, one process is used.

This option may not be combined with the --targets (-T) option.

--no-output

Do not produce a test results file.

-o file, --output file

Write full test results to file, in QMTest's machine-readable file format. Use a "-" (a hyphen) to write results to the standard output. If neither this option nor --no-output is specified, the results are written to the file named results.qmr in the current directory.

-O file, --outcomes file

Treat file as a set of expected outcomes. The file is usually a results file created either by using the qmtest run or by saving results in the graphical user interface. If file does not appear to be such a file, it is interpreted as an extension descriptor, as described in Section 2, “qmtest create. QMTest will expect the results of the current test run to match those specified in the file and will highlight differences from those results.

--random

Run the tests in a random order.

This option can be used to find hidden dependencies between tests in the testsuite. (You may not notice the dependencies if you always run the tests in the same order.)

--rerun file

Rerun only those tests that had unexpected outcomes.

The tests run are determined as follows. QMTest starts with all of the tests specified on the command line, or, if no tests are explicitly specified, all of the tests in the database. If no expectations file is specified (see the description of the --outcomes option), then all tests that passed in the results file indicated by the --rerun option are removed form the set of eligible tests. If an expectations file is specified, then the tests removed are tests whose outcome in the results file indicated by the --rerun option is the same as in the expectations file.

The --rerun provides a simple way of rerunning failing tests. If you run your tests and notice failures, you might try to fix those failing tests. Then, you can rerun the failing tests to see if you succeeded by using the --rerun option.

--result-stream descriptor

Specify an additional output result stream. The descriptor is in the format described in Section 2, “qmtest create.

--seed integer

If the --random is used, QMTest randomizes the order in which tests are run, subject to the constraints described in Section 1.3, “Ordering and Dependencies”. By default, the random number generator is seeded using the system time.

For debugging purposes, it is sometimes necessary to obtain a reproducible sequence of tests. Use the --seed option to specify the seed for the random number generator.

Note that even with the same random number seed, if tests are run in parallel, scheduling uncertainty may still produce variation in the order in which tests are run.

-T file, --targets file

Use targets specified in target specification file file. If this option is not present, the QMTest/targets in the test database directory will be used. If that file is not present, the tests will be run in serial on the local machine.