1ct(3)                      Erlang Module Definition                      ct(3)
2
3
4

NAME

6       ct - Main user interface for the Common Test framework.
7

DESCRIPTION

9       Main user interface for the Common Test framework.
10
11       This module implements the command-line interface for running tests and
12       basic functions for Common Test case issues, such as configuration  and
13       logging.
14
15       Test Suite Support Macros
16
17       The  config  macro  is  defined  in ct.hrl. This macro is to be used to
18       retrieve information from the Config variable sent to all  test  cases.
19       It  is used with two arguments; the first is the name of the configura‐
20       tion variable to retrieve, the second is the Config  variable  supplied
21       to the test case.
22
23       Possible configuration variables include:
24
25         * data_dir - Data file directory
26
27         * priv_dir - Scratch file directory
28
29         * Whatever  added  by  init_per_suite/1 or init_per_testcase/2 in the
30           test suite.
31

DATA TYPES

33         handle() = pid():
34           The identity (handle) of a connection.
35
36         config_key() = atom():
37           A configuration key which exists in a configuration file
38
39         target_name() = atom():
40           A name and association to configuration data introduced  through  a
41           require   statement,  or  a  call  to  ct:require/2,  for  example,
42           ct:require(mynodename,{node,[telnet]}).
43
44         key_or_name() = config_key() | target_name():
45
46
47         conn_log_options() = [conn_log_option()]:
48           Options that can be given to the cth_conn_log hook, which  is  used
49           for  logging  of NETCONF and Telnet connections. See ct_netconfc or
50           ct_telnet for description and examples of how to use this hook.
51
52         conn_log_option()        =        {log_type,conn_log_type()}        |
53         {hosts,[key_or_name()]}:
54
55
56         conn_log_type() = raw | pretty | html | silent:
57
58
59         conn_log_mod() = ct_netconfc | ct_telnet:
60
61

EXPORTS

