Initial commit.
[qa-tools:testrunner-lite.git] / doc / mainpage.dox
1 /*! \mainpage testrunner-lite Reference Documentation
2
3 \section intro_sec Introduction
4
5 testrunner-lite  is  a tool for executing test commands. 
6 It is designed to be a lightweight wrapper for various test harnesses. The tool is driven by input XML file containing the test definitions (suite, set, case, step). Tests are executed as instructed in the input XML file and the  output
7 is written to result XML or text file.
8
9 @li @ref install
10
11 @li @ref opt_page
12
13 @li @ref main_mod_page
14
15 \page install Installation
16
17 The tool can be compiled into debian packages with 
18 \code dpkg-buildpackage \endcode and installed with \code dpkg -i testrunner-lite_<version>_<architecture>.deb \endcode .
19
20 \page opt_page Usage
21
22 The program is excuted from commandline 
23 \verbatim /usr/bin/testrunner-lite [options]
24 \endverbatim
25 \section opts Options
26 \subsection opt_help  -h,  --help
27 Display short help and exit
28
29 \subsection opt_file -f FILE,  --file FILE
30 Input file with test definitions in XML (required)
31
32 \subsection opt_ofile -o FILE,  --output FILE
33 Output file format; FORMAT can be xml or text (Default xml)
34
35 \subsection opt_verbose -v, -vv,  --verbose[={INFO|DEBUG}]
36 Enable  verbosity mode; -v and --verbose=INFO are equivalent outputting INFO, 
37 ERROR and WARNING messages. Similarly -vv and --verbose=DEBUG are equivalent, 
38 outputting also debug messages. Default behaviour is silent mode.
39
40 \subsection log_opt -L URL,  --logger=URL
41 Remote HTTP logger. Log messages are sent to given URL in a HTTP POST message. 
42 URL format is [http://]host[:port][/path/], where host  may be a hostname or 
43 an IPv4 address.
44
45 \subsection opt_auto -a,  --automatic
46 Enable only automatic tests to be executed
47
48 \subsection opt_syslog       -S,  --syslog
49 Enable logging to syslog.
50
51 \subsection opt_manual       -m,  --manual
52 Enable only manual tests to be executed
53
54 \subsection opt_ci -c,  --ci
55 Disable validation of test definition against schema
56
57 \subsection opt_semantic       -s,  --semantic
58 Enable validation of test definition against stricter (semantics) schema
59
60 \subsection opt_valonly -A,  --validate-only
61 Do only input xml validation, do not execute tests
62
63 \subsection opt_nohwinfo -H,  --no-hwinfo
64 Do not try to obtain hardware information
65
66 \subsection opt_target  -t [USER@]ADDRESS, --target=[USER@]ADDRESS
67 Enable host-based testing. If given, commands are executed from test control 
68 PC (host) side. ADDRESS is the ipv4 adress of the system under test.
69
70
71 \subsection filt_opts Filtering options  
72
73 Filtering options allow selecting which tests are to be executed. Filtering options are given as a string. String may contain one or more filter entries. Format of each entry is 'filtername=values' where 'filtername' typically corresponds to an attribute in Test Definition XML and 'values' is a string to which the filter should match. Multiple values can be specified if separated by comma (without extra space). A value containing space must be enclosed in double quotes (""). Current list of forbidden characters in values is as follows: Single quote ('), double quote ("), is-equal-to sign (=), comma (,).
74
75 How filtering is carried out: Before processing the filter options, all tests are active by default. Filters can only deactivate tests: If filter value does not match with the value of the corresponding attribute, the test is disabled. Each filter entry is applied for all the active tests in the test package, one after another, in the given order. Filtering is always carried out at the lowest level of the "suite-set-case-step" hierarchy where the corresponding attribute can be defined. Note that some attributes may inherit the value from the upper level. Please refer to Test Definition XML for details.
76
77 If 'filtername' is prefixed with dash (-), the filter behaviour is reversed: those tests for which the filter value does match, are disabled.
78
79 'filtername' can be any of the following:
80 @li feature
81 @li requirement
82 @li testset
83 @li type
84 @li testcase
85
86 The following example does the following: First it disables all test cases except those with attribute type='Integration'. Next, a test case named as Bad Test is disabled. The tests left active will be executed.
87 \code
88 testrunner-lite -f tests.xml -o ~/results -l 'type=Integration -testcase="Bad Test"'
89 \endcode
90 The following example executes test cases that specify the requirement attribute with a value containing at least one of the following strings: '50001', '50002', '50003'.
91 \code
92 testrunner-lite -f tests.xml -o ~/results -l 'requirement=50001,50002,50003'
93 \endcode
94
95 \section manual_exec_sec Manual Test Cases
96
97 It is also possible to execute manual test cases using testrunner-lite, as defined in Test Definition XML.
98
99 In case manual test case is encountered during execution, testrunner-lite will go through the defined test steps and ask user whether the step is passed or failed. The test case will terminate at the first failure, otherwise every step defined will be executed. After the test case is done, user has the option to enter additional comments.
100
101 Example output when running manual case:
102 \verbatim
103 [INFO] 15:15:53 Starting test case: ExampleTestCase
104 --- Execute test step ---
105 Description:
106 Open calculator. Expected result: calculator opens up.
107
108 Please enter the result ([P/p]ass or [F/f]ail):
109 P
110
111 --- Execute test step ---
112 Description:
113 Stop calculator
114
115 Please enter the result ([P/p]ass or [F/f]ail):
116 P
117
118 --- Test steps executed, case is PASSED ---
119 Please enter additional comments (ENTER to finish):
120 Execution was slow.
121
122 [INFO] 15:16:41 Finished test case. Result: PASS
123 \endverbatim
124
125
126 \page main_mod_page Main Modules
127 \section main_mod Main Modules
128
129 Following gives short introduction to main modules of testrunner-lite. To give
130 better understanding of the program flow.
131
132 \subsection main Main
133
134 File \ref main.c contains basic commandline parsing and the high level logic of execution.
135
136 \subsection test_def Test definition parser
137
138 The test definition parsing is done in \ref testdefinitionparser.c. The data is saved to data structures defined in \ref testdefinitiondatatypes.h as the parsing progresses. File \ref testdefinitiondatatypes.c contains routines for intialization and cleanup of the test definition data types.
139
140 \subsection execution Executor
141
142 The executor module (\ref executor.c) takes care of test step execution. File 
143 \ref remote_executor.c provides support for host based testing, where the test
144 steps are executed in a remote host over ssh. Manual test steps are handled 
145 in \ref manual_executor.c.
146
147 \subsection log Logger
148
149 The logger module \ref log.c provides routines for logging to stdout or to 
150 remote location with http POST method.
151
152 \subsection test_re Test result writer
153
154 Test results are written to text or xml writer in \ref testresultlogger.c.
155 */
156