← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to lib/common_test/doc/src/run_test_chapter.xml

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/common_test/doc/src/run_test_chapter.xml
4
4
<chapter>
5
5
  <header>
6
6
    <copyright>
7
 
      <year>2003</year><year>2009</year>
 
7
      <year>2003</year><year>2011</year>
8
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
9
9
    </copyright>
10
10
    <legalnotice>
13
13
      compliance with the License. You should have received a copy of the
14
14
      Erlang Public License along with this software. If not, it can be
15
15
      retrieved online at http://www.erlang.org/.
16
 
    
 
16
 
17
17
      Software distributed under the License is distributed on an "AS IS"
18
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
19
19
      the License for the specific language governing rights and limitations
20
20
      under the License.
21
 
    
 
21
 
22
22
    </legalnotice>
23
23
 
24
 
    <title>Running Test Suites</title>
 
24
    <title>Running Tests</title>
25
25
    <prepared>Peter Andersson, Kenneth Lundin</prepared>
26
26
    <docno></docno>
27
27
    <date></date>
71
71
 
72
72
    <p>If test suites or help modules include header files stored in other
73
73
      locations than the test directory, you may specify these include directories
74
 
      by means of the <c><![CDATA[-include]]></c> flag with <c><![CDATA[run_test]]></c>, 
 
74
      by means of the <c><![CDATA[-include]]></c> flag with <c><![CDATA[ct_run]]></c>, 
75
75
      or the <c><![CDATA[include]]></c> option with <c><![CDATA[ct:run_test/1]]></c>.
76
76
      In addition to this, an include path may be specified with an OS
77
77
      environment variable; <c><![CDATA[CT_INCLUDE_PATH]]></c>. Example (bash):</p>
93
93
      there instead.</p>
94
94
 
95
95
    <p>It is possible to disable the automatic compilation feature by using the
96
 
      <c><![CDATA[-no_auto_compile]]></c> flag with <c><![CDATA[run_test]]></c>, or
 
96
      <c><![CDATA[-no_auto_compile]]></c> flag with <c><![CDATA[ct_run]]></c>, or
97
97
      the <c><![CDATA[{auto_compile,false}]]></c> option with 
98
98
      <c><![CDATA[ct:run_test/1]]></c>. With automatic compilation
99
99
      disabled, the user is responsible for compiling the test suite modules 
100
 
      (and any help modules) before the test run. Common Test will only verify 
101
 
      that the specified test suites exist before starting the tests.</p> 
 
100
      (and any help modules) before the test run. If the modules can not be loaded
 
101
      from the local file system during startup of Common Test, the user needs to
 
102
      pre-load the modules before starting the test. Common Test will only verify
 
103
      that the specified test suites exist (i.e. that they are, or can be, loaded).
 
104
      This is useful e.g. if the test suites are transferred and loaded as binaries via
 
105
      RPC from a remote node.</p>
102
106
  </section>
103
107
 
 
108
  <marker id="ct_run"></marker>
104
109
  <section>
105
 
    <title>Running tests from the UNIX command line</title>
 
110
    <title>Running tests from the OS command line</title>
106
111
    
107
 
    <p>The script <c>run_test</c> can be used for running tests from
108
 
      the Unix/Linux command line, e.g.
 
112
    <p>The <c>ct_run</c> program can be used for running tests from
 
113
      the OS command line, e.g.
109
114
    </p>
110
115
    <list>
111
 
      <item><c><![CDATA[run_test -config <configfilenames> -dir <dirs>]]></c></item>
112
 
      <item><c><![CDATA[run_test -config <configfilenames> -suite <suiteswithfullpath>]]></c>
113
 
      </item>
