aboutsummaryrefslogtreecommitdiffstats
path: root/lib/test_server/doc/src/test_server_ctrl.xml
blob: 9028a67ecb01cfac3ca45f8ab89bbd0c3dfe67ed (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2007</year>
      <year>2011</year>
      <holder>Ericsson AB, All Rights Reserved</holder>
    </copyright>
    <legalnotice>
  The contents of this file are subject to the Erlang Public License,
  Version 1.1, (the "License"); you may not use this file except in
  compliance with the License. You should have received a copy of the
  Erlang Public License along with this software. If not, it can be
  retrieved online at http://www.erlang.org/.

  Software distributed under the License is distributed on an "AS IS"
  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  the License for the specific language governing rights and limitations
  under the License.

  The Initial Developer of the Original Code is Ericsson AB.
    </legalnotice>

    <title>The Test Server Controller</title>
    <prepared>Siri Hansen, Peter Andersson</prepared>
    <responsible></responsible>
    <docno></docno>
    <approved></approved>
    <checked></checked>
    <date></date>
    <rev></rev>
    <file>test_server_ctrl_ref.sgml</file>
  </header>
  <module>test_server_ctrl</module>
  <modulesummary>This module provides a low level interface to the Test Server.</modulesummary>
  <description>
    <p>The <c>test_server_ctrl</c> module provides a low level
      interface to the Test Server. This interface is normally
      not used directly by the tester, but through a framework built 
      on top of <c>test_server_ctrl</c>.
      </p>
    <p>Common Test is such a framework, well suited for automated
      black box testing of target systems of any kind (not necessarily
      implemented in Erlang). Common Test is also a very useful tool for
      white box testing Erlang programs and OTP applications. 
      Please see the Common Test User's Guide and reference manual for 
      more information.
      </p>
    <p>If you want to write your own framework, some more information
      can be found in the chapter "Writing your own test server
      framework" in the Test Server User's Guide. Details about the
      interface provided by <c>test_server_ctrl</c> follows below.
      </p>
  </description>
  <funcs>
    <func>
      <name>start() -> Result</name>
      <name>start(ParameterFile) -> Result</name>
      <fsummary>Starts the test server.</fsummary>
      <type>
        <v>Result = ok | {error, {already_started, pid()}</v>
        <v>ParameterFile = atom() | string()</v>
      </type>
      <desc>
        <p>This function starts the test server. If the parameter file
          is given, it indicates that the target is remote. In that case
          the target node is started and a socket connection is
          established between the controller and the target node.
          </p>
        <p>The parameter file is a text file containing key-value
          tuples. Each tuple must be followed by a dot-newline
          sequence. The following key-value tuples are allowed:
          </p>
        <taglist>
          <tag><c>{type,PlatformType}</c></tag>
          <item>This is an atom indicating the target platform type,
           currently supported: <c>PlatformType = vxworks</c>          <br></br>
Mandatory
          </item>
          <tag><c>{target,TargetHost}</c></tag>
          <item>This is the name of the target host, can be atom or
           string.
                    <br></br>
Mandatory
          </item>
          <tag><c>{slavetargets,SlaveTargets}</c></tag>
          <item>This is a list of available hosts where slave nodes
           can be started. The hostnames are given as atoms or strings.
                    <br></br>
Optional, default <c>SlaveTargets = []</c></item>
          <tag><c>{longnames,Bool}</c></tag>
          <item>This indicates if longnames shall be used, i.e. if the
          <c>-name</c> option should be used for the target node
           instead of <c>-sname</c>          <br></br>
Optional, default <c>Bool = false</c></item>
          <tag><c>{master, {MasterHost, MasterCookie}}</c></tag>
          <item>If target is remote and the target node is started as
           a slave node, this option indicates which master and 
	   cookie to use. The given master
           will also be used as master for slave nodes started with
          <c>test_server:start_node/3</c>. It is expected that the
          <c>erl_boot_server</c> is started on the master node before
           the <c>test_server_ctrl:start/1</c> function is called.
                    <br></br>
Optional, if not given the test server controller node
           is used as master and the <c>erl_boot_server</c> is
           automatically started.</item>
        </taglist>
      </desc>
    </func>
    <func>
      <name>stop() -> ok</name>
      <fsummary>Stops the test server immediately.</fsummary>
      <desc>
        <p>This stops the test server (both controller and target) and
          all its activity.  The running test suite (if any) will be
          halted.</p>
      </desc>
    </func>
    <func>
      <name>add_dir(Name, Dir) -> ok</name>
      <name>add_dir(Name, Dir, Pattern) -> ok</name>
      <name>add_dir(Name, [Dir|Dirs]) -> ok</name>
      <name>add_dir(Name, [Dir|Dirs], Pattern) -> ok</name>
      <fsummary>Add a directory to the job queue.</fsummary>
      <type>
        <v>Name = term()</v>
        <d>The jobname for this directory.</d>
        <v>Dir = term()</v>
        <d>The directory to scan for test suites.</d>
        <v>Dirs = [term()]</v>
        <d>List of directories to scan for test suites.</d>
        <v>Pattern = term()</v>
        <d>Suite match pattern. Directories will be scanned for Pattern_SUITE.erl files.</d>
      </type>
      <desc>
        <p>Puts a collection of suites matching (*_SUITE) in given
          directories into the job queue. <c>Name</c> is an arbitrary
          name for the job, it can be any erlang term. If <c>Pattern</c>
          is given, only modules matching <c>Pattern*</c> will be added.</p>
      </desc>
    </func>
    <func>
      <name>add_module(Mod) -> ok</name>
      <name>add_module(Name, [Mod|Mods]) -> ok</name>
      <fsummary>Add a module to the job queue with or without a given name.</fsummary>
      <type>
        <v>Mod = atom()</v>
        <v>Mods = [atom()]</v>
        <d>The name(s) of the module(s) to add.</d>
        <v>Name = term()</v>
        <d>Name for the job.</d>
      </type>
      <desc>
        <p>This function adds a module or a list of modules, to the
          test servers job queue. <c>Name</c> may be any Erlang
          term. When <c>Name</c> is not given, the job gets the name of
          the module.</p>
      </desc>
    </func>
    <func>
      <name>add_case(Mod, Case) -> ok</name>
      <fsummary>Adds one test case to the job queue.</fsummary>
      <type>
        <v>Mod = atom()</v>
        <d>Name of the module the test case is in.</d>
        <v>Case = atom() </v>
        <d>Function name of the test case to add.</d>
      </type>
      <desc>
        <p>This function will add one test case to the job queue. The
          job will be given the module's name.</p>
      </desc>
    </func>
    <func>
      <name>add_case(Name, Mod, Case) -> ok</name>
      <fsummary>Equivalent to add_case/2, but with specified name.</fsummary>
      <type>
        <v>Name = string()</v>
        <d>Name to use for the test job.</d>
      </type>
      <desc>
        <p>Equivalent to <c>add_case/2</c>, but the test job will get
          the specified name.</p>
      </desc>
    </func>
    <func>
      <name>add_cases(Mod, Cases) -> ok</name>
      <fsummary>Adds a list of test cases to the job queue.</fsummary>
      <type>
        <v>Mod = atom()</v>
        <d>Name of the module the test case is in.</d>
        <v>Cases = [Case] </v>
        <v>Case = atom() </v>
        <d>Function names of the test cases to add.</d>
      </type>
      <desc>
        <p>This function will add one or more test cases to the job
          queue. The job will be given the module's name.</p>
      </desc>
    </func>
    <func>
      <name>add_cases(Name, Mod, Cases) -> ok</name>
      <fsummary>Equivalent to add_cases/2, but with specified name.</fsummary>
      <type>
        <v>Name = string()</v>
        <d>Name to use for the test job.</d>
      </type>
      <desc>
        <p>Equivalent to <c>add_cases/2</c>, but the test job will get
          the specified name.</p>
      </desc>
    </func>
    <func>
      <name>add_spec(TestSpecFile) -> ok | {error, nofile}</name>
      <fsummary>Adds a test specification file to the job queue.</fsummary>
      <type>
        <v>TestSpecFile = string()</v>
        <d>Name of the test specification file</d>
      </type>
      <desc>
        <p>This function will add the content of the given test
          specification file to the job queue. The job will be given the
          name of the test specification file, e.g. if the file is
          called <c>test.spec</c>, the job will be called <c>test</c>.
          </p>
        <p>See the reference manual for the test server application
          for details about the test specification file.</p>
      </desc>
      </func>
      <func>
        <name>add_dir_with_skip(Name, [Dir|Dirs], Skip) -> ok</name>
	<name>add_dir_with_skip(Name, [Dir|Dirs], Pattern, Skip) -> ok</name>
        <name>add_module_with_skip(Mod, Skip) -> ok</name>
        <name>add_module_with_skip(Name, [Mod|Mods], Skip) -> ok</name>
        <name>add_case_with_skip(Mod, Case, Skip) -> ok</name>
        <name>add_case_with_skip(Name, Mod, Case, Skip) -> ok</name>
	<name>add_cases_with_skip(Mod, Cases, Skip) -> ok</name>
	<name>add_cases_with_skip(Name, Mod, Cases, Skip) -> ok</name>
	<fsummary>Same purpose as functions listed above, but with extra Skip argument.</fsummary>
	<type>
	<v>Skip = [SkipItem]</v>
	<d>List of items to be skipped from the test.</d>
        <v>SkipItem = {Mod,Comment} | {Mod,Case,Comment} | {Mod,Cases,Comment}</v>
	<v>Mod = atom()</v>
	<d>Test suite name.</d>
	<v>Comment = string()</v>
	<d>Reason why suite or case is being skipped.</d>
	<v>Cases = [Case]</v>
	<v>Case = atom()</v>
	<d>Name of test case function.</d>
	</type>
	<desc>
	  <p>These functions add test jobs just like the add_dir, add_module,
	    add_case and add_cases functions above, but carry an additional
	    argument, Skip. Skip is a list of items that should be skipped
	    in the current test run. Test job items that occur in the Skip
	    list will be logged as SKIPPED with the associated Comment.</p>
	</desc>
    </func>
    <func>
      <name>add_tests_with_skip(Name, Tests, Skip) -> ok</name>
      <fsummary>Adds different types of jobs to the run queue.</fsummary>
      <type>
        <v>Name = term()</v>
        <d>The jobname for this directory.</d>
	<v>Tests = [TestItem]</v>
	<d>List of jobs to add to the run queue.</d>
	<v>TestItem = {Dir,all,all} | {Dir,Mods,all} | {Dir,Mod,Cases}</v>
        <v>Dir = term()</v>
        <d>The directory to scan for test suites.</d>
	<v>Mods = [Mod]</v>
	<v>Mod = atom()</v>
	<d>Test suite name.</d>
	<v>Cases = [Case]</v>
	<v>Case = atom()</v>
	<d>Name of test case function.</d>
	<v>Skip = [SkipItem]</v>
	<d>List of items to be skipped from the test.</d>
        <v>SkipItem = {Mod,Comment} | {Mod,Case,Comment} | {Mod,Cases,Comment}</v>
	<v>Comment = string()</v>
	<d>Reason why suite or case is being skipped.</d>
      </type>
	<desc>
	<p>This function adds various test jobs to the test_server_ctrl
	job queue. These jobs can be of different type (all or specific suites 
	in one directory, all or specific cases in one suite, etc). It is also
	possible to get particular items skipped by passing them along in the
	Skip list (see the add_*_with_skip functions above).</p>
	</desc>
    </func>
    <func>
      <name>abort_current_testcase(Reason) -> ok | {error,no_testcase_running}</name>
      <fsummary>Aborts the test case currently executing.</fsummary>
      <type>
      <v>Reason = term()</v>
      <d>The reason for stopping the test case, which will be printed in the log.</d>
      </type>
	<desc>
	<p>When calling this function, the currently executing test case will be aborted.
	   It is the user's responsibility to know for sure which test case is currently
	   executing. The function is therefore only safe to call from a function which
	   has been called (or synchronously invoked) by the test case.</p>
	</desc>
    </func>
    <func>
      <name>set_levels(Console, Major, Minor) -> ok</name>
      <fsummary>Sets the levels of I/O.</fsummary>
      <type>
        <v>Console = integer()</v>
        <d>Level for I/O to be sent to console.</d>
        <v>Major = integer()</v>
        <d>Level for I/O to be sent to the major logfile.</d>
        <v>Minor = integer()</v>
        <d>Level for I/O to be sent to the minor logfile.</d>
      </type>
      <desc>
        <p>Determines where I/O from test suites/test server will
          go. All text output from test suites and the test server is
          tagged with a priority value which ranges from 0 to 100, 100
          being the most detailed. (see the section about log files in
          the user's guide). Output from the test cases (using
          <c>io:format/2</c>) has a detail level of 50. Depending on the
          levels set by this function, this I/O may be sent to the
          console, the major log file (for the whole test suite) or to
          the minor logfile (separate for each test case).
          </p>
        <p>All output with detail level:</p>
        <list type="bulleted">
          <item>Less than or equal to <c>Console</c> is displayed on
           the screen (default 1)
          </item>
          <item>Less than or equal to <c>Major</c> is logged in the
           major log file (default 19)
          </item>
          <item>Greater than or equal to <c>Minor</c> is logged in the
           minor log files (default 10)
          </item>
        </list>
        <p>To view the currently set thresholds, use the
          <c>get_levels/0</c> function.</p>
      </desc>
    </func>
    <func>
      <name>get_levels() -> {Console, Major, Minor}</name>
      <fsummary>Returns the current levels.</fsummary>
      <desc>
        <p>Returns the current levels. See <c>set_levels/3</c> for
          types.</p>
      </desc>
    </func>
    <func>
      <name>jobs() -> JobQueue</name>
      <fsummary>Returns the job queue.</fsummary>
      <type>
        <v>JobQueue = [{list(), pid()}]</v>
      </type>
      <desc>
        <p>This function will return all the jobs currently in the job
          queue.</p>
      </desc>
    </func>
    <func>
      <name>multiply_timetraps(N) -> ok</name>
      <fsummary>All timetraps started after this will be multiplied by N.</fsummary>
      <type>
        <v>N = integer() | infinity</v>
      </type>
      <desc>
        <p>This function should be called before a test is started
          which requires extended timetraps, e.g. if extensive tracing
          is used. All timetraps started after this call will be
          multiplied by <c>N</c>.</p>
      </desc>
    </func>
    <func>
      <name>scale_timetraps(Bool) -> ok</name>
      <fsummary>.</fsummary>
      <type>
        <v>Bool = true | false</v>
      </type>
      <desc>
        <p>This function should be called before a test is started.
	  The parameter specifies if test_server should attempt
	  to automatically scale the timetrap value in order to compensate
	  for delays caused by e.g. the cover tool.</p>
      </desc>
    </func>
    <func>
      <name>get_timetrap_parameters() -> {N,Bool} </name>
      <fsummary>Read the parameter values that affect timetraps.</fsummary>
      <type>
        <v>N = integer() | infinity</v>
        <v>Bool = true | false</v>
      </type>
      <desc>
        <p>This function may be called to read the values set by
	<c>multiply_timetraps/1</c> and <c>scale_timetraps/1</c>.</p>
      </desc>
    </func>
    <func>
      <name>cover(Application,Analyse) -> ok</name>
      <name>cover(CoverFile,Analyse) -> ok</name>
      <name>cover(App,CoverFile,Analyse) -> ok</name>
      <fsummary>Informs the test_server controller that next test shall run with code coverage analysis.</fsummary>
      <type>
        <v>Application = atom()</v>
        <d>OTP application to cover compile</d>
        <v>CoverFile = string()</v>
        <d>Name of file listing modules to exclude from or include in cover compilation. The filename must include full path to the file.</d>
        <v>Analyse = details | overview</v>
      </type>
      <desc>
        <p>This function informs the test_server controller that next
          test shall run with code coverage analysis. All timetraps will
          automatically be multiplied by 10 when cover i run.
          </p>
        <p><c>Application</c> and <c>CoverFile</c> indicates what to
          cover compile. If <c>Application</c> is given, the default is
          that all modules in the <c>ebin</c> directory of the
          application will be cover compiled. The <c>ebin</c> directory
          is found by adding <c>ebin</c> to
          <c>code:lib_dir(Application)</c>.
          </p>
        <p>A <c>CoverFile</c> can have the following entries:</p>
        <code type="none">
{exclude, all | ExcludeModuleList}.
{include, IncludeModuleList}.        </code>
        <p>Note that each line must end with a full
          stop. <c>ExcludeModuleList</c> and <c>IncludeModuleList</c>
          are lists of atoms, where each atom is a module name.
          </p>
        <p>If both an <c>Application</c> and a <c>CoverFile</c> is
          given, all modules in the application are cover compiled,
          except for the modules listed in <c>ExcludeModuleList</c>. The
          modules in <c>IncludeModuleList</c> are also cover compiled.
          </p>
        <p>If a <c>CoverFile</c> is given, but no <c>Application</c>,
          only the modules in <c>IncludeModuleList</c> are cover
          compiled.
          </p>
        <p><c>Analyse</c> indicates the detail level of the cover
          analysis. If <c>Analyse = details</c>, each cover compiled
          module will be analysed with
          <c>cover:analyse_to_file/1</c>. If <c>Analyse = overview</c>
          an overview of all cover compiled modules is created, listing
          the number of covered and not covered lines for each module.
          </p>
        <p>If the test following this call starts any slave or peer
          nodes with <c>test_server:start_node/3</c>, the same cover
          compiled code will be loaded on all nodes. If the loading
          fails, e.g. if the node runs an old version of OTP, the node
          will simply not be a part of the coverage analysis. Note that
          slave or peer nodes must be stopped with
          <c>test_server:stop_node/1</c> for the node to be part of the
          coverage analysis, else the test server will not be able to
          fetch coverage data from the node.
          </p>
        <p>When the test is finished, the coverage analysis is
          automatically completed, logs are created and the cover
          compiled modules are unloaded. If another test is to be run
          with coverage analysis, <c>test_server_ctrl:cover/2/3</c> must
          be called again.
          </p>
      </desc>
    </func>
    <func>
      <name>cross_cover_analyse(Level) -> ok</name>
      <fsummary>Analyse cover data collected from all tests</fsummary>
      <type>
        <v>Level = details | overview</v>
      </type>
      <desc>
        <p>Analyse cover data collected from all tests. The modules
          analysed are the ones listed in the cross cover file
          <c>cross.cover</c> in the current directory of the test
          server.</p>
        <p>The modules listed in the <c>cross.cover</c> file are
          modules that are heavily used by other applications than the
          one they belong to. This function should be run after all
          tests are completed, and the result will be stored in a file
          called cross_cover.html in the run.&lt;timestamp&gt;
          directory of the application the modules belong to.
          </p>
        <p>The <c>cross.cover</c> file contains elements like this:</p>
        <pre>
{App,Modules}.        </pre>
        <p>where <c>App</c> can be an application name or the atom
          <c>all</c>. The application (or all applications) will cover
          compile the listed <c>Modules</c>.
          </p>
      </desc>
    </func>
    <func>
      <name>trc(TraceInfoFile) -> ok | {error, Reason}</name>
      <fsummary>Starts call trace on target and slave nodes</fsummary>
      <type>
        <v>TraceInfoFile = atom() | string()</v>
        <d>Name of a file defining which functions to trace and how</d>
      </type>
      <desc>
        <p>This function starts call trace on target and on slave or
          peer nodes that are started or will be started by the test
          suites.
          </p>
        <p>Timetraps are not extended automatically when tracing is
          used. Use <c>multiply_timetraps/1</c> if necessary.
          </p>
        <p>Note that the trace support in the test server is in a very
          early stage of the implementation, and thus not yet as
          powerful as one might wish for.
          </p>
        <p>The trace information file specified by the
          <c>TraceInfoFile</c> argument is a text file containing one or
          more of the following elements:
          </p>
        <list type="bulleted">
          <item><c>{SetTP,Module,Pattern}.</c></item>
          <item><c>{SetTP,Module,Function,Pattern}.</c></item>
          <item><c>{SetTP,Module,Function,Arity,Pattern}.</c></item>
          <item><c>ClearTP.</c></item>
          <item><c>{ClearTP,Module}.</c></item>
          <item><c>{ClearTP,Module,Function}.</c></item>
          <item><c>{ClearTP,Module,Function,Arity}.</c></item>
        </list>
        <taglist>
          <tag><c>SetTP = tp | tpl</c></tag>
          <item>This is maps to the corresponding functions in the
          <c>ttb</c> module in the <c>observer</c>
           application. <c>tp</c> means set trace pattern on global
           function calls. <c>tpl</c> means set trace pattern on local
           and global function calls.
          </item>
          <tag><c>ClearTP =  ctp | ctpl | ctpg</c></tag>
          <item>This is maps to the corresponding functions in the
          <c>ttb</c> module in the <c>observer</c>
           application. <c>ctp</c> means clear trace pattern (i.e. turn
           off) on global and local function calls. <c>ctpl</c> means
           clear trace pattern on local function calls only and <c>ctpg</c>
           means clear trace pattern on global function calls only.
          </item>
          <tag><c>Module = atom()</c></tag>
          <item>The module to trace
          </item>
          <tag><c>Function = atom()</c></tag>
          <item>The name of the function to trace
          </item>
          <tag><c>Arity = integer()</c></tag>
          <item>The arity of the function to trace
          </item>
          <tag><c>Pattern = [] | match_spec()</c></tag>
          <item>The trace pattern to set for the module or
           function. For a description of the match_spec() syntax,
           please turn to the User's guide for the runtime system
           (erts). The chapter "Match Specification in Erlang" explains
           the general match specification language.
          </item>
        </taglist>
        <p>The trace result will be logged in a (binary) file called
          <c>NodeName-test_server</c> in the current directory of the
          test server controller node. The log must be formatted using
          <c>ttb:format/1/2</c>.
          </p>
      </desc>
    </func>
    <func>
      <name>stop_trace() -> ok | {error, not_tracing}</name>
      <fsummary>Stops tracing on target and slave nodes.</fsummary>
      <desc>
        <p>This function stops tracing on target, and on slave or peer
          nodes that are currently running. New slave or peer nodes will
          no longer be traced after this.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>FUNCTIONS INVOKED FROM COMMAND LINE</title>
    <p>The following functions are supposed to be invoked from the
      command line using the <c>-s</c> option when starting the erlang
      node.</p>
  </section>
  <funcs>
    <func>
      <name>run_test(CommandLine) -> ok</name>
      <fsummary>Runs the tests specified on the command line.</fsummary>
      <type>
        <v>CommandLine = FlagList</v>
      </type>
      <desc>
        <p>This function is supposed to be invoked from the
          commandline. It starts the test server, interprets the
          argument supplied from the commandline, runs the tests
          specified and when all tests are done, stops the test server
          and returns to the Erlang prompt.
          </p>
        <p>The <c>CommandLine</c> argument is a list of command line
          flags, typically <c>['KEY1', Value1, 'KEY2', Value2, ...]</c>. 
          The valid command line flags are listed below.
          </p>
        <p>Under a UNIX command prompt, this function can be invoked like this:
                    <br></br>
<c>erl -noshell -s test_server_ctrl run_test KEY1 Value1 KEY2 Value2 ... -s erlang halt</c></p>
        <p>Or make an alias (this is for unix/tcsh)          <br></br>
<c>alias erl_test 'erl -noshell -s test_server_ctrl run_test \!* -s erlang halt'</c></p>
        <p>And then use it like this          <br></br>
<c>erl_test KEY1 Value1 KEY2 Value2 ...</c>          <br></br>
</p>
        <p>The valid command line flags are</p>
        <taglist>
          <tag><c>DIR dir</c></tag>
          <item>Adds all test modules in the directory <c>dir</c> to
           the job queue.
          </item>
          <tag><c>MODULE mod</c></tag>
          <item>Adds the module <c>mod</c> to the job queue.
          </item>
          <tag><c>CASE mod case</c></tag>
          <item>Adds the case <c>case</c> in module <c>mod</c> to the
           job queue.
          </item>
          <tag><c>SPEC spec</c></tag>
          <item>Runs the test specification file <c>spec</c>.
          </item>
          <tag><c>SKIPMOD mod</c></tag>
          <item>Skips all test cases in the module <c>mod</c></item>
          <tag><c>SKIPCASE mod case</c></tag>
          <item>Skips the test case <c>case</c> in module <c>mod</c>.
          </item>
          <tag><c>NAME name</c></tag>
          <item>Names the test suite to something else than the
           default name. This does not apply to <c>SPEC</c> which keeps
           its names.
          </item>
          <tag><c>PARAMETERS parameterfile</c></tag>
          <item>Specifies the parameter file to use when starting
           remote target
          </item>
          <tag><c>COVER app cover_file analyse</c></tag>
          <item>Indicates that the test should be run with cover
           analysis. <c>app</c>, <c>cover_file</c> and <c>analyse</c>
           corresponds to the parameters to
          <c>test_server_ctrl:cover/3</c>. If no cover file is used,
           the atom <c>none</c> should be given.
          </item>
          <tag><c>TRACE traceinfofile</c></tag>
          <item>Specifies a trace information file. When this option
           is given, call tracing is started on the target node and all
           slave or peer nodes that are started. The trace information
           file specifies which modules and functions to trace. See the
           function <c>trc/1</c> above for more information about the
           syntax of this file.
          </item>
        </taglist>
      </desc>
    </func>
  </funcs>

  <section>
    <title>FRAMEWORK CALLBACK FUNCTIONS</title>
    <p>A test server framework can be defined by setting the
      environment variable <c>TEST_SERVER_FRAMEWORK</c> to a module
      name. This module will then be framework callback module, and it
      must export the following function:</p>
  </section>
  <funcs>
    <func>
      <name>get_suite(Mod,Func) -> TestCaseList</name>
      <fsummary>Get subcases.</fsummary>
      <type>
        <v>Mod = atom()</v>
	<d>Test suite name.</d>
        <v>Func = atom()</v>
	<d>Name of test case.</d>
        <v>TestCaseList = [SubCase]</v>
	<d>List of test cases.</d>
        <v>SubCase = atom()</v>
	<d>Name of a case.</d>
      </type>
      <desc>
        <p>This function is called before a test case is started. The
          purpose is to retrieve a list of subcases. The default
          behaviour of this function should be to call
          <c>Mod:Func(suite)</c> and return the result from this call.</p>
      </desc>
    </func>
    <func>
      <name>init_tc(Mod,Func,Args0) -> {ok,Args1} | {skip,ReasonToSkip} | {auto_skip,ReasonToSkip} | {fail,ReasonToFail}</name>
      <fsummary>Preparation for a test case or configuration function.</fsummary>
      <type>
        <v>Mod = atom()</v>
	<d>Test suite name.</d>
        <v>Func = atom()</v>
	<d>Name of test case or configuration function.</d>
        <v>Args0 = Args1 = [tuple()]</v>
	<d>Normally Args = [Config]</d>
	<v>ReasonToSkip = term()</v>
	<d>Reason to skip the test case or configuration function.</d>
	<v>ReasonToFail = term()</v>
	<d>Reason to fail the test case or configuration function.</d>
      </type>
      <desc>
        <p>This function is called before a test case or configuration
	function starts. It is called on the process executing the function
        <c>Mod:Func</c>. Typical use of this function can be to alter
        the input parameters to the test case function (<c>Args</c>) or
        to set properties for the executing process.</p>
	<p>By returning <c>{skip,Reason}</c>, <c>Func</c> gets skipped.
	<c>Func</c> also gets skipped if <c>{auto_skip,Reason}</c> is returned,
	but then gets an auto skipped status (rather than user skipped).</p>
	<p>To fail <c>Func</c> immediately instead of executing it, return 
	<c>{fail,ReasonToFail}.</c></p>
      </desc>
    </func>
    <func>
      <name>end_tc(Mod,Func,Status) -> ok | {fail,ReasonToFail}</name>
      <fsummary>Cleanup after a test case or configuration function.</fsummary>
      <type>
        <v>Mod = atom()</v>
	<d>Test suite name.</d>
        <v>Func = atom()</v>
	<d>Name of test case or configuration function.</d>
        <v>Status = {Result,Args} | {TCPid,Result,Args}</v>
	<d>The status of the test case or configuration function.</d>
	<v>ReasonToFail = term()</v>
	<d>Reason to fail the test case or configuration function.</d>
	<v>Result = ok | Skip | Fail</v>
	<d>The final result of the test case or configuration function.</d>
	<v>TCPid = pid()</v>
	<d>Pid of the process executing Func</d>
	<v>Skip = {skip,SkipReason}</v>
	<v>SkipReason = term() | {failed,{Mod,init_per_testcase,term()}}</v>
	<d>Reason why the function was skipped.</d>
	<v>Fail = {error,term()} | {'EXIT',term()} | {timetrap_timeout,integer()} |
	          {testcase_aborted,term()} | testcase_aborted_or_killed | 
		  {failed,term()} | {failed,{Mod,end_per_testcase,term()}}</v>
	<d>Reason why the function failed.</d>
        <v>Args = [tuple()]</v>
	<d>Normally Args = [Config]</d>
      </type>
      <desc>
        <p>This function is called when a test case, or a configuration function,
	  is finished. It is normally called on the process where the function
          <c>Mod:Func</c> has been executing, but if not, the pid of the test 
	  case process is passed with the <c>Status</c> argument.</p> 
	  <p>Typical use of the <c>end_tc/3</c> function can be to clean up 
	  after <c>init_tc/3</c>.</p> 
	  <p>If <c>Func</c> is a test case, it is possible to analyse the value of 
	  <c>Result</c> to verify that <c>init_per_testcase/2</c> and 
	  <c>end_per_testcase/2</c> executed successfully.</p>
	  <p>It is possible with <c>end_tc/3</c> to fail an otherwise successful
	  test case, by returning <c>{fail,ReasonToFail}</c>. The test case <c>Func</c>
	  will be logged as failed with the provided term as reason.</p>
      </desc>
    </func>
    <func>
      <name>report(What,Data) -> ok</name>
      <fsummary>Progress report for test.</fsummary>
      <type>
        <v>What = atom()</v>
        <v>Data = term()</v>
      </type>
      <desc>
        <p>This function is called in order to keep the framework up-to-date with 
	the progress of the test. This is useful e.g. if the
        framework implements a GUI where the progress information is
        constantly updated. The following can be reported:
        </p>
        <p><c>What = tests_start, Data = {Name,NumCases}</c><br></br>
	   <c>What = tests_done, Data = {Ok,Failed,{UserSkipped,AutoSkipped}}</c><br></br>
	   <c>What = tc_start, Data = {Mod,Func}</c><br></br>
	   <c>What = tc_done, Data = {Mod,Func,Result}</c><br></br>
	   <c>What = tc_user_skip, Data = {Mod,Func,Comment}</c><br></br>
	   <c>What = tc_auto_skip, Data = {Mod,Func,Comment}</c></p>
      </desc>
    </func>
    <func>
      <name>error_notification(Mod, Func, Args, Error) -> ok</name>
      <fsummary>Inform framework of crashing testcase or configuration function.</fsummary>
      <type>
        <v>Mod = atom()</v>
	<d>Test suite name.</d>
        <v>Func = atom()</v>
	<d>Name of test case or configuration function.</d>
        <v>Args = [tuple()]</v>
	<d>Normally Args = [Config]</d>
        <v>Error = {Reason,Location}</v>
	<v>Reason = term()</v>
	<d>Reason for termination.</d>
	<v>Location = unknown | [{Mod,Func,Line}]</v>
	<d>Last known position in Mod before termination.</d>
        <v>Line = integer()</v>
	<d>Line number in file Mod.erl.</d> 
      </type>
      <desc>
        <p>This function is called as the result of function <c>Mod:Func</c> failing
	  with Reason at Location. The function is intended mainly to aid
	  specific logging or error handling in the framework application. Note
	  that for Location to have relevant values (i.e. other than unknown), 
	  the <c>line</c> macro or <c>test_server_line</c> parse transform must 
	  be used. For details, please see the section about test suite line numbers
	  in the <c>test_server</c> reference manual page.</p>
      </desc>
    </func>
    <func>
      <name>warn(What) -> boolean()</name>
      <fsummary>Ask framework if test server should issue a warning for What.</fsummary>
      <type>
        <v>What = processes | nodes</v>
      </type>
      <desc>
        <p>The test server checks the number of processes and nodes
          before and after the test is executed. This function is a
          question to the framework if the test server should warn when
          the number of processes or nodes has changed during the test
          execution. If <c>true</c> is returned, a warning will be written
          in the test case minor log file.</p>
      </desc>
    </func>
    <func>
      <name>target_info() -> InfoStr</name>
      <fsummary>Print info about the target system to the test case log.</fsummary>
      <type>
        <v>InfoStr = string() | ""</v>
      </type>
      <desc>
        <p>The test server will ask the framework for information about
	  the test target system and print InfoStr in the test case
	  log file below the host information.</p>
      </desc>
    </func>
  </funcs>
</erlref>