1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
26
<title>test_server</title>
27
<prepared>Siri Hansen</prepared>
28
<responsible></responsible>
34
<file>test_server_ref.sgml</file>
36
<module>test_server</module>
37
<modulesummary>This module provides support for test suite authors.</modulesummary>
39
<p>The <c>test_server</c> module aids the test suite author by providing
40
various support functions. The supported functionality includes:
42
<list type="bulleted">
43
<item>Logging and timestamping
45
<item>Capturing output to stdout
47
<item>Retrieving and flushing the message queue of a process
49
<item>Watchdog timers, process sleep, time measurement and unit
52
<item>Private scratch directory for all test suites
54
<item>Start and stop of slave- or peer nodes</item>
56
<p>For more information on how to write test cases and for
57
examples, please see the Test Server User's Guide.
62
<title>TEST SUITE SUPPORT FUNCTIONS</title>
63
<p>The following functions are supposed to be used inside a test
69
<name>os_type() -> OSType</name>
70
<fsummary>Returns the OS type of the target node</fsummary>
72
<v>OSType = term()</v>
73
<d>This is the same as returned from <c>os:type/0</c></d>
76
<p>This function can be called on controller or target node, and
77
it will always return the OS type of the target node.</p>
82
<name>fail(Reason)</name>
83
<fsummary>Makes the test case fail.</fsummary>
85
<v>Reason = term()</v>
86
<d>The reason why the test case failed.</d>
89
<p>This will make the test suite fail with a given reason, or
90
with <c>suite_failed</c> if no reason was given. Use this
91
function if you want to terminate a test case, as this will
92
make it easier to read the log- and HTML files. <c>Reason</c>
93
will appear in the comment field in the HTML log.</p>
97
<name>timetrap(Timout) -> Handle</name>
100
<v>Timeout = integer() | {hours,H} | {minutes,M} | {seconds,S}</v>
101
<v>H = M = S = integer()</v>
103
<d>The process that is to be timetrapped (<c>self()</c>by default)</d>
106
<p>Sets up a time trap for the current process. An expired
107
timetrap kills the process with reason
108
<c>timetrap_timeout</c>. The returned handle is to be given
109
as argument to <c>timetrap_cancel</c> before the timetrap
110
expires. If <c>Timeout</c> is an integer, it is expected to
113
<p>If the current process is trapping exits, it will not be killed
114
by the exit signal with reason <c>timetrap_timeout</c>.
115
If this happens, the process will be sent an exit signal
116
with reason <c>kill</c> 10 seconds later which will kill the
117
process. Information about the timetrap timeout will in
118
this case not be found in the test logs. However, the
119
error_logger will be sent a warning.</p>
124
<name>timetrap_cancel(Handle) -> ok</name>
125
<fsummary>Cancels a timetrap.</fsummary>
127
<v>Handle = term()</v>
128
<d>Handle returned from <c>timetrap</c></d>
131
<p>This function cancels a timetrap. This must be done before
132
the timetrap expires.</p>
136
<name>timetrap_scale_factor() -> ScaleFactor</name>
137
<fsummary>Returns the scale factor for timeouts.</fsummary>
139
<v>ScaleFactor = integer()</v>
142
<p>This function returns the scale factor by which all timetraps
143
are scaled. It is normally 1, but can be greater than 1 if
144
the test_server is running <c>cover</c>, using a larger amount of
145
scheduler threads than the amount of logical processors on the
146
system, running under purify, valgrind or in a debug-compiled
147
emulator. The scale factor can be used if you need to scale you
148
own timeouts in test cases with same factor as the test_server
153
<name>sleep(MSecs) -> ok</name>
154
<fsummary>Suspens the calling task for a specified time.</fsummary>
156
<v>MSecs = integer() | float() | infinity</v>
157
<d>The number of milliseconds to sleep</d>
160
<p>This function suspends the calling process for at least the
161
supplied number of milliseconds. There are two major reasons
162
why you should use this function instead of
163
<c>timer:sleep</c>, the first being that the module
164
<c>timer</c> may be unavaliable at the time the test suite is
165
run, and the second that it also accepts floating point
170
<name>hours(N) -> MSecs</name>
171
<name>minutes(N) -> MSecs</name>
172
<name>seconds(N) -> MSecs</name>
173
<fsummary></fsummary>
176
<d>Value to convert to milliseconds.</d>
179
<p>Theese functions convert <c>N</c> number of hours, minutes
180
or seconds into milliseconds.
182
<p>Use this function when you want to
183
<c>test_server:sleep/1</c> for a number of seconds, minutes or
188
<name>format(Format) -> ok</name>
189
<name>format(Format, Args)</name>
190
<name>format(Pri,Format)</name>
191
<name>format(Pri, Format, Args)</name>
192
<fsummary></fsummary>
194
<v>Format = string()</v>
195
<d>Format as described for <c>io_:format</c>.</d>
197
<d>List of arguments to format.</d>
200
<p>Formats output just like <c>io:format</c> but sends the
201
formatted string to a logfile. If the urgency value,
202
<c>Pri</c>, is lower than some threshold value, it will also
203
be written to the test person's console. Default urgency is
204
50, default threshold for display on the console is 1.
206
<p>Typically, the test person don't want to see everything a
207
test suite outputs, but is merely interested in if the test
208
cases succeeded or not, wich the test server tells him. If he
209
would like to see more, he could manually change the threshold
210
values by using the <c>test_server_ctrl:set_levels/3</c>
215
<name>capture_start() -> ok</name>
216
<name>capture_stop() -> ok</name>
217
<name>capture_get() -> list()</name>
218
<fsummary>Captures all output to stdout for a process.</fsummary>
220
<p>These functions makes it possible to capture all output to
221
stdout from a process started by the test suite. The list of
222
characters captured can be purged by using <c>capture_get</c>.</p>
226
<name>messages_get() -> list()</name>
227
<fsummary>Empty the message queue.</fsummary>
229
<p>This function will empty and return all the messages
230
currently in the calling process' message queue.</p>
234
<name>timecall(M, F, A) -> {Time, Value}</name>
235
<fsummary>Measures the time needed to call a function.</fsummary>
238
<d>The name of the module where the function resides.</d>
240
<d>The name of the function to call in the module.</d>
242
<d>The arguments to supplu the called function.</d>
243
<v>Time = integer()</v>
244
<d>The number of seconds it took to call the function.</d>
245
<v>Value = term()</v>
246
<d>Value returned from the called function.</d>
249
<p>This function measures the time (in seconds) it takes to
250
call a certain function. The function call is <em>not</em>
251
caught within a catch.</p>
255
<name>do_times(N, M, F, A) -> ok</name>
256
<name>do_times(N, Fun)</name>
257
<fsummary>Calls MFA or Fun N times.</fsummary>
260
<d>Number of times to call MFA.</d>
262
<d>Module name where the function resides.</d>
264
<d>Function name to call.</d>
266
<d>Arguments to M:F.</d>
269
<p>Calls MFA or Fun N times. Useful for extensive testing of a
270
sensitive function.</p>
274
<name>m_out_of_n(M, N, Fun) -> ok | exit({m_out_of_n_failed, {R,left_to_do}}</name>
275
<fsummary>Fault tolerant <c>do_times</c>.</fsummary>
278
<d>Number of times to call the Fun.</d>
280
<d>Number of times to require a successful return.</d>
283
<p>Repeatedly evaluates the given function until it succeeds
284
(doesn't crash) M times. If, after N times, M successful
285
attempts have not been accomplished, the process crashes with
286
reason {m_out_of_n_failed, {R,left_to_do}}, where R indicates
287
how many cases that was still to be successfully completed.
291
<p><c>m_out_of_n(1,4,fun() -> tricky_test_case() end)</c> <br></br>
292
Tries to run tricky_test_case() up to 4 times, and is
293
happy if it succeeds once.
295
<p><c>m_out_of_n(7,8,fun() -> clock_sanity_check() end)</c> <br></br>
296
Tries running clock_sanity_check() up to 8 times,and
297
allows the function to fail once. This might be useful if
298
clock_sanity_check/0 is known to fail if the clock crosses an
299
hour boundary during the test (and the up to 8 test runs could
300
never cross 2 boundaries)</p>
304
<name>call_crash(M, F, A) -> Result</name>
305
<name>call_crash(Time, M, F, A) -> Result</name>
306
<name>call_crash(Time, Crash, M, F, A) -> Result</name>
307
<fsummary>Calls MFA and succeeds if it crashes.</fsummary>
309
<v>Result = ok | exit(call_crash_timeout) | exit({wrong_crash_reason, Reason})</v>
310
<v>Crash = term()</v>
311
<d>Crash return from the function.</d>
312
<v>Time = integer()</v>
313
<d>Timeout in milliseconds.</d>
315
<d>Module name where the function resides.</d>
317
<d>Function name to call.</d>
319
<d>Arguments to M:F.</d>
322
<p>Spawns a new process that calls MFA. The call is considered
323
successful if the call crashes with the gives reason
324
(<c>Crash</c>) or any reason if not specified. The call must
325
terminate within the given time (default <c>infinity</c>), or
326
it is considered a failure.</p>
330
<name>temp_name(Stem) -> Name</name>
331
<fsummary>Returns a unique filename.</fsummary>
333
<v>Stem = string()</v>
336
<p>Returns a unique filename starting with <c>Stem</c> with
337
enough extra characters appended to make up a unique
338
filename. The filename returned is guaranteed not to exist in
339
the filesystem at the time of the call.</p>
343
<name>break(Comment) -> ok</name>
344
<fsummary>Cancel all timetraps and wait for call to continue/0.</fsummary>
346
<v>Comment = string()</v>
349
<p><c>Comment</c> is a string which will be written in
350
the shell, e.g. explaining what to do.</p>
351
<p>This function will cancel all timetraps and pause the
352
execution of the test case until the user executes the
353
<c>continue/0</c> function. It gives the user the opportunity
354
to interact with the erlang node running the tests, e.g. for
355
debugging purposes or for manually executing a part of the
357
<p>When the <c>break/1</c> function is called, the shell will
358
look something like this:</p>
359
<code type="none"><![CDATA[
360
--- SEMIAUTOMATIC TESTING ---
361
The test case executes on process <0.51.0>
364
"Here is a comment, it could e.g. instruct to pull out a card"
367
-----------------------------
369
Continue with --> test_server:continue(). ]]></code>
370
<p>The user can now interact with the erlang node, and when
371
ready call <c>test_server:continue().</c></p>
372
<p>Note that this function can not be used if the test is
373
executed with <c>ts:run/0/1/2/3/4</c> in <c>batch</c> mode.</p>
377
<name>continue() -> ok</name>
378
<fsummary>Continue after break/1.</fsummary>
380
<p>This function must be called in order to continue after a
381
test case has called <c>break/1</c>.</p>
385
<name>run_on_shielded_node(Fun, CArgs) -> term()</name>
386
<fsummary>Execute a function a shielded node.</fsummary>
388
<v>Fun = function() (arity 0)</v>
389
<d>Function to execute on the shielded node.</d>
390
<v>CArg = string()</v>
391
<d>Extra command line arguments to use when starting the shielded node.</d>
394
<p><c>Fun</c> is executed in a process on a temporarily created
395
hidden node with a proxy for communication with the test server
396
node. The node is called a shielded node (should have been called
397
a shield node). If <c>Fun</c> is successfully executed, the result
398
is returned. A peer node (see <c>start_node/3</c>) started from
399
the shielded node will be shielded from test server node, i.e.
400
they will not be aware of eachother. This is useful when you want
401
to start nodes from earlier OTP releases than the OTP release of
402
the test server node.</p>
403
<p>Nodes from an earlier OTP release can normally not be started
404
if the test server hasn't been started in compatibility mode
405
(see the <c>+R</c> flag in the <c>erl(1)</c> documentation) of
406
an earlier release. If a shielded node is started in compatibility
407
mode of an earlier OTP release than the OTP release of the test
408
server node, the shielded node can start nodes of an earlier OTP
411
<p>You <em>must</em> make sure that nodes started by the shielded
412
node never communicate directly with the test server node.</p>
415
<p>Slave nodes always communicate with the test server node;
416
therefore, <em>never</em> start <em>slave nodes</em> from the
417
shielded node, <em>always</em> start <em>peer nodes</em>.</p>
422
<name>start_node(Name, Type, Options) -> {ok, Node} | {error, Reason}</name>
423
<fsummary>Start a node.</fsummary>
425
<v>Name = atom() | string()</v>
426
<d>Name of the slavenode to start (as given to -sname or -name)</d>
427
<v>Type = slave | peer</v>
428
<d>The type of node to start.</d>
429
<v>Options = [{atom(), term()]</v>
430
<d>Tuplelist of options</d>
433
<p>This functions starts a node, possibly on a remote machine,
434
and guarantees cross architecture transparency. Type is set to
435
either <c>slave</c> or <c>peer</c>.
437
<p><c>slave</c> means that the new node will have a master,
438
i.e. the slave node will terminate if the master terminates,
439
TTY output produced on the slave will be sent back to the
440
master node and file I/O is done via the master. The master is
441
normally the target node unless the target is itself a slave.
443
<p><c>peer</c> means that the new node is an independent node
446
<p><c>Options</c> is a tuplelist wich can contain one or more
450
<tag><c>{remote, true}</c></tag>
451
<item>Start the node on a remote host. If not specified, the
452
node will be started on the local host (with some
453
exceptions, as for the case of VxWorks, where
454
all nodes are started on a remote host). Test cases that
455
require a remote host will fail with a reasonable comment if
456
no remote hosts are availiable at the time they are run.
458
<tag><c>{args, Arguments}</c></tag>
459
<item>Arguments passed directly to the node. This is
460
typically a string appended to the command line.
462
<tag><c>{wait, false}</c></tag>
463
<item>Don't wait until the node is up. By default, this
464
function does not return until the node is up and running,
465
but this option makes it return as soon as the node start
468
Only valid for peer nodes
470
<tag><c>{fail_on_error, false}</c></tag>
471
<item>Returns <c>{error, Reason}</c> rather than failing the
474
Only valid for peer nodes. Note that slave nodes always
475
act as if they had <c>fail_on_error=false</c></item>
476
<tag><c>{erl, ReleaseList}</c></tag>
477
<item>Use an Erlang emulator determined by ReleaseList when
478
starting nodes, instead of the same emulator as the test
479
server is running. ReleaseList is a list of specifiers,
480
where a specifier is either {release, Rel}, {prog, Prog}, or
481
'this'. Rel is either the name of a release, e.g., "r12b_patched"
482
or 'latest'. 'this' means using the same emulator as the test
483
server. Prog is the name of an emulator executable. If the
484
list has more than one element, one of them is picked
485
randomly. (Only works on Solaris, and the test server gives
486
warnings when it notices that nodes are not of the same
491
When specififying this option to run a previous release, use
492
<c>is_release_available/1</c> function to test if the given
493
release is available and skip the test case if not.
497
In order to avoid compatibility problems (may not appear right
498
away), use a shielded node (see <c>run_on_shielded_node/2</c>)
499
when starting nodes from different OTP releases than the test
502
<tag><c>{cleanup, false}</c></tag>
503
<item>Tells the test server not to kill this node if it is
504
still alive after the test case is completed. This is useful
505
if the same node is to be used by a group of test cases.
507
<tag><c>{env, Env}</c></tag>
508
<item><c>Env</c> should be a list of tuples <c>{Name, Val}</c>,
509
where <c>Name</c> is the name of an environment variable, and
510
<c>Val</c> is the value it is to have in the started node.
511
Both <c>Name</c> and <c>Val</c> must be strings. The one
512
exception is <c>Val</c> being the atom <c>false</c> (in
513
analogy with <c>os:getenv/1</c>), which removes the
514
environment variable. Only valid for peer nodes. Not
515
available on VxWorks.</item>
520
<name>stop_node(NodeName) -> bool()</name>
521
<fsummary>Stops a node</fsummary>
523
<v>NodeName = term()</v>
524
<d>Name of the node to stop</d>
527
<p>This functions stops a node previously started with
528
<c>start_node/3</c>. Use this function to stop any node you
529
start, or the test server will produce a warning message in
530
the test logs, and kill the nodes automatically unless it was
531
started with the <c>{cleanup, false}</c> option.</p>
535
<name>is_commercial() -> bool()</name>
536
<fsummary>Tests whether the emulator is commercially supported</fsummary>
538
<p>This function test whether the emulator is commercially supported
539
emulator. The tests for a commercially supported emulator could be more
540
stringent (for instance, a commercial release should always contain
541
documentation for all applications).</p>
546
<name>is_release_available(Release) -> bool()</name>
547
<fsummary>Tests whether a release is available</fsummary>
549
<v>Release = string() | atom()</v>
550
<d>Release to test for</d>
553
<p>This function test whether the release given by
554
<c>Release</c> (for instance, "r12b_patched") is available
555
on the computer that the test_server controller is running on.
556
Typically, you should skip the test case if not.</p>
557
<p>Caution: This function may not be called from the <c>suite</c>
558
clause of a test case, as the test_server will deadlock.</p>
562
<name>is_native(Mod) -> bool()</name>
563
<fsummary>Checks wether the module is natively compiled or not</fsummary>
569
<p>Checks wether the module is natively compiled or not</p>
573
<name>app_test(App) -> ok | test_server:fail()</name>
574
<name>app_test(App,Mode)</name>
575
<fsummary>Checks an applications .app file for obvious errors</fsummary>
578
<d>The name of the application to test</d>
579
<v>Mode = pedantic | tolerant</v>
580
<d>Default is pedantic</d>
583
<p>Checks an applications .app file for obvious errors.
584
The following is checked:
586
<list type="bulleted">
587
<item>required fields
589
<item>that all modules specified actually exists
591
<item>that all requires applications exists
593
<item>that no module included in the application has export_all
595
<item>that all modules in the ebin/ dir is included (If
596
<c>Mode==tolerant</c> this only produces a warning, as all
597
modules does not have to be included)</item>
602
<name>comment(Comment) -> ok</name>
603
<fsummary>Print a comment on the HTML result page</fsummary>
605
<v>Comment = string()</v>
608
<p>The given String will occur in the comment field of the
609
table on the HTML result page. If called several times, only
610
the last comment is printed. comment/1 is also overwritten by
611
the return value {comment,Comment} from a test case or by
612
fail/1 (which prints Reason as a comment).</p>
618
<title>TEST SUITE EXPORTS</title>
619
<p>The following functions must be exported from a test suite
625
<name>all(suite) -> TestSpec | {skip, Comment}</name>
626
<fsummary>Returns the module's test specification</fsummary>
628
<v>TestSpec = list()</v>
629
<v>Comment = string()</v>
630
<d>This comment will be printed on the HTML result page</d>
633
<p>This function must return the test specification for the
634
test suite module. The syntax of a test specification is
635
described in the Test Server User's Guide.</p>
639
<name>init_per_suite(Config0) -> Config1 | {skip, Comment}</name>
640
<fsummary>Test suite initiation</fsummary>
642
<v>Config0 = Config1 = [tuple()]</v>
643
<v>Comment = string()</v>
644
<d>Describes why the suite is skipped</d>
647
<p>This function is called before all other test cases in the
648
suite. <c>Config</c> is the configuration which can be modified
649
here. Whatever is returned from this function is given as
650
<c>Config</c> to the test cases.
652
<p>If this function fails, all test cases in the suite will be
657
<name>end_per_suite(Config) -> void()</name>
658
<fsummary>Test suite finalization</fsummary>
660
<v>Config = [tuple()]</v>
663
<p>This function is called after the last test case in the
664
suite, and can be used to clean up whatever the test cases
665
have done. The return value is ignored.</p>
669
<name>init_per_testcase(Case, Config0) -> Config1 | {skip, Comment}</name>
670
<fsummary>Test case initiation</fsummary>
673
<v>Config0 = Config1 = [tuple()]</v>
674
<v>Comment = string()</v>
675
<d>Describes why the test case is skipped</d>
678
<p>This function is called before each test case. The
679
<c>Case</c> argument is the name of the test case, and
680
<c>Config</c> is the configuration which can be modified
681
here. Whatever is returned from this function is given as
682
<c>Config</c> to the test case.</p>
686
<name>end_per_testcase(Case, Config) -> void()</name>
687
<fsummary>Test case finalization</fsummary>
690
<v>Config = [tuple()]</v>
693
<p>This function is called after each test case, and can be
694
used to clean up whatever the test case has done. The return
695
value is ignored.</p>
699
<name>Case(doc) -> [Decription]</name>
700
<name>Case(suite) -> [] | TestSpec | {skip, Comment}</name>
701
<name>Case(Config) -> {skip, Comment} | {comment, Comment} | Ok</name>
702
<fsummary>A test case</fsummary>
704
<v>Description = string()</v>
705
<d>Short description of the test case</d>
706
<v>TestSpec = list()</v>
707
<v>Comment = string()</v>
708
<d>This comment will be printed on the HTML result page</d>
710
<v>Config = [tuple()]</v>
711
<d>Elements from the Config parameter can be read with the ?config macro, see section about test suite support macros</d>
714
<p>The <em>documentation clause</em> (argument <c>doc</c>) can
715
be used for automatic generation of test documentation or test
718
<p>The <em>specification clause</em> (argument <c>spec</c>)
719
shall return an empty list, the test specification for the
720
test case or <c>{skip,Comment}</c>. The syntax of a test
721
specification is described in the Test Server User's Guide.
723
<p><em>Note that the specification clause always is executed on the controller host.</em></p>
724
<p>The <em>execution clause</em> (argument <c>Config</c>) is
725
only called if the specification clause returns an empty list.
726
The execution clause is the real test case. Here you must call
727
the functions you want to test, and do whatever you need to
728
check the result. If someting fails, make sure the process
729
crashes or call <c>test_server:fail/0/1</c> (which also will
730
cause the process to crash).
732
<p>You can return <c>{skip,Comment}</c> if you decide not to
733
run the test case after all, e.g. if it is not applicable on
736
<p>You can return <c>{comment,Comment}</c> if you wish to
737
print some information in the 'Comment' field on the HTML
740
<p>If the execution clause returns anything else, it is
741
considered a success, unless it is <c>{'EXIT',Reason}</c> or
742
<c>{'EXIT',Pid,Reason}</c> which can't be distinguished from a
743
crash, and thus will be considered a failure.
745
<p>A <em>conf test case</em> is a group of test cases with an
746
init and a cleanup function. The init and cleanup functions
747
are also test cases, but they have spcial rules:</p>
748
<list type="bulleted">
749
<item>They do not need a specification clause.</item>
750
<item>They must always have the execution clause.</item>
751
<item>They must return the <c>Config</c> parameter, a modified
752
version of it or <c>{skip,Comment}</c> from the execution clause.</item>
753
<item><c>init_per_testcase</c> and <c>end_per_testcase</c> are
754
not called before and after these functions.</item>
761
<title>TEST SUITE LINE NUMBERS</title>
762
<p>If a test case fails, the test server can report the exact line
763
number at which it failed. There are two ways of doing this,
764
either by using the <c>line</c> macro or by using the
765
<c>test_server_line</c> parse transform.
767
<p>The <c>line</c> macro is described under TEST SUITE SUPPORT
768
MACROS below. The <c>line</c> macro will only report the last line
769
executed when a test case failed.
771
<p>The <c>test_server_line</c> parse transform is activated by
772
including the headerfile <c>test_server_line.hrl</c> in the test
773
suite. When doing this, it is important that the
774
<c>test_server_line</c> module is in the code path of the erlang
775
node compiling the test suite. The parse transform will report a
776
history of a maximum of 10 lines when a test case
777
fails. Consecutive lines in the same function are not shown.
779
<p>The attribute <c>-no_lines(FuncList).</c> can be used in the
780
test suite to exclude specific functions from the parse
781
transform. This is necessary e.g. for functions that are executed
782
on old (i.e. <R10B) OTP releases. <c>FuncList = [{Func,Arity}]</c>.
784
<p>If both the <c>line</c> macro and the parse tranform is used in
785
the same module, the parse transform will overrule the macro.
790
<title>TEST SUITE SUPPORT MACROS</title>
791
<p>There are some macros defined in the <c>test_server.hrl</c>
792
that are quite useful for test suite programmers:
794
<p>The <em>line</em> macro, is quite
795
essential when writing test cases. It tells the test server
796
exactly what line of code that is being executed, so that it can
797
report this line back if the test case fails. Use this macro at
798
the beginning of every test case line of code.
800
<p>The <em>config</em> macro, is used to
801
retrieve information from the <c>Config</c> variable sent to all
802
test cases. It is used with two arguments, where the first is the
803
name of the configuration variable you wish to retrieve, and the
804
second is the <c>Config</c> variable supplied to the test case
805
from the test server.
807
<p>Possible configuration variables include:</p>
808
<list type="bulleted">
809
<item><c>data_dir</c> - Data file directory.</item>
810
<item><c>priv_dir</c> - Scratch file directory.</item>
811
<item><c>nodes</c> - Nodes specified in the spec file</item>
812
<item><c>nodenames</c> - Generated nodenames.</item>
813
<item>Whatever added by conf test cases or
814
<c>init_per_testcase/2</c></item>
816
<p>Examples of the <c>line</c> and <c>config</c> macros can be
817
seen in the Examples chapter in the user's guide.
819
<p>If the <c>line_trace</c> macro is defined, you will get a
820
timestamp (<c>erlang:now()</c>) in your minor log for each
821
<c>line</c> macro in your suite. This way you can at any time see
822
which line is currently being executed, and when the line was
825
<p>The <c>line_trace</c> macro can also be used together with the
826
<c>test_server_line</c> parse tranform described above. A
827
timestamp will then be written for each line in the suite, except
828
for functions stated in the <c>-no_lines</c> attribute.
830
<p>The <c>line_trace</c> macro can e.g. be defined as a compile
833
<c>erlc -W -Dline_trace my_SUITE.erl</c></p>
added
removed
lib/test_server/doc/src/test_server.xml