63       abort_current_testcase(Reason) -> ok | {error, ErrorReason}
64
65              Types:
66
67                 Reason = term()
68                 ErrorReason = no_testcase_running | parallel_group
69
70              Aborts  the  currently  executing  test case. The user must know
71              with certainty which test case is currently executing. The func‐
72              tion  is  therefore  only  safe to call from a function that has
73              been called (or synchronously invoked) by the test case.
74
75              Reason, the reason for aborting the test case, is printed in the
76              test case log.
77
78       add_config(Callback, Config) -> ok | {error, Reason}
79
80              Types:
81
82                 Callback = atom()
83                 Config = string()
84                 Reason = term()
85
86              Loads  configuration variables using the specified callback mod‐
87              ule and configuration string.  The  callback  module  is  to  be
88              either  loaded or present in the code part. Loaded configuration
89              variables can later be  removed  using  function  ct:remove_con‐
90              fig/2.
91
92       break(Comment) -> ok | {error, Reason}
93
94              Types:
95
96                 Comment = string()
97                 Reason  = {multiple_cases_running, TestCases} | 'enable break
98                 with release_shell option'
99                 TestCases = [atom()]
100
101              Cancels any active timetrap and pauses the execution of the cur‐
102              rent  test  case  until  the user calls function continue/0. The
103              user can then interact with the Erlang node running  the  tests,
104              for  example, for debugging purposes or for manually executing a
105              part of the  test  case.  If  a  parallel  group  is  executing,
106              ct:break/2 is to be called instead.
107
108              A  cancelled timetrap is not automatically reactivated after the
109              break, but must be started exlicitly with ct:timetrap/1.
110
111              In order for the break/continue functionality  to  work,  Common
112              Test  must  release the shell process controlling stdin. This is
113              done by setting start option release_shell to true. For details,
114              see  section  Running  Tests  from  the  Erlang Shell or from an
115              Erlang Program in the User's Guide.
116
117       break(TestCase, Comment) -> ok | {error, Reason}
118
119              Types:
120
121                 TestCase = atom()
122                 Comment = string()
123                 Reason =  'test  case  not  running'  |  'enable  break  with
124                 release_shell option'
125
126              Works  the  same way as ct:break/1, only argument TestCase makes
127              it possible to pause a test case executing in a parallel  group.
128              Function  ct:continue/1  is  to  be  used to resume execution of
129              TestCase.
130
131              For details, see ct:break/1.
132
133       capture_get() -> ListOfStrings
134
135              Types:
136
137                 ListOfStrings = [string()]
138
139              Equivalent to ct:capture_get([default]).
140
141       capture_get(ExclCategories) -> ListOfStrings
142
143              Types:
144
145                 ExclCategories = [atom()]
146                 ListOfStrings = [string()]
147
148              Returns and purges the list of text strings buffered during  the
149              latest  session of capturing printouts to stdout. Log categories
150              that are to be ignored in ListOfStrings can  be  specified  with
151              ExclCategories.  If  ExclCategories  =  [],  no  filtering takes
152              place.
153
154              See also ct:capture_start/0, ct:capture_stop/0, ct:log/3.
155
156       capture_start() -> ok
157
158              Starts capturing all text strings printed to stdout during  exe‐
159              cution of the test case.
160
161              See also ct:capture_get/1, ct:capture_stop/0.
162
163       capture_stop() -> ok
164
165              Stops  capturing  text  strings  (a  session  started  with cap‐
166              ture_start/0).
167
168              See also ct:capture_get/1, ct:capture_start/0.
169
170       comment(Comment) -> ok
171
172              Types:
173
174                 Comment = term()
175
176              Prints the specified Comment in the comment field in  the  table
177              on the test suite result page.
178
179              If  called  several times, only the last comment is printed. The
180              test case return value {comment,Comment} overwrites  the  string
181              set by this function.
182
183       comment(Format, Args) -> ok
184
185              Types:
186
187                 Format = string()
188                 Args = list()
189
190              Prints the formatted string in the comment field in the table on
191              the test suite result page.
192
193              Arguments Format and Args are used in a call to  io_lib:format/2
194              to  create the comment string. The behavior of comment/2 is oth‐
195              erwise the same as function ct:comment/1.
196
197       continue() -> ok
198
199              This function must be called to continue after a test case  (not
200              executing in a parallel group) has called function ct:break/1.
201
202       continue(TestCase) -> ok
203
204              Types:
205
206                 TestCase = atom()
207
208              This  function  must be called to continue after a test case has
209              called ct:break/2. If the paused test case,  TestCase,  executes
210              in a parallel group, this function, rather than continue/0, must
211              be used to let the test case proceed.
212
213       decrypt_config_file(EncryptFileName, TargetFileName) ->  ok  |  {error,
214       Reason}
215
216              Types:
217
218                 EncryptFileName = string()
219                 TargetFileName = string()
220                 Reason = term()
221
222              Decrypts     EncryptFileName,    previously    generated    with
223              ct:encrypt_config_file/2,3. The original file contents is  saved
224              in the target file. The encryption key, a string, must be avail‐
225              able in a text file named .ct_config.crypt, either in  the  cur‐
226              rent  directory,  or  the  home  directory  of  the  user (it is
227              searched for in that order).
228
229       decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -> ok |
230       {error, Reason}
231
232              Types:
233
234                 EncryptFileName = string()
235                 TargetFileName = string()
236                 KeyOrFile = {key, string()} | {file, string()}
237                 Reason = term()
238
239              Decrypts     EncryptFileName,    previously    generated    with
240              ct:encrypt_config_file/2,3. The original file contents is  saved
241              in  the  target  file.  The key must have the same value as that
242              used for encryption.
243
244       encrypt_config_file(SrcFileName, EncryptFileName) -> ok | {error,  Rea‐
245       son}
246
247              Types:
248
249                 SrcFileName = string()
250                 EncryptFileName = string()
251                 Reason = term()
252
253              Encrypts  the  source configuration file with DES3 and saves the
254              result in file EncryptFileName.  The  key,  a  string,  must  be
255              available  in  a text file named .ct_config.crypt, either in the
256              current directory, or the home directory  of  the  user  (it  is
257              searched for in that order).
258
259              For  information  about using encrypted configuration files when
260              running tests, see section Encrypted Configuration Files in  the
261              User's Guide.
262
263              For  details  on  DES3  encryption/decryption,  see  application
264              Crypto.
265
266       encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile)  ->  ok  |
267       {error, Reason}
268
269              Types:
270
271                 SrcFileName = string()
272                 EncryptFileName = string()
273                 KeyOrFile = {key, string()} | {file, string()}
274                 Reason = term()
275
276              Encrypts  the  source configuration file with DES3 and saves the
277              result in the target file EncryptFileName. The encryption key to
278              use  is either the value in {key,Key} or the value stored in the
279              file specified by {file,File}.
280
281              For information about using encrypted configuration  files  when
282              running  tests, see section Encrypted Configuration Files in the
283              User's Guide.
284
285              For  details  on  DES3  encryption/decryption,  see  application
286              Crypto.
287
288       fail(Reason) -> ok
289
290              Types:
291
292                 Reason = term()
293
294              Terminates a test case with the specified error Reason.
295
296       fail(Format, Args) -> ok
297
298              Types:
299
300                 Format = string()
301                 Args = list()
302
303              Terminates a test case with an error message specified by a for‐
304              mat  string  and  a  list  of  values  (used  as  arguments   to
305              io_lib:format/2).
306
307       get_config(Required) -> Value
308
309              Equivalent to ct:get_config(Required, undefined, []).
310
311       get_config(Required, Default) -> Value
312
313              Equivalent to ct:get_config(Required, Default, []).
314
315       get_config(Required, Default, Opts) -> ValueOrElement
316
317              Types:
318
319                 Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, Sub‐
320                 Key, SubKey}
321                 KeyOrName = atom()
322                 SubKey = atom()
323                 Default = term()
324                 Opts = [Opt] | []
325                 Opt = element | all
326                 ValueOrElement = term() | Default
327
328              Reads configuration data values.
329
330              Returns the matching values or configuration elements,  given  a
331              configuration  variable  key  or its associated name (if one has
332              been specified with ct:require/2 or a require statement).
333
334              Example:
335
336              Given the following configuration file:
337
338               {unix,[{telnet,IpAddr},
339                      {user,[{username,Username},
340                             {password,Password}]}]}.
341
342              Then:
343
344               ct:get_config(unix,Default) -> [{telnet,IpAddr},
345                {user, [{username,Username}, {password,Password}]}]
346               ct:get_config({unix,telnet},Default) -> IpAddr
347               ct:get_config({unix,user,username},Default) -> Username
348               ct:get_config({unix,ftp},Default) -> Default
349               ct:get_config(unknownkey,Default) -> Default
350
351              If a configuration variable key has been associated with a  name
352              (by  ct:require/2  or a require statement), the name can be used
353              instead of the key to read the value:
354
355               ct:require(myuser,{unix,user}) -> ok.
356               ct:get_config(myuser,Default) -> [{username,Username}, {password,Password}]
357
358              If a configuration variable is defined in  multiple  files,  use
359              option  all  to  access  all  possible  values.  The  values are
360              returned in a list. The order of the elements corresponds to the
361              order that the configuration files were specified at startup.
362
363              If  configuration elements (key-value tuples) are to be returned
364              as result instead of values, use option  element.  The  returned
365              elements are then on the form {Required,Value}.
366
367              See   also   ct:get_config/1,   ct:get_config/2,   ct:require/1,
368              ct:require/2.
369
370       get_event_mgr_ref() -> EvMgrRef
371
372              Types:
373
374                 EvMgrRef = atom()
375
376              Gets a reference to the Common Test event manager. The reference
377              can  be  used to, for example, add a user-specific event handler
378              while tests are running.
379
380              Example:
381
382               gen_event:add_handler(ct:get_event_mgr_ref(), my_ev_h, [])
383
384       get_progname() -> string()
385
386              Returns the command used to start this Erlang instance. If  this
387              information  could  not  be  found, the string "no_prog_name" is
388              returned.
389
390       get_status() -> TestStatus | {error, Reason} | no_tests_running
391
392              Types:
393
394                 TestStatus = [StatusElem]
395                 StatusElem = {current, TestCaseInfo} | {successful,  Success‐
396                 ful} | {failed, Failed} | {skipped, Skipped} | {total, Total}
397                 TestCaseInfo = {Suite, TestCase} | [{Suite, TestCase}]
398                 Suite = atom()
399                 TestCase = atom()
400                 Successful = integer()
401                 Failed = integer()
402                 Skipped = {UserSkipped, AutoSkipped}
403                 UserSkipped = integer()
404                 AutoSkipped = integer()
405                 Total = integer()
406                 Reason = term()
407
408              Returns  status  of  ongoing  test.  The  returned list contains
409              information about which test case is executing (a list of  cases
410              when  a parallel test case group is executing), as well as coun‐
411              ters for successful, failed, skipped, and total  test  cases  so
412              far.
413
414       get_target_name(Handle) -> {ok, TargetName} | {error, Reason}
415
416              Types:
417
418                 Handle = handle()
419                 TargetName = target_name()
420
421              Returns  the  name  of  the target that the specified connection
422              belongs to.
423
424       get_testspec_terms() -> TestSpecTerms | undefined
425
426              Types:
427
428                 TestSpecTerms = [{Tag, Value}]
429                 Value = [term()]
430
431              Gets a list of all test specification terms  used  to  configure
432              and run this test.
433
434       get_testspec_terms(Tags) -> TestSpecTerms | undefined
435
436              Types:
437
438                 Tags = [Tag] | Tag
439                 Tag = atom()
440                 TestSpecTerms = [{Tag, Value}] | {Tag, Value}
441                 Value = [{Node, term()}] | [term()]
442                 Node = atom()
443
444              Reads one or more terms from the test specification used to con‐
445              figure and run this test. Tag is any  valid  test  specification
446              tag,  for example, label, config, or logdir. User-specific terms
447              are also available to read if option allow_user_terms is set.
448
449              All value tuples returned, except user terms, have the node name
450              as first element.
451
452              To read test terms, use Tag = tests (rather than suites, groups,
453              or cases). Value is then the list  of  all  tests  on  the  form
454              [{Node,Dir,[{TestSpec,GroupsAndCases1},...]},...],  where Group‐
455              sAndCases = [{Group,[Case]}] | [Case].
456
457       get_timetrap_info() -> {Time, {Scaling,ScaleVal}}
458
459              Types:
460
461                 Time = integer() | infinity
462                 Scaling = true | false
463                 ScaleVal = integer()
464
465              Reads information about the timetrap set for  the  current  test
466              case.  Scaling  indicates if Common Test will attempt to compen‐
467              sate timetraps automatically for runtime delays  introduced  by,
468              for example, tools like cover. ScaleVal is the value of the cur‐
469              rent scaling multipler (always 1 if scaling is  disabled).  Note
470              the Time is not the scaled result.
471
472       get_verbosity(Category) -> Level | undefined
473
474              Types:
475
476                 Category = default | atom()
477                 Level = integer()
478
479              This function returns the verbosity level for the specified log‐
480              ging category. See the  User's Guide for details. Use the  value
481              default to read the general verbosity level.
482
483       install(Opts) -> ok | {error, Reason}
484
485              Types:
486
487                 Opts = [Opt]
488                 Opt  =  {config,  ConfigFiles}  |  {event_handler, Modules} |
489                 {decrypt, KeyOrFile}
490                 ConfigFiles = [ConfigFile]
491                 ConfigFile = string()
492                 Modules = [atom()]
493                 KeyOrFile = {key, Key} | {file, KeyFile}
494                 Key = string()
495                 KeyFile = string()
496
497              Installs configuration files and event handlers.
498
499              Run this function once before the first test.
500
501              Example:
502
503               install([{config,["config_node.ctc","config_user.ctc"]}])
504
505              This function is automatically run by program ct_run.
506
507       listenv(Telnet) -> [Env]
508
509              Types:
510
511                 Telnet = term()
512                 Env = {Key, Value}
513                 Key = string()
514                 Value = string()
515
516              Performs command listenv on the specified Telnet connection  and
517              returns the result as a list of key-value pairs.
518
519       log(Format) -> ok
520
521              Equivalent to ct:log(default, 50, Format, [], []).
522
523       log(X1, X2) -> ok
524
525              Types:
526
527                 X1 = Category | Importance | Format
528                 X2 = Format | FormatArgs
529
530              Equivalent  to  ct:log(Category, Importance, Format, FormatArgs,
531              []).
532
533       log(X1, X2, X3) -> ok
534
535              Types:
536
537                 X1 = Category | Importance
538                 X2 = Importance | Format
539                 X3 = Format | FormatArgs | Opts
540
541              Equivalent to ct:log(Category, Importance,  Format,  FormatArgs,
542              Opts).
543
544       log(X1, X2, X3, X4) -> ok
545
546              Types:
547
548                 X1 = Category | Importance
549                 X2 = Importance | Format
550                 X3 = Format | FormatArgs
551                 X4 = FormatArgs | Opts
552
553              Equivalent  to  ct:log(Category, Importance, Format, FormatArgs,
554              Opts).
555
556       log(Category, Importance, Format, FormatArgs, Opts) -> ok
557
558              Types:
559
560                 Category = atom()
561                 Importance = integer()
562                 Format = string()
563                 FormatArgs = list()
564                 Opts = [Opt]
565                 Opt = {heading,string()} | no_css | esc_chars
566
567              Prints from a test case to the log file.
568
569              This function is meant for printing a  string  directly  from  a
570              test case to the test case log file.
571
572              Default  Category  is default, default Importance is ?STD_IMPOR‐
573              TANCE, and default value for FormatArgs is [].
574
575              For details on Category, Importance and the no_css  option,  see
576              section  Logging - Categories and Verbosity Levels in the User's
577              Guide.
578
579              Common Test will not escape special HTML characters (<, > and &)
580              in  the  text  printed  with this function, unless the esc_chars
581              option is used.
582
583       make_priv_dir() -> ok | {error, Reason}
584
585              Types:
586
587                 Reason = term()
588
589              If the test is started with option create_priv_dir set  to  man‐
590              ual_per_tc, in order for the test case to use the private direc‐
591              tory, it must first create it by calling this function.
592
593       notify(Name, Data) -> ok
594
595              Types:
596
597                 Name = atom()
598                 Data = term()
599
600              Sends an asynchronous notification of type Name with Datato  the
601              Common  Test  event  manager.  This  can  later be caught by any
602              installed event manager.
603
604              See also gen_event(3).
605
606       pal(Format) -> ok
607
608              Equivalent to ct:pal(default, 50, Format, [], []).
609
610       pal(X1, X2) -> ok
611
612              Types:
613
614                 X1 = Category | Importance | Format
615                 X2 = Format | FormatArgs
616
617              Equivalent to ct:pal(Category, Importance,  Format,  FormatArgs,
618              []).
619
620       pal(X1, X2, X3) -> ok
621
622              Types:
623
624                 X1 = Category | Importance
625                 X2 = Importance | Format
626                 X3 = Format | FormatArgs | Opts
627
628              Equivalent  to  ct:pal(Category, Importance, Format, FormatArgs,
629              Opts).
630
631       pal(X1, X2, X3, X4) -> ok
632
633              Types:
634
635                 X1 = Category | Importance
636                 X2 = Importance | Format
637                 X3 = Format | FormatArgs
638                 X4 = FormatArgs | Opts
639
640              Equivalent to ct:pal(Category, Importance,  Format,  FormatArgs,
641              Opts).
642
643       pal(Category, Importance, Format, FormatArgs, Opts) -> ok
644
645              Types:
646
647                 Category = atom()
648                 Importance = integer()
649                 Format = string()
650                 FormatArgs = list()
651                 Opts = [Opt]
652                 Opt = {heading,string()} | no_css
653
654              Prints and logs from a test case.
655
656              This  function  is meant for printing a string from a test case,
657              both to the test case log file and to the console.
658
659              Default Category is default, default Importance  is  ?STD_IMPOR‐
660              TANCE, and default value for FormatArgs is [].
661
662              For  details  on  Category and Importance, see section Logging -
663              Categories and Verbosity Levels in the User's Guide.
664
665              Note that special characters in the text (<, > and  &)  will  be
666              escaped  by  Common  Test  before the text is printed to the log
667              file.
668
669       parse_table(Data) -> {Heading, Table}
670
671              Types:
672
673                 Data = [string()]
674                 Heading = tuple()
675                 Table = [tuple()]
676
677              Parses the printout from an SQL table  and  returns  a  list  of
678              tuples.
679
680              The  printout  to parse is typically the result of a select com‐
681              mand in SQL. The returned Table is a list of tuples, where  each
682              tuple is a row in the table.
683
684              Heading  is a tuple of strings representing the headings of each
685              column in the table.
686
687       print(Format) -> ok
688
689              Equivalent to ct:print(default, 50, Format, [], []).
690
691       print(X1, X2) -> ok
692
693              Types:
694
695                 X1 = Category | Importance | Format
696                 X2 = Format | FormatArgs
697
698              Equivalent to ct:print(Category, Importance, Format, FormatArgs,
699              []).
700
701       print(X1, X2, X3) -> ok
702
703              Types:
704
705                 X1 = Category | Importance
706                 X2 = Importance | Format
707                 X3 = Format | FormatArgs | Opts
708
709              Equivalent to ct:print(Category, Importance, Format, FormatArgs,
710              Opts).
711
712       print(X1, X2, X3, X4) -> ok
713
714              Types:
715
716                 X1 = Category | Importance
717                 X2 = Importance | Format
718                 X3 = Format | FormatArgs
719                 X4 = FormatArgs | Opts
720
721              Equivalent to ct:print(Category, Importance, Format, FormatArgs,
722              Opts).
723
724       print(Category, Importance, Format, FormatArgs, Opts) -> ok
725
726              Types:
727
728                 Category = atom()
729                 Importance = integer()
730                 Format = string()
731                 FormatArgs = list()
732                 Opts = [Opt]
733                 Opt = {heading,string()}
734
735              Prints from a test case to the console.
736
737              This function is meant for printing a string from a test case to
738              the console.
739
740              Default Category is default, default Importance  is  ?STD_IMPOR‐
741              TANCE, and default value for FormatArgs is [].
742
743              For  details  on  Category and Importance, see section Logging -
744              Categories and Verbosity Levels in the User's Guide.
745
746       reload_config(Required) -> ValueOrElement | {error, Reason}
747
748              Types:
749
750                 Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, Sub‐
751                 Key, SubKey}
752                 KeyOrName = atom()
753                 SubKey = atom()
754                 ValueOrElement = term()
755
756              Reloads  configuration  file  containing specified configuration
757              key.
758
759              This function updates the  configuration  data  from  which  the
760              specified configuration variable was read, and returns the (pos‐
761              sibly) new value of this variable.
762
763              If some variables were present in the configuration, but are not
764              loaded using this function, they are removed from the configura‐
765              tion table together with their aliases.
766
767       remaining_test_procs() -> {TestProcs,SharedGL,OtherGLs}
768
769              Types:
770
771                 TestProcs = [{pid(),GL}]
772                 GL = pid()
773                 SharedGL = pid()
774                 OtherGLs = [pid()]
775
776              This function will return the identity of test- and group leader
777              processes that are still running at the time of this call. Test‐
778              Procs are processes in the system that have  a  Common  Test  IO
779              process  as group leader. SharedGL is the central Common Test IO
780              process, responsible for printing to log files for configuration
781              functions  and  sequentially  executing test cases. OtherGLs are
782              Common Test IO processes that print to log files for test  cases
783              in parallel test case groups.
784
785              The process information returned by this function may be used to
786              locate and terminate remaining processes after tests  have  fin‐
787              ished  executing.  The  function  would typically by called from
788              Common Test Hook functions.
789
790              Note that processes that execute configuration functions or test
791              cases  are  never included in TestProcs. It is therefore safe to
792              use    post    configuration    hook    functions    (such    as
793              post_end_per_suite,  post_end_per_group,  post_end_per_testcase)
794              to terminate all processes in TestProcs that  have  the  current
795              group leader process as its group leader.
796
797              Note  also that the shared group leader (SharedGL) must never be
798              terminated by the user, only by Common Test. Group  leader  pro‐
799              cesses  for  parallel test case groups (OtherGLs) may however be
800              terminated in post_end_per_group hook functions.
801
802       remove_config(Callback, Config) -> ok
803
804              Types:
805
806                 Callback = atom()
807                 Config = string()
808                 Reason = term()
809
810              Removes configuration variables  (together  wih  their  aliases)
811              that  were  loaded with specified callback module and configura‐
812              tion string.
813
814       require(Required) -> ok | {error, Reason}
815
816              Types:
817
818                 Required = Key | {Key, SubKeys} | {Key, SubKey, SubKeys}
819                 Key = atom()
820                 SubKeys = SubKey | [SubKey]
821                 SubKey = atom()
822
823              Checks if the required configuration is  available.  Arbitrarily
824              deep  tuples can be specified as Required. Only the last element
825              of the tuple can be a list of SubKeys.
826
827              Example 1. Require the variable myvar:
828
829               ok = ct:require(myvar).
830
831              In this case the configuration file must at least contain:
832
833               {myvar,Value}.
834
835              Example 2. Require key myvar with subkeys sub1 and sub2:
836
837               ok = ct:require({myvar,[sub1,sub2]}).
838
839              In this case the configuration file must at least contain:
840
841               {myvar,[{sub1,Value},{sub2,Value}]}.
842
843              Example 3. Require key myvar with subkey sub1 with subsub1:
844
845               ok = ct:require({myvar,sub1,sub2}).
846
847              In this case the configuration file must at least contain:
848
849               {myvar,[{sub1,[{sub2,Value}]}]}.
850
851              See  also  ct:get_config/1,  ct:get_config/2,   ct:get_config/3,
852              ct:require/2.
853
854       require(Name, Required) -> ok | {error, Reason}
855
856              Types:
857
858                 Name = atom()
859                 Required = Key | {Key, SubKey} | {Key, SubKey, SubKey}
860                 SubKey = Key
861                 Key = atom()
862
863              Checks if the required configuration is available and gives it a
864              name. The semantics for Required is the same as in  ct:require/1
865              except that a list of SubKeys cannot be specified.
866
867              If  the  requested data is available, the subentry is associated
868              with Name so that the value of the  element  can  be  read  with
869              ct:get_config/1,2  provided  Name  is  used instead of the whole
870              Required term.
871
872              Example:
873
874              Require one node with a Telnet connection and an FTP connection.
875              Name the node a:
876
877               ok = ct:require(a,{machine,node}).
878
879              All  references  to  this  node  can then use the node name. For
880              example, a file over FTP is fetched like follows:
881
882               ok = ct:ftp_get(a,RemoteFile,LocalFile).
883
884              For this to work, the configuration file must at least contain:
885
886               {machine,[{node,[{telnet,IpAddr},{ftp,IpAddr}]}]}.
887
888          Note:
889              The behavior of this function changed radically in  Common  Test
890              1.6.2.  To keep some backwards compatability, it is still possi‐
891              ble to do:
892              ct:require(a,{node,[telnet,ftp]}).
893              This associates the name a with the top-level  node  entry.  For
894              this to work, the configuration file must at least contain:
895              {node,[{telnet,IpAddr},{ftp,IpAddr}]}.
896
897
898              See   also  ct:get_config/1,  ct:get_config/2,  ct:get_config/3,
899              ct:require/1.
900
901       run(TestDirs) -> Result
902
903              Types:
904
905                 TestDirs = TestDir | [TestDir]
906
907              Runs all test cases in all suites in the specified directories.
908
909              See also ct:run/3.
910
911       run(TestDir, Suite) -> Result
912
913              Runs all test cases in the specified suite.
914
915              See also ct:run/3.
916
917       run(TestDir, Suite, Cases) -> Result
918
919              Types:
920
921                 TestDir = string()
922                 Suite = atom()
923                 Cases = atom() | [atom()]
924                 Result = [TestResult] | {error, Reason}
925
926              Runs the specified test cases.
927
928              Requires that ct:install/1 has been run first.
929
930              Suites (*_SUITE.erl) files must be stored in  TestDir  or  Test‐
931              Dir/test. All suites are compiled when the test is run.
932
933       run_test(Opts) -> Result
934
935              Types:
936
937                 Opts = [OptTuples]
938                 OptTuples  =  {dir,  TestDirs}  |  {suite,  Suites} | {group,
939                 Groups}  |  {testcase,   Cases}   |   {spec,   TestSpecs}   |
940                 {join_specs,  Bool}  |  {label, Label} | {config, CfgFiles} |
941                 {userconfig,  UserConfig}  |   {allow_user_terms,   Bool}   |
942                 {logdir, LogDir} | {silent_connections, Conns} | {stylesheet,
943                 CSSFile} | {cover,  CoverSpecFile}  |  {cover_stop,  Bool}  |
944                 {step, StepOpts} | {event_handler, EventHandlers} | {include,
945                 InclDirs} | {auto_compile, Bool} |  {abort_if_missing_suites,
946                 Bool}  |  {create_priv_dir,  CreatePrivDir} | {multiply_time‐
947                 traps, M} | {scale_timetraps, Bool} | {repeat,  N}  |  {dura‐
948                 tion,  DurTime} | {until, StopTime} | {force_stop, ForceStop}
949                 | {decrypt,  DecryptKeyOrFile}  |  {refresh_logs,  LogDir}  |
950                 {logopts,  LogOpts}  |  {verbosity,  VLevels}  | {basic_html,
951                 Bool} | {esc_chars, Bool} | {keep_logs,KeepSpec} | {ct_hooks,
952                 CTHs} | {enable_builtin_hooks, Bool} | {release_shell, Bool}
953                 TestDirs = [string()] | string()
954                 Suites = [string()] | [atom()] | string() | atom()
955                 Cases = [atom()] | atom()
956                 Groups = GroupNameOrPath | [GroupNameOrPath]
957                 GroupNameOrPath = [atom()] | atom() | all
958                 TestSpecs = [string()] | string()
959                 Label = string() | atom()
960                 CfgFiles = [string()] | string()
961                 UserConfig  =  [{CallbackMod,  CfgStrings}]  |  {CallbackMod,
962                 CfgStrings}
963                 CallbackMod = atom()
964                 CfgStrings = [string()] | string()
965                 LogDir = string()
966                 Conns = all | [atom()]
967                 CSSFile = string()
968                 CoverSpecFile = string()
969                 StepOpts = [StepOpt] | []
970                 StepOpt = config | keep_inactive
971                 EventHandlers = EH | [EH]
972                 EH = atom() | {atom(), InitArgs} | {[atom()], InitArgs}
973                 InitArgs = [term()]
974                 InclDirs = [string()] | string()
975                 CreatePrivDir = auto_per_run | auto_per_tc | manual_per_tc
976                 M = integer()
977                 N = integer()
978                 DurTime = string(HHMMSS)
979                 StopTime = string(YYMoMoDDHHMMSS) | string(HHMMSS)
980                 ForceStop = skip_rest | Bool
981                 DecryptKeyOrFile = {key, DecryptKey} | {file, DecryptFile}
982                 DecryptKey = string()
983                 DecryptFile = string()
984                 LogOpts = [LogOpt]
985                 LogOpt = no_nl | no_src
986                 VLevels = VLevel | [{Category, VLevel}]
987                 VLevel = integer()
988                 Category = atom()
989                 KeepSpec = all | pos_integer()
990                 CTHs = [CTHModule | {CTHModule, CTHInitArgs}]
991                 CTHModule = atom()
992                 CTHInitArgs = term()
993                 Result = {Ok, Failed, {UserSkipped, AutoSkipped}} |  TestRun‐
994                 nerPid | {error, Reason}
995                 Ok = integer()
996                 Failed = integer()
997                 UserSkipped = integer()
998                 AutoSkipped = integer()
999                 TestRunnerPid = pid()
1000                 Reason = term()
1001
1002              Runs  tests  as specified by the combination of options in Opts.
1003              The options are the same as those used with program ct_run,  see
1004              Run Tests from Command Line in the ct_run manual page.
1005
1006              Here  a  TestDir  can  be used to point out the path to a Suite.
1007              Option testcase corresponds to option -case in  program  ct_run.
1008              Configuration  files  specified  in Opts are installed automati‐
1009              cally at startup.
1010
1011              TestRunnerPid is returned if release_shell == true. For details,
1012              see ct:break/1.
1013
1014              Reason indicates the type of error encountered.
1015
1016       run_testspec(TestSpec) -> Result
1017
1018              Types:
1019
1020                 TestSpec = [term()]
1021                 Result  =  {Ok, Failed, {UserSkipped, AutoSkipped}} | {error,
1022                 Reason}
1023                 Ok = integer()
1024                 Failed = integer()
1025                 UserSkipped = integer()
1026                 AutoSkipped = integer()
1027                 Reason = term()
1028
1029              Runs a test specified by TestSpec. The same terms are used as in
1030              test specification files.
1031
1032              Reason indicates the type of error encountered.
1033
1034       set_verbosity(Category, Level) -> ok
1035
1036              Types:
1037
1038                 Category = default | atom()
1039                 Level = integer()
1040
1041              Use  this  function to set, or modify, the verbosity level for a
1042              logging category. See the  User's Guide  for  details.  Use  the
1043              value default to set the general verbosity level.
1044
1045       sleep(Time) -> ok
1046
1047              Types:
1048
1049                 Time  =  {hours, Hours} | {minutes, Mins} | {seconds, Secs} |
1050                 Millisecs | infinity
1051                 Hours = integer()
1052                 Mins = integer()
1053                 Secs = integer()
1054                 Millisecs = integer() | float()
1055
1056              This function, similar to timer:sleep/1 in STDLIB, suspends  the
1057              test case for a specified time. However, this function also mul‐
1058              tiplies Time with the  multiply_timetraps  value  (if  set)  and
1059              under  certain  circumstances  also scales up the time automati‐
1060              cally if scale_timetraps is set to true (default is false).
1061
1062       start_interactive() -> ok
1063
1064              Starts Common Test in interactive mode.
1065
1066              From this mode, all test case support functions can be  executed
1067              directly from the Erlang shell. The interactive mode can also be
1068              started from the OS command line  with  ct_run  -shell  [-config
1069              File...].
1070
1071              If  any  functions  (for example, Telnet or FTP) using "required
1072              configuration data" are to be called from the Erlang shell, con‐
1073              figuration data must first be required with ct:require/2.
1074
1075              Example:
1076
1077               > ct:require(unix_telnet, unix).
1078               ok
1079               > ct_telnet:open(unix_telnet).
1080               {ok,<0.105.0>}
1081               > ct_telnet:cmd(unix_telnet, "ls .").
1082               {ok,["ls","file1  ...",...]}
1083
1084       step(TestDir, Suite, Case) -> Result
1085
1086              Types:
1087
1088                 Case = atom()
1089
1090              Steps through a test case with the debugger.
1091
1092              See also ct:run/3.
1093
1094       step(TestDir, Suite, Case, Opts) -> Result
1095
1096              Types:
1097
1098                 Case = atom()
1099                 Opts = [Opt] | []
1100                 Opt = config | keep_inactive
1101
1102              Steps  through  a  test case with the debugger. If option config
1103              has been specifed, breakpoints are also set on the configuration
1104              functions in Suite.
1105
1106              See also ct:run/3.
1107
1108       stop_interactive() -> ok
1109
1110              Exits the interactive mode.
1111
1112              See also ct:start_interactive/0.
1113
1114       sync_notify(Name, Data) -> ok
1115
1116              Types:
1117
1118                 Name = atom()
1119                 Data = term()
1120
1121              Sends  a  synchronous notification of type Name with Data to the
1122              Common Test event manager. This  can  later  be  caught  by  any
1123              installed event manager.
1124
1125              See also gen_event(3).
1126
1127       testcases(TestDir, Suite) -> Testcases | {error, Reason}
1128
1129              Types:
1130
1131                 TestDir = string()
1132                 Suite = atom()
1133                 Testcases = list()
1134                 Reason = term()
1135
1136              Returns all test cases in the specified suite.
1137
1138       timetrap(Time) -> ok
1139
1140              Types:
1141
1142                 Time  =  {hours, Hours} | {minutes, Mins} | {seconds, Secs} |
1143                 Millisecs | infinity | Func
1144                 Hours = integer()
1145                 Mins = integer()
1146                 Secs = integer()
1147                 Millisecs = integer()
1148                 Func = {M, F, A} | function()
1149                 M = atom()
1150                 F = atom()
1151                 A = list()
1152
1153              Sets a new timetrap for the running test case.
1154
1155              If the argument is Func, the timetrap  is  triggered  when  this
1156              function  returns.  Func can also return a new Time value, which
1157              in that case is the value for the new timetrap.
1158
1159       userdata(TestDir, Suite) -> SuiteUserData | {error, Reason}
1160
1161              Types:
1162
1163                 TestDir = string()
1164                 Suite = atom()
1165                 SuiteUserData = [term()]
1166                 Reason = term()
1167
1168              Returns any data specified with tag  userdata  in  the  list  of
1169              tuples returned from suite/0.
1170
1171       userdata(TestDir,  Suite,  Case::GroupOrCase)  ->  TCUserData | {error,
1172       Reason}
1173
1174              Types:
1175
1176                 TestDir = string()
1177                 Suite = atom()
1178                 GroupOrCase = {group, GroupName} | atom()
1179                 GroupName = atom()
1180                 TCUserData = [term()]
1181                 Reason = term()
1182
1183              Returns any data specified with tag  userdata  in  the  list  of
1184              tuples returned from Suite:group(GroupName) or Suite:Case().
1185
1186
1187
1188Ericsson AB                    common_test 1.18                          ct(3)
Impressum