114
 
      <item><c><![CDATA[run_test -config <configfilenames> -suite <suitewithfullpath>
 
116
      <item><c><![CDATA[ct_run -config <configfilenames> -dir <dirs>]]></c></item>
 
117
      <item><c><![CDATA[ct_run -config <configfilenames> -suite <suiteswithfullpath>]]></c>
 
118
      </item>
 
119
      <item><c><![CDATA[ct_run -userconfig <callbackmodulename> <configfilenames> -suite <suiteswithfullpath>]]></c>
 
120
      </item>
 
121
      <item><c><![CDATA[ct_run -config <configfilenames> -suite <suitewithfullpath>
115
122
              -group <groupnames> -case <casenames>]]></c></item>
116
123
    </list>
117
124
    <p>Examples:</p>
118
 
    <p><c>$ run_test -config $CFGS/sys1.cfg $CFGS/sys2.cfg -dir $SYS1_TEST $SYS2_TEST</c></p>
119
 
    <p><c>$ run_test -suite $SYS1_TEST/setup_SUITE $SYS2_TEST/config_SUITE</c></p>
120
 
    <p><c>$ run_test -suite $SYS1_TEST/setup_SUITE -case start stop</c></p>
121
 
    <p><c>$ run_test -suite $SYS1_TEST/setup_SUITE -group installation -case start stop</c></p>
 
125
    <p><c>$ ct_run -config $CFGS/sys1.cfg $CFGS/sys2.cfg -dir $SYS1_TEST $SYS2_TEST</c></p>
 
126
    <p><c>$ ct_run -userconfig ct_config_xml $CFGS/sys1.xml $CFGS/sys2.xml -dir $SYS1_TEST $SYS2_TEST</c></p>
 
127
    <p><c>$ ct_run -suite $SYS1_TEST/setup_SUITE $SYS2_TEST/config_SUITE</c></p>
 
128
    <p><c>$ ct_run -suite $SYS1_TEST/setup_SUITE -case start stop</c></p>
 
129
    <p><c>$ ct_run -suite $SYS1_TEST/setup_SUITE -group installation -case start stop</c></p>
122
130
    
123
 
    <p>Other flags that may be used with <c>run_test</c>:</p>
 
131
    <p>Other flags that may be used with <c>ct_run</c>:</p>
124
132
    <list>
125
133
      <item><c><![CDATA[-logdir <dir>]]></c>, specifies where the HTML log files are to be written.</item>
 
134
      <item><c><![CDATA[-label <name_of_test_run>]]></c>, associates the test run with a name that gets printed
 
135
        in the overview HTML log files.</item>
126
136
      <item><c>-refresh_logs</c>, refreshes the top level HTML index files.</item>
127
137
      <item><c>-vts</c>, start web based GUI (see below).</item>
128
138
      <item><c>-shell</c>, start interactive shell mode (see below).</item>
136
146
        <seealso marker="cover_chapter#cover">Code Coverage Analysis</seealso>).</item>
137
147
      <item><c><![CDATA[-event_handler <event_handlers>]]></c>, to install 
138
148
        <seealso marker="event_handler_chapter#event_handling">event handlers</seealso>.</item>
 
149
      <item><c><![CDATA[-event_handler_init <event_handlers>]]></c>, to install
 
150
        <seealso marker="event_handler_chapter#event_handling">event handlers</seealso> including start arguments.</item>
 
151
      <item><c><![CDATA[-ct_hooks <ct_hooks>]]></c>, to install
 
152
        <seealso marker="ct_hooks_chapter#installing">Common Test Hooks</seealso> including start arguments.</item>
139
153
      <item><c><![CDATA[-include]]></c>, specifies include directories (see above).</item>
140
154
      <item><c><![CDATA[-no_auto_compile]]></c>, disables the automatic test suite compilation feature (see above).</item>
 
155
      <item><c><![CDATA[-multiply_timetraps <n>]]></c>, extends <seealso marker="write_test_chapter#timetraps">timetrap
 
156
          timeout</seealso> values.</item>
 
157
      <item><c><![CDATA[-scale_timetraps <bool>]]></c>, enables automatic <seealso marker="write_test_chapter#timetraps">timetrap
 
158
          timeout</seealso> scaling.</item>
141
159
      <item><c><![CDATA[-repeat <n>]]></c>, tells Common Test to repeat the tests n times (see below).</item> 
142
160
      <item><c><![CDATA[-duration <time>]]></c>, tells Common Test to repeat the tests for duration of time (see below).</item> 
143
161
      <item><c><![CDATA[-until <stop_time>]]></c>, tells Common Test to repeat the tests until stop_time (see below).</item> 
152
170
    <note><p>Directories passed to Common Test may have either relative or absolute paths.</p></note>
153
171
 
154
172
    <note><p>Arbitrary start flags to the Erlang Runtime System may also be passed as
155
 
             parameters to <c>run_test</c>. It is, for example, useful to be able to
 
173
             parameters to <c>ct_run</c>. It is, for example, useful to be able to
156
174
             pass directories that should be added to the Erlang code server search path
157
175
             with the <c>-pa</c> or <c>-pz</c> flag. If you have common help- or library 
158
176
             modules for test suites (separately compiled), stored in other directories 
159
177
             than the test suite directories, these help/lib directories are preferrably
160
178
             added to the code path this way. Example:</p>
161
 
          <p><c>$ run_test -dir ./chat_server -logdir ./chat_server/testlogs -pa $PWD/chat_server/ebin</c></p>
 
179
          <p><c>$ ct_run -dir ./chat_server -logdir ./chat_server/testlogs -pa $PWD/chat_server/ebin</c></p>
162
180
          <p>Note how in this example, the absolute path of the <c>chat_server/ebin</c>
163
181
             directory is passed to the code server. This is essential since relative
164
182
             paths are stored by the code server as relative, and Common Test changes 
165
183
             the current working directory of the Erlang Runtime System during the test run!</p>
166
184
    </note>
167
185
    
168
 
    <p>For details on how to generate the <c>run_test</c> script, see the 
 
186
    <p>For more information about the <c>ct_run</c> program, see the
169
187
      <seealso marker="install_chapter#general">Installation</seealso> chapter.
170
188
    </p>
171
189
  </section>
173
191
  <section>
174
192
    <title>Running tests from the Web based GUI</title>
175
193
    
176
 
    <p>The web based GUI, VTS, is started with the <c>run_test</c>
177
 
      script. From the GUI you can load config files, and select
 
194
    <p>The web based GUI, VTS, is started with the <c>ct_run</c>
 
195
      program. From the GUI you can load config files, and select
178
196
      directories, suites and cases to run. You can also state the
179
197
      config files, directories, suites and cases on the command line
180
198
      when starting the web based GUI.
181
199
    </p>
182
200
    
183
201
    <list>
184
 
      <item><c>run_test -vts</c></item>
185
 
      <item><c><![CDATA[run_test -vts -config <configfilename>]]></c></item>
186
 
      <item><c><![CDATA[run_test -vts -config <configfilename> -suite <suitewithfullpath>
 
202
      <item><c>ct_run -vts</c></item>
 
203
      <item><c><![CDATA[ct_run -vts -config <configfilename>]]></c></item>
 
204
      <item><c><![CDATA[ct_run -vts -config <configfilename> -suite <suitewithfullpath>
187
205
              -case <casename>]]></c></item>
188
206
    </list>
189
207
    
190
208
    <p>From the GUI you can run tests and view the result and the logs.
191
209
    </p>
192
210
    
193
 
    <p>Note that <c>run_test -vts</c> will try to open the Common Test start
 
211
    <p>Note that <c>ct_run -vts</c> will try to open the Common Test start
194
212
      page in an existing web browser window or start the browser if it is
195
213
      not running. Which browser should be started may be specified with
196
214
      the browser start command option:</p>
197
 
      <p><c><![CDATA[run_test -vts -browser <browser_start_cmd>]]></c></p>
 
215
      <p><c><![CDATA[ct_run -vts -browser <browser_start_cmd>]]></c></p>
198
216
      <p>Example:</p>
199
 
      <p><c><![CDATA[$ run_test -vts -browser 'firefox&']]></c></p>
 
217
      <p><c><![CDATA[$ ct_run -vts -browser 'firefox&']]></c></p>
200
218
      <p>Note that the browser must run as a separate OS process or VTS will hang!</p>
201
 
      <p>If no specific browser start command is specified, netscape will
 
219
      <p>If no specific browser start command is specified, Firefox will
202
220
        be the default browser on Unix platforms and Internet Explorer on Windows.
203
 
        If Common Test fails to start a browser automatically, start your 
204
 
        favourite browser manually instead and type in the URL that Common Test
 
221
        If Common Test fails to start a browser automatically, or <c>'none'</c> is
 
222
        specified as the value for -browser (i.e. <c>-browser none</c>), start your
 
223
        favourite browser manually and type in the URL that Common Test
205
224
        displays in the shell.</p>    
206
225
  </section>
207
226
  
211
230
    <p>Common Test provides an Erlang API for running tests. The main (and most
212
231
      flexible) function for specifying and executing tests is called
213
232
      <c>ct:run_test/1</c>. This function takes the same start parameters as
214
 
      the <c>run_test</c> script described above, only the flags are instead
 
233
      the <c>ct_run</c> program described above, only the flags are instead
215
234
      given as options in a list of key-value tuples. E.g. a test specified 
216
 
      with <c>run_test</c> like:</p>
217
 
      <p><c>$ run_test -suite ./my_SUITE -logdir ./results</c></p> 
 
235
      with <c>ct_run</c> like:</p>
 
236
      <p><c>$ ct_run -suite ./my_SUITE -logdir ./results</c></p> 
218
237
      <p>is with <c>ct:run_test/1</c> specified as:</p> 
219
238
      <p><c>1> ct:run_test([{suite,"./my_SUITE"},{logdir,"./results"}]).</c></p>
220
239
      <p>For detailed documentation, please see the <c>ct</c> manual page.</p>    
237
256
      manually and call <c>ct:install/1</c> to install any configuration
238
257
      data you might need (use <c>[]</c> as argument otherwise), then
239
258
      call <c>ct:start_interactive/0</c> to start Common Test. If you use
240
 
      the <c>run_test</c> script, you may start the Erlang shell and Common Test
 
259
      the <c>ct_run</c> program, you may start the Erlang shell and Common Test
241
260
      in the same go by using the <c>-shell</c> and, optionally, the <c>-config</c>
242
 
      flag:
 
261
      and/or <c>-userconfig</c> flag. Examples:
243
262
    </p>
244
263
    <list>
245
 
      <item><c>run_test -shell</c></item>
246
 
      <item><c><![CDATA[run_test -shell -config <configfilename>]]></c></item>
 
264
      <item><c>ct_run -shell</c></item>
 
265
      <item><c><![CDATA[ct_run -shell -config cfg/db.cfg]]></c></item>
 
266
      <item><c><![CDATA[ct_run -shell -userconfig db_login testuser x523qZ]]></c></item>
247
267
    </list>
248
268
    
249
 
    <p>If no config file is given with the <c>run_test</c> command,
 
269
    <p>If no config file is given with the <c>ct_run</c> command,
250
270
      a warning will be displayed. If Common Test has been run from the same
251
271
      directory earlier, the same config file(s) will be used
252
272
      again. If Common Test has not been run from this directory before, no
268
288
       2> ct_telnet:open(unix_telnet).
269
289
       {ok,&lt;0.105.0&gt;}
270
290
       4> ct_telnet:cmd(unix_telnet, "ls .").
271
 
       {ok,["ls .","file1  ...",...]}</pre>
 
291
       {ok,["ls .","file1  ...",...]}
 
292
    </pre>
272
293
    
273
294
    <p>Everything that Common Test normally prints in the test case logs,
274
295
      will in the interactive mode be written to a log named
275
296
      <c>ctlog.html</c> in the <c><![CDATA[ct_run.<timestamp>]]></c>
276
297
      directory. A link to this file will be available in the file
277
298
      named <c>last_interactive.html</c> in the directory from which
278
 
      you executed <c>run_test</c>. Currently, specifying a different
 
299
      you executed <c>ct_run</c>. Currently, specifying a different
279
300
      root directory for the logs than the current working directory,
280
301
      is not supported.</p>
281
302
    
291
312
  <section>
292
313
    <title>Step by step execution of test cases with the Erlang Debugger</title>
293
314
   
294
 
    <p>By means of <c>run_test -step [opts]</c>, or by passing the 
 
315
    <p>By means of <c>ct_run -step [opts]</c>, or by passing the 
295
316
       <c>{step,Opts}</c> option to <c>ct:run_test/1</c>, it is possible
296
317
       to get the Erlang Debugger started automatically and use its
297
318
       graphical interface to investigate the state of the current test 
315
336
       with <c>dir</c>.</p>       
316
337
  </section>
317
338
 
 
339
  <marker id="test_specifications"></marker>
318
340
  <section>
319
 
    <marker id="test_specifications"></marker>
320
341
    <title>Using test specifications</title>
321
342
    
322
 
    <p>The most expressive way to specify what to test is to use a so 
323
 
      called test specification. A test specification is a sequence of 
324
 
      Erlang terms. The terms may be declared in a text file or passed 
325
 
      to the test server at runtime as a list (see <c>run_testspec/1</c>
326
 
      in the manual page for <c>ct</c>). There are two general types 
327
 
      of terms: configuration terms and test specification terms.</p>
328
 
    <p>With configuration terms it is possible to import configuration 
329
 
      data (similar to <c>run_test -config</c>), specify HTML log 
330
 
      directories (similar to <c>run_test -logdir</c>), give aliases 
331
 
      to test nodes and test directories (to make a specification
332
 
      easier to read and maintain), enable code coverage analysis
333
 
      (see the <seealso marker="cover_chapter#cover">Code Coverage 
334
 
       Analysis</seealso> chapter) and specify event_handler plugins 
 
343
    <p>The most flexible way to specify what to test, is to use a so
 
344
      called test specification. A test specification is a sequence of
 
345
      Erlang terms. The terms may be declared in a text file or passed
 
346
      to the test server at runtime as a list
 
347
      (see <c>run_testspec/1</c> in the manual page
 
348
      for <c>ct</c>). There are two general types of terms:
 
349
      configuration terms and test specification terms.</p>
 
350
    <p>With configuration terms it is possible to e.g. label the test
 
351
      run (similar to <c>ct_run -label</c>), evaluate arbitrary expressions
 
352
      before starting a test, import configuration
 
353
      data (similar to
 
354
      <c>ct_run -config/-userconfig</c>), specify HTML log directories (similar
 
355
      to
 
356
      <c>ct_run -logdir</c>), give aliases to test nodes and test
 
357
      directories (to make a specification easier to read and
 
358
      maintain), enable code coverage analysis (see
 
359
      the <seealso marker="cover_chapter#cover">Code Coverage
 
360
      Analysis</seealso> chapter) and specify event_handler plugins
335
361
      (see the <seealso marker="event_handler_chapter#event_handling">
336
 
       Event Handling</seealso> chapter). There is also a term
337
 
       for specifying include directories that should be passed on
338
 
       to the compiler when automatic compilation is performed 
339
 
       (similar to <c>run_test -include</c>, see above).</p>
340
 
    <p>With test specification terms it is possible to state exactly which
341
 
      tests should run and in which order. A test term specifies either
342
 
      one or more suites or one or more test cases. An arbitrary number of test 
343
 
      terms may be declared in sequence. A test term can also specify one or 
344
 
      more test suites or test cases to be skipped. Skipped suites and cases 
345
 
      are not executed and show up in the HTML test log as SKIPPED.</p>
346
 
 
347
 
    <note><p>It is not yet possible to specify test case groups in
348
 
      test specifications. This will be supported in a soon upcoming 
349
 
      release.</p></note>
 
362
      Event Handling</seealso> chapter). There is also a term for
 
363
      specifying include directories that should be passed on to the
 
364
      compiler when automatic compilation is performed (similar
 
365
      to <c>ct_run -include</c>, see above).</p>
 
366
    <p>With test specification terms it is possible to state exactly
 
367
      which tests should run and in which order. A test term specifies
 
368
      either one or more suites, one or more test case groups, or one
 
369
      or more test cases in a group or suite.</p>
 
370
    <p>An arbitrary number of test terms may be declared in sequence.
 
371
      Common Test will by default compile the terms into one or more tests 
 
372
      to be performed in one resulting test run. Note that a term that
 
373
      specifies a set of test cases will "swallow" one that only
 
374
      specifies a subset of these cases. E.g. the result of merging
 
375
      one term that specifies that all cases in suite S should be
 
376
      executed, with another term specifying only test case X and Y in
 
377
      S, is a test of all cases in S. However, if a term specifying
 
378
      test case X and Y in S is merged with a term specifying case Z
 
379
      in S, the result is a test of X, Y and Z in S. To disable this
 
380
      behaviour, it is possible in test specification to set the 
 
381
      <c>merge_tests</c> term to <c>false</c>.</p>
 
382
    <p>A test term can also specify one or more test suites, groups,
 
383
      or test cases to be skipped. Skipped suites, groups and cases
 
384
      are not executed and show up in the HTML test log files as
 
385
      SKIPPED.</p>
 
386
    <p>When a test case group is specified, the resulting test
 
387
      executes the
 
388
      <c>init_per_group</c> function, followed by all test cases and
 
389
      sub groups (including their configuration functions), and
 
390
      finally the <c>end_per_group</c> function. Also if particular
 
391
      test cases in a group are specified, <c>init_per_group</c>
 
392
      and <c>end_per_group</c> for the group in question are
 
393
      called. If a group which is defined (in <c>Suite:group/0</c>) to
 
394
      be a sub group of another group, is specified (or particular test
 
395
      cases of a sub group are), Common Test will call the configuration
 
396
      functions for the top level groups as well as for the sub group
 
397
      in question (making it possible to pass configuration data all
 
398
      the way from <c>init_per_suite</c> down to the test cases in the
 
399
      sub group).</p>
350
400
 
351
401
    <p>Below is the test specification syntax. Test specifications can
352
 
      be used to run tests both in a single test host environment and in 
353
 
      a distributed Common Test environment. Node parameters are only relevant in the 
354
 
      latter (see the chapter about running Common Test in distributed mode for information). 
355
 
      For details on the event_handler term, see the 
356
 
      <seealso marker="event_handler_chapter#event_handling">Event Handling</seealso>
357
 
      chapter.</p>
 
402
      be used to run tests both in a single test host environment and
 
403
      in a distributed Common Test environment (Large Scale
 
404
      Testing). The node parameters in the init term are only
 
405
      relevant in the latter (see the
 
406
      <seealso marker="ct_master_chapter#test_specifications">Large
 
407
      Scale Testing</seealso> chapter for information). For details on
 
408
      the event_handler term, see the
 
409
      <seealso marker="event_handler_chapter#event_handling">Event
 
410
      Handling</seealso> chapter.</p>
358
411
      <p>Config terms:</p>
359
412
    <pre>
360
413
      {node, NodeAlias, Node}.
 
414
 
 
415
      {init, InitOptions}.
 
416
      {init, [NodeAlias], InitOptions}.
 
417
 
 
418
      {label, Label}.
 
419
      {label, NodeRefs, Label}.
 
420
 
 
421
      {multiply_timetraps, N}.
 
422
      {multiply_timetraps, NodeRefs, N}.
 
423
 
 
424
      {scale_timetraps, Bool}.
 
425
      {scale_timetraps, NodeRefs, Bool}.
361
426
 
362
427
      {cover, CoverSpecFile}.
363
 
      {cover, NodeRef, CoverSpecFile}.
 
428
      {cover, NodeRefs, CoverSpecFile}.
364
429
      
365
430
      {include, IncludeDirs}.
366
431
      {include, NodeRefs, IncludeDirs}.
367
432
 
368
433
      {config, ConfigFiles}.
369
434
      {config, NodeRefs, ConfigFiles}.
 
435
 
 
436
      {userconfig, {CallbackModule, ConfigStrings}}.
 
437
      {userconfig, NodeRefs, {CallbackModule, ConfigStrings}}.
370
438
      
371
439
      {alias, DirAlias, Dir}.
 
440
 
 
441
      {merge_tests, Bool}.
372
442
      
373
443
      {logdir, LogDir}.                                        
374
444
      {logdir, NodeRefs, LogDir}.
377
447
      {event_handler, NodeRefs, EventHandlers}.
378
448
      {event_handler, EventHandlers, InitArgs}.
379
449
      {event_handler, NodeRefs, EventHandlers, InitArgs}.
 
450
 
 
451
      {ct_hooks, CTHModules}.
 
452
      {ct_hooks, NodeRefs, CTHModules}.
380
453
    </pre>
381
454
      <p>Test terms:</p>
382
455
    <pre>
383
456
      {suites, DirRef, Suites}.                                
384
457
      {suites, NodeRefs, DirRef, Suites}.
385
458
      
 
459
      {groups, DirRef, Suite, Groups}.
 
460
      {groups, NodeRefsDirRef, Suite, Groups}.
 
461
 
 
462
      {groups, DirRef, Suite, Group, {cases,Cases}}.
 
463
      {groups, NodeRefsDirRef, Suite, Group, {cases,Cases}}.
 
464
 
386
465
      {cases, DirRef, Suite, Cases}.                           
387
466
      {cases, NodeRefs, DirRef, Suite, Cases}.
388
467
 
395
474
      <p>Types:</p>
396
475
    <pre>
397
476
      NodeAlias     = atom()
 
477
      InitOptions   = term()
398
478
      Node          = node()
399
479
      NodeRef       = NodeAlias | Node | master
400
480
      NodeRefs      = all_nodes | [NodeRef] | NodeRef
 
481
      N             = integer()
 
482
      Bool          = true | false
401
483
      CoverSpecFile = string()
402
484
      IncludeDirs   = string() | [string()]
403
485
      ConfigFiles   = string() | [string()]
406
488
      LogDir        = string()
407
489
      EventHandlers = atom() | [atom()]
408
490
      InitArgs      = [term()]
 
491
      CTHModules    = [CTHModule | {CTHModule, CTHInitArgs}]
 
492
      CTHModule     = atom()
 
493
      CTHInitArgs   = term()
409
494
      DirRef        = DirAlias | Dir
410
495
      Suites        = atom() | [atom()] | all
 
496
      Suite         = atom()
 
497
      Groups        = atom() | [atom()] | all
 
498
      Group         = atom()
411
499
      Cases         = atom() | [atom()] | all
412
500
      Comment       = string() | ""
413
501
    </pre>
449
537
      <item>Secondly, the test for system t2 should run. The included suites are
450
538
        t2B and t2C. Included are also test cases test4, test1 and test7 in suite
451
539
        t2A. Note that the test cases will be executed in the specified order.</item>
452
 
      <item>Lastly, all suites for systems t3 are to be completely skipped and this 
 
540
      <item>Lastly, all suites for systems t3 are to be completely skipped and this
453
541
        should be explicitly noted in the log files.</item>
454
542
    </list>
 
543
    <p>It is possible to specify initialization options for nodes defined in the
 
544
      test specification. Currently, there are options to start the node and/or to
 
545
      evaluate any function on the node.
 
546
      See the <seealso marker="ct_master_chapter#ct_slave">Automatic startup of
 
547
      the test target nodes</seealso> chapter for details.</p>
455
548
    <p>It is possible for the user to provide a test specification that
456
549
      includes (for Common Test) unrecognizable terms. If this is desired,
457
550
      the <c>-allow_user_terms</c> flag should be used when starting tests with
458
 
      <c>run_test</c>. This forces Common Test to ignore unrecognizable terms.
 
551
      <c>ct_run</c>. This forces Common Test to ignore unrecognizable terms.
459
552
      Note that in this mode, Common Test is not able to check the specification 
460
553
      for errors as efficiently as if the scanner runs in default mode. 
461
554
      If <c>ct:run_test/1</c> is used for starting the tests, the relaxed scanner 
581
674
        </pre>
582
675
 
583
676
        <p>To install the CSS file (Common Test inlines the definition in the 
584
 
          HTML code), the name may be provided when executing <c>run_test</c>.
 
677
          HTML code), the name may be provided when executing <c>ct_run</c>.
585
678
          Example:</p>
586
679
 
587
680
        <pre>
588
 
          $ run_test -dir $TEST/prog -stylesheet $TEST/styles/test_categories.css
 
681
          $ ct_run -dir $TEST/prog -stylesheet $TEST/styles/test_categories.css
589
682
        </pre>
590
683
 
591
684
          <p>Categories in a CSS file installed with the <c>-stylesheet</c> flag
658
751
       means of time, it is also possible to specify what action Common Test should 
659
752
       take upon timeout. Either Common Test performs all tests in the current run before stopping, 
660
753
       or it stops as soon as the current test job is finished. Repetition can be activated by
661
 
       means of <c>run_test</c> start flags, or tuples in the <c>ct:run:test/1</c>
 
754
       means of <c>ct_run</c> start flags, or tuples in the <c>ct:run:test/1</c>
662
755
       option list argument. The flags (options in parenthesis) are:</p>
663
756
       <list>
664
757
       <item><c>-repeat N ({repeat,N})</c>, where <c>N</c> is a positive integer.</item>
694
787
 
695
788
       <p>Example 1:</p>
696
789
       <pre>
697
 
          $ run_test -dir $TEST_ROOT/to1 $TEST_ROOT/to2 -duration 001000 -force_stop</pre>
 
790
          $ ct_run -dir $TEST_ROOT/to1 $TEST_ROOT/to2 -duration 001000 -force_stop</pre>
698
791
       <p>Here the suites in test directory to1, followed by the suites in to2, will be executed 
699
792
          in one test run. A timeout event will occur after 10 minutes. As long as there is time 
700
793
          left, Common Test will repeat the test run (i.e. starting over with the to1 test). 
707
800
          $ date
708
801
          Fri Sep 28 15:00:00 MEST 2007
709
802
 
710
 
          $ run_test -dir $TEST_ROOT/to1 $TEST_ROOT/to2 -until 160000</pre>
 
803
          $ ct_run -dir $TEST_ROOT/to1 $TEST_ROOT/to2 -until 160000</pre>
711
804
       <p>Here the same test run as in the example above will be executed (and possibly repeated). 
712
805
          In this example, however, the timeout will occur after 1 hour and when that happens,
713
806
          Common Test will finish the entire test run before stopping (i.e. the to1 and to2 test
715
808
       
716
809
       <p>Example 3:</p>
717
810
       <pre>
718
 
          $ run_test -dir $TEST_ROOT/to1 $TEST_ROOT/to2 -repeat 5</pre>
 
811
          $ ct_run -dir $TEST_ROOT/to1 $TEST_ROOT/to2 -repeat 5</pre>
719
812
       <p>Here the test run, including both the to1 and the to2 test, will be repeated 5 times.</p>
720
813
 
721
814
       <note><p>This feature should not be confused with the <c>repeat</c> property of a test
734
827
        of the <c>-silent_connections</c> flag:</p>
735
828
      
736
829
      <pre>
737
 
        run_test -silent_connections [conn_types]
 
830
        ct_run -silent_connections [conn_types]
738
831
      </pre>
739
832
      
740
833
      <p>where <c>conn_types</c> specifies <c>telnet, ftp, rpc</c> and/or <c>snmp</c>.</p>
742
835
      <p>Example:</p>
743
836
      
744
837
      <pre>
745
 
        run_test ... -silent_connections telnet ftp</pre>
 
838
        ct_run ... -silent_connections telnet ftp</pre>
746
839
      <p>switches off logging for telnet and ftp connections.</p>
747
840
      
748
841
      <pre>
749
 
        run_test ... -silent_connections</pre>
 
842
        ct_run ... -silent_connections</pre>
750
843
      <p>switches off logging for all connection types.</p>
751
844
      
752
845