1ct(3) Erlang Module Definition ct(3)
2
6 ct - Main user interface for the Common Test framework.
7
9 Main user interface for the Common Test framework.
10 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 Test Suite Support Macros
16 The config macro is defined in ct.hrl. This macro is to be used to re‐
18 trieve information from the Config variable sent to all test cases. It
19 is used with two arguments; the first is the name of the configuration
20 variable to retrieve, the second is the Config variable supplied to the
21 test case.
22 Possible configuration variables include:
24 * data_dir - Data file directory
26 * priv_dir - Scratch file directory
28 * Whatever added by init_per_suite/1 or init_per_testcase/2 in the
30 test suite.
31
33 handle() = pid()
34 The identity (handle) of a connection.
36 config_key() = atom()
38 A configuration key which exists in a configuration file
40 target_name() = atom()
42 A name and association to configuration data introduced through
44 a require statement, or a call to ct:require/2, for example,
45 ct:require(mynodename,{node,[telnet]}).
46 key_or_name() = config_key() | target_name()
48 conn_log_options() = [conn_log_option()]
50 Options that can be given to the cth_conn_log hook, which is
52 used for logging of NETCONF and Telnet connections. See ct_net‐
53 confc or ct_telnet for description and examples of how to use
54 this hook.
55 conn_log_option() =
57 {log_type, conn_log_type()} | {hosts, [key_or_name()]}
58 conn_log_type() = raw | pretty | html | silent
60 conn_log_mod() = ct_netconfc | ct_telnet
62
64 abort_current_testcase(Reason) -> ok | {error, ErrorReason}
65 Types:
67 Reason = term()
69 ErrorReason = no_testcase_running | parallel_group
70 Aborts the currently executing test case. The user must know
72 with certainty which test case is currently executing. The func‐
73 tion is therefore only safe to call from a function that has
74 been called (or synchronously invoked) by the test case.
75 Reason, the reason for aborting the test case, is printed in the
77 test case log.
78 add_config(Callback, Config) -> ok | {error, Reason}
80 Types:
82 Callback = atom()
84 Config = string()
85 Reason = term()
86 Loads configuration variables using the specified callback mod‐
88 ule and configuration string. The callback module is to be ei‐
89 ther loaded or present in the code path. Loaded configuration
90 variables can later be removed using function ct:remove_con‐
91 fig/2.
92 break(Comment) -> ok | {error, Reason}
94 Types:
96 Comment = string()
98 Reason =
99 {multiple_cases_running, TestCases} |
100 'enable break with release_shell option'
101 TestCases = [atom()]
102 Cancels any active timetrap and pauses the execution of the cur‐
104 rent test case until the user calls function continue/0. The
105 user can then interact with the Erlang node running the tests,
106 for example, for debugging purposes or for manually executing a
107 part of the test case. If a parallel group is executing,
108 ct:break/2 is to be called instead.
109 A cancelled timetrap is not automatically reactivated after the
111 break, but must be started explicitly with ct:timetrap/1.
112 In order for the break/continue functionality to work, Common
114 Test must release the shell process controlling stdin. This is
115 done by setting start option release_shell to true. For details,
116 see section Running Tests from the Erlang Shell or from an Er‐
117 lang Program in the User's Guide.
118 break(TestCase, Comment) -> ok | {error, Reason}
120 Types:
122 TestCase = atom()
124 Comment = string()
125 Reason =
126 'test case not running' |
127 'enable break with release_shell option'
128 Works the same way as ct:break/1, only argument TestCase makes
130 it possible to pause a test case executing in a parallel group.
131 Function ct:continue/1 is to be used to resume execution of
132 TestCase.
133 For details, see ct:break/1.
135 capture_get() -> ListOfStrings
137 Types:
139 ListOfStrings = [string()]
141 Equivalent to ct:capture_get([default]).
143 capture_get(ExclCategories) -> ListOfStrings
145 Types:
147 ExclCategories = [atom()]
149 ListOfStrings = [string()]
150 Returns and purges the list of text strings buffered during the
152 latest session of capturing printouts to stdout. Log categories
153 that are to be ignored in ListOfStrings can be specified with
154 ExclCategories. If ExclCategories = [], no filtering takes
155 place.
156 See also ct:capture_start/0, ct:capture_stop/0, ct:log/3.
158 capture_start() -> ok
160 Starts capturing all text strings printed to stdout during exe‐
162 cution of the test case.
163 See also ct:capture_get/1, ct:capture_stop/0.
165 capture_stop() -> ok
167 Stops capturing text strings (a session started with cap‐
169 ture_start/0).
170 See also ct:capture_get/1, ct:capture_start/0.
172 comment(Comment) -> ok
174 Types:
176 Comment = term()
178 Prints the specified Comment in the comment field in the table
180 on the test suite result page.
181 If called several times, only the last comment is printed. The
183 test case return value {comment,Comment} overwrites the string
184 set by this function.
185 comment(Format, Args) -> ok
187 Types:
189 Format = string()
191 Args = list()
192 Prints the formatted string in the comment field in the table on
194 the test suite result page.
195 Arguments Format and Args are used in a call to io_lib:format/2
197 to create the comment string. The behavior of comment/2 is oth‐
198 erwise the same as function ct:comment/1.
199 continue() -> ok
201 This function must be called to continue after a test case (not
203 executing in a parallel group) has called function ct:break/1.
204 continue(TestCase) -> ok
206 Types:
208 TestCase = atom()
210 This function must be called to continue after a test case has
212 called ct:break/2. If the paused test case, TestCase, executes
213 in a parallel group, this function, rather than continue/0, must
214 be used to let the test case proceed.
215 decrypt_config_file(EncryptFileName, TargetFileName) ->
217 ok | {error, Reason}
218 Types:
220 EncryptFileName = TargetFileName = string()
222 Reason = term()
223 Decrypts EncryptFileName, previously generated with ct:en‐
225 crypt_config_file/2,3. The original file contents is saved in
226 the target file. The encryption key, a string, must be available
227 in a text file named .ct_config.crypt, either in the current di‐
228 rectory, or the home directory of the user (it is searched for
229 in that order).
230 decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) ->
232 ok | {error, Reason}
233 Types:
235 EncryptFileName = TargetFileName = string()
237 KeyOrFile = {key, string()} | {file, string()}
238 Reason = term()
239 Decrypts EncryptFileName, previously generated with ct:en‐
241 crypt_config_file/2,3. The original file contents is saved in
242 the target file. The key must have the same value as that used
243 for encryption.
244 encrypt_config_file(SrcFileName, EncryptFileName) ->
246 ok | {error, Reason}
247 Types:
249 SrcFileName = EncryptFileName = string()
251 Reason = term()
252 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 For information about using encrypted configuration files when
260 running tests, see section Encrypted Configuration Files in the
261 User's Guide.
262 For details on DES3 encryption/decryption, see application
264 Crypto.
265 encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile) ->
267 ok | {error, Reason}
268 Types:
270 SrcFileName = EncryptFileName = string()
272 KeyOrFile = {key, string()} | {file, string()}
273 Reason = term()
274 Encrypts the source configuration file with DES3 and saves the
276 result in the target file EncryptFileName. The encryption key to
277 use is either the value in {key,Key} or the value stored in the
278 file specified by {file,File}.
279 For information about using encrypted configuration files when
281 running tests, see section Encrypted Configuration Files in the
282 User's Guide.
283 For details on DES3 encryption/decryption, see application
285 Crypto.
286 fail(Reason) -> no_return()
288 Types:
290 Reason = term()
292 Terminates a test case with the specified error Reason.
294 fail(Format, Args) -> no_return()
296 Types:
298 Format = io:format()
300 Args = [term()]
301 Terminates a test case with an error message specified by a for‐
303 mat string and a list of values (used as arguments to
304 io_lib:format/2).
305 get_config(Required) -> Value
307 Types:
309 Required =
311 KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey,
312 SubKey}
313 KeyOrName = SubKey = atom()
314 Value = term()
315 Equivalent to ct:get_config(Required, undefined, []).
317 get_config(Required, Default) -> Value
319 Types:
321 Required =
323 KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey,
324 SubKey}
325 KeyOrName = SubKey = atom()
326 Default = Value = term()
327 Equivalent to ct:get_config(Required, Default, []).
329 get_config(Required, Default, Opts) -> ValueOrElement
331 Types:
333 Required =
335 KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey,
336 SubKey}
337 KeyOrName = SubKey = atom()
338 Default = term()
339 Opts = [Opt]
340 Opt = element | all
341 ValueOrElement = term() | Default
342 Reads configuration data values.
344 Returns the matching values or configuration elements, given a
346 configuration variable key or its associated name (if one has
347 been specified with ct:require/2 or a require statement).
348 Example:
350 Given the following configuration file:
352 {unix,[{telnet,IpAddr},
354 {user,[{username,Username},
355 {password,Password}]}]}.
356 Then:
358 ct:get_config(unix,Default) -> [{telnet,IpAddr},
360 {user, [{username,Username}, {password,Password}]}]
361 ct:get_config({unix,telnet},Default) -> IpAddr
362 ct:get_config({unix,user,username},Default) -> Username
363 ct:get_config({unix,ftp},Default) -> Default
364 ct:get_config(unknownkey,Default) -> Default
365 If a configuration variable key has been associated with a name
367 (by ct:require/2 or a require statement), the name can be used
368 instead of the key to read the value:
369 ct:require(myuser,{unix,user}) -> ok.
371 ct:get_config(myuser,Default) -> [{username,Username}, {password,Password}]
372 If a configuration variable is defined in multiple files, use
374 option all to access all possible values. The values are re‐
375 turned in a list. The order of the elements corresponds to the
376 order that the configuration files were specified at startup.
377 If configuration elements (key-value tuples) are to be returned
379 as result instead of values, use option element. The returned
380 elements are then on the form {Required,Value}.
381 See also ct:get_config/1, ct:get_config/2, ct:require/1, ct:re‐
383 quire/2.
384 get_event_mgr_ref() -> EvMgrRef
386 Types:
388 EvMgrRef = atom()
390 Gets a reference to the Common Test event manager. The reference
392 can be used to, for example, add a user-specific event handler
393 while tests are running.
394 Example:
396 gen_event:add_handler(ct:get_event_mgr_ref(), my_ev_h, [])
398 get_progname() -> string()
400 Returns the command used to start this Erlang instance. If this
402 information could not be found, the string "no_prog_name" is re‐
403 turned.
404 get_status() -> TestStatus | {error, Reason} | no_tests_running
406 Types:
408 TestStatus = [StatusElem]
410 StatusElem =
411 {current, TestCaseInfo} |
412 {successful, Successful} |
413 {failed, Failed} |
414 {skipped, Skipped} |
415 {total, Total}
416 TestCaseInfo = {Suite, TestCase} | [{Suite, TestCase}]
417 Suite = TestCase = atom()
418 Successful = Failed = integer()
419 Skipped = {UserSkipped, AutoSkipped}
420 UserSkipped = AutoSkipped = Total = integer()
421 Reason = term()
422 Returns status of ongoing test. The returned list contains in‐
424 formation about which test case is executing (a list of cases
425 when a parallel test case group is executing), as well as coun‐
426 ters for successful, failed, skipped, and total test cases so
427 far.
428 get_target_name(Handle) -> {ok, TargetName} | {error, Reason}
430 Types:
432 Handle = handle()
434 TargetName = target_name()
435 Reason = term()
436 Returns the name of the target that the specified connection be‐
438 longs to.
439 get_testspec_terms() -> TestSpecTerms | undefined
441 Types:
443 TestSpecTerms = [{Tag, Value}]
445 Tag = atom()
446 Value = [term()]
447 Gets a list of all test specification terms used to configure
449 and run this test.
450 get_testspec_terms(Tags) -> TestSpecTerms | undefined
452 Types:
454 Tags = [Tag] | Tag
456 Tag = atom()
457 TestSpecTerms = [{Tag, Value}] | {Tag, Value}
458 Value = [{Node, term()}] | [term()]
459 Node = atom()
460 Reads one or more terms from the test specification used to con‐
462 figure and run this test. Tag is any valid test specification
463 tag, for example, label, config, or logdir. User-specific terms
464 are also available to read if option allow_user_terms is set.
465 All value tuples returned, except user terms, have the node name
467 as first element.
468 To read test terms, use Tag = tests (rather than suites, groups,
470 or cases). Value is then the list of all tests on the form
471 [{Node,Dir,[{TestSpec,GroupsAndCases1},...]},...], where Group‐
472 sAndCases = [{Group,[Case]}] | [Case].
473 get_timetrap_info() -> {Time, {Scaling, ScaleVal}}
475 Types:
477 Time = integer() | infinity
479 Scaling = boolean()
480 ScaleVal = integer()
481 Reads information about the timetrap set for the current test
483 case. Scaling indicates if Common Test will attempt to compen‐
484 sate timetraps automatically for runtime delays introduced by,
485 for example, tools like cover. ScaleVal is the value of the cur‐
486 rent scaling multiplier (always 1 if scaling is disabled). Note
487 the Time is not the scaled result.
488 get_verbosity(Category) -> Level | undefined
490 Types:
492 Category = default | atom()
494 Level = integer()
495 This function returns the verbosity level for the specified log‐
497 ging category. See the User's Guide for details. Use the value
498 default to read the general verbosity level.
499 install(Opts) -> ok | {error, Reason}
501 Types:
503 Opts = [Opt]
505 Opt =
506 {config, ConfigFiles} |
507 {event_handler, Modules} |
508 {decrypt, KeyOrFile}
509 ConfigFiles = [ConfigFile]
510 ConfigFile = string()
511 Modules = [atom()]
512 KeyOrFile = {key, Key} | {file, KeyFile}
513 Key = KeyFile = string()
514 Reason = term()
515 Installs configuration files and event handlers.
517 Run this function once before the first test.
519 Example:
521 install([{config,["config_node.ctc","config_user.ctc"]}])
523 This function is automatically run by program ct_run.
525 listenv(Telnet) -> {ok, [Env]}
527 Types:
529 Telnet = term()
531 Env = {Key, Value}
532 Key = Value = string()
533 Performs command listenv on the specified Telnet connection and
535 returns the result as a list of key-value pairs.
536 log(Format) -> ok
538 Types:
540 Format = string()
542 Equivalent to ct:log(default, 50, Format, [], []).
544 log(X1, X2) -> ok
546 Types:
548 X1 = Category | Importance | Format
550 X2 = Format | FormatArgs
551 Category = atom() | integer() | string()
552 Importance = integer()
553 Format = string()
554 FormatArgs = list()
555 Equivalent to ct:log(Category, Importance, Format, FormatArgs,
557 []).
558 log(X1, X2, X3) -> ok
560 Types:
562 X1 = Category | Importance
564 X2 = Importance | Format
565 X3 = Format | FormatArgs | Opts
566 Category = atom() | integer() | string()
567 Importance = integer()
568 Format = string()
569 FormatArgs = list()
570 Opts = [Opt]
571 Opt = {heading, string()} | no_css | esc_chars
572 Equivalent to ct:log(Category, Importance, Format, FormatArgs,
574 Opts).
575 log(X1, X2, X3, X4) -> ok
577 Types:
579 X1 = Category | Importance
581 X2 = Importance | Format
582 X3 = Format | FormatArgs
583 X4 = FormatArgs | Opts
584 Category = atom() | integer() | string()
585 Importance = integer()
586 Format = string()
587 FormatArgs = list()
588 Opts = [Opt]
589 Opt = {heading, string()} | no_css | esc_chars
590 Equivalent to ct:log(Category, Importance, Format, FormatArgs,
592 Opts).
593 log(Category, Importance, Format, FormatArgs, Opts) -> ok
595 Types:
597 Category = atom() | integer() | string()
599 Importance = integer()
600 Format = string()
601 FormatArgs = list()
602 Opts = [Opt]
603 Opt = {heading, string()} | no_css | esc_chars
604 Prints from a test case to the log file.
606 This function is meant for printing a string directly from a
608 test case to the test case log file.
609 Default Category is default, default Importance is ?STD_IMPOR‐
611 TANCE, and default value for FormatArgs is [].
612 For details on Category, Importance and the no_css option, see
614 section Logging - Categories and Verbosity Levels in the User's
615 Guide.
616 Common Test will not escape special HTML characters (<, > and &)
618 in the text printed with this function, unless the esc_chars op‐
619 tion is used.
620 make_priv_dir() -> ok | {error, Reason}
622 Types:
624 Reason = term()
626 If the test is started with option create_priv_dir set to man‐
628 ual_per_tc, in order for the test case to use the private direc‐
629 tory, it must first create it by calling this function.
630 notify(Name, Data) -> ok
632 Types:
634 Name = atom()
636 Data = term()
637 Sends an asynchronous notification of type Name with Datato the
639 Common Test event manager. This can later be caught by any in‐
640 stalled event manager.
641 See also gen_event(3).
643 pal(Format) -> ok
645 Types:
647 Format = string()
649 Equivalent to ct:pal(default, 50, Format, [], []).
651 pal(X1, X2) -> ok
653 Types:
655 X1 = Category | Importance | Format
657 X2 = Format | FormatArgs
658 Category = atom() | integer() | string()
659 Importance = integer()
660 Format = string()
661 FormatArgs = list()
662 Equivalent to ct:pal(Category, Importance, Format, FormatArgs,
664 []).
665 pal(X1, X2, X3) -> ok
667 Types:
669 X1 = Category | Importance
671 X2 = Importance | Format
672 X3 = Format | FormatArgs | Opt
673 Category = atom() | integer() | string()
674 Importance = integer()
675 Format = string()
676 FormatArgs = list()
677 Opt = {heading, string()} | no_css
678 Equivalent to ct:pal(Category, Importance, Format, FormatArgs,
680 Opts).
681 pal(X1, X2, X3, X4) -> ok
683 Types:
685 X1 = Category | Importance
687 X2 = Importance | Format
688 X3 = Format | FormatArgs
689 X4 = FormatArgs | Opts
690 Category = atom() | integer() | string()
691 Importance = integer()
692 Format = string()
693 FormatArgs = list()
694 Opts = [Opt]
695 Opt = {heading, string()} | no_css
696 Equivalent to ct:pal(Category, Importance, Format, FormatArgs,
698 Opts).
699 pal(Category, Importance, Format, FormatArgs, Opts) -> ok
701 Types:
703 Category = atom() | integer() | string()
705 Importance = integer()
706 Format = string()
707 FormatArgs = list()
708 Opts = [Opt]
709 Opt = {heading, string()} | no_css
710 Prints and logs from a test case.
712 This function is meant for printing a string from a test case,
714 both to the test case log file and to the console.
715 Default Category is default, default Importance is ?STD_IMPOR‐
717 TANCE, and default value for FormatArgs is [].
718 For details on Category and Importance, see section Logging -
720 Categories and Verbosity Levels in the User's Guide.
721 Note that special characters in the text (<, > and &) will be
723 escaped by Common Test before the text is printed to the log
724 file.
725 parse_table(Data) -> {Heading, Table}
727 Types:
729 Data = [string()]
731 Heading = tuple()
732 Table = [tuple()]
733 Parses the printout from an SQL table and returns a list of tu‐
735 ples.
736 The printout to parse is typically the result of a select com‐
738 mand in SQL. The returned Table is a list of tuples, where each
739 tuple is a row in the table.
740 Heading is a tuple of strings representing the headings of each
742 column in the table.
743 print(Format) -> ok
745 Types:
747 Format = string()
749 Equivalent to ct:print(default, 50, Format, [], []).
751 print(X1, X2) -> ok
753 Types:
755 X1 = Category | Importance | Format
757 X2 = Format | FormatArgs
758 Category = atom() | integer() | string()
759 Importance = integer()
760 Format = string()
761 FormatArgs = list()
762 Equivalent to ct:print(Category, Importance, Format, FormatArgs,
764 []).
765 print(X1, X2, X3) -> ok
767 Types:
769 X1 = Category | Importance
771 X2 = Importance | Format
772 X3 = Format | FormatArgs | Opts
773 Category = atom() | integer() | string()
774 Importance = integer()
775 Format = string()
776 FormatArgs = list()
777 Opts = [Opt]
778 Opt = {heading, string()}
779 Equivalent to ct:print(Category, Importance, Format, FormatArgs,
781 Opts).
782 print(X1, X2, X3, X4) -> ok
784 Types:
786 X1 = Category | Importance
788 X2 = Importance | Format
789 X3 = Format | FormatArgs
790 X4 = FormatArgs | Opts
791 Category = atom() | integer() | string()
792 Importance = integer()
793 Format = string()
794 FormatArgs = list()
795 Opts = [Opt]
796 Opt = {heading, string()}
797 Equivalent to ct:print(Category, Importance, Format, FormatArgs,
799 Opts).
800 print(Category, Importance, Format, FormatArgs, Opts) -> ok
802 Types:
804 Category = atom() | integer() | string()
806 Importance = integer()
807 Format = string()
808 FormatArgs = list()
809 Opts = [Opt]
810 Opt = {heading, string()}
811 Prints from a test case to the console.
813 This function is meant for printing a string from a test case to
815 the console.
816 Default Category is default, default Importance is ?STD_IMPOR‐
818 TANCE, and default value for FormatArgs is [].
819 For details on Category and Importance, see section Logging -
821 Categories and Verbosity Levels in the User's Guide.
822 reload_config(Required) -> ValueOrElement | {error, Reason}
824 Types:
826 Required =
828 KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey,
829 SubKey}
830 KeyOrName = SubKey = atom()
831 ValueOrElement = Reason = term()
832 Reloads configuration file containing specified configuration
834 key.
835 This function updates the configuration data from which the
837 specified configuration variable was read, and returns the (pos‐
838 sibly) new value of this variable.
839 If some variables were present in the configuration, but are not
841 loaded using this function, they are removed from the configura‐
842 tion table together with their aliases.
843 remaining_test_procs() -> {TestProcs, SharedGL, OtherGLs}
845 Types:
847 TestProcs = [{pid(), GL}]
849 GL = SharedGL = pid()
850 OtherGLs = [pid()]
851 This function will return the identity of test- and group leader
853 processes that are still running at the time of this call. Test‐
854 Procs are processes in the system that have a Common Test IO
855 process as group leader. SharedGL is the central Common Test IO
856 process, responsible for printing to log files for configuration
857 functions and sequentially executing test cases. OtherGLs are
858 Common Test IO processes that print to log files for test cases
859 in parallel test case groups.
860 The process information returned by this function may be used to
862 locate and terminate remaining processes after tests have fin‐
863 ished executing. The function would typically by called from
864 Common Test Hook functions.
865 Note that processes that execute configuration functions or test
867 cases are never included in TestProcs. It is therefore safe to
868 use post configuration hook functions (such as
869 post_end_per_suite, post_end_per_group, post_end_per_testcase)
870 to terminate all processes in TestProcs that have the current
871 group leader process as its group leader.
872 Note also that the shared group leader (SharedGL) must never be
874 terminated by the user, only by Common Test. Group leader pro‐
875 cesses for parallel test case groups (OtherGLs) may however be
876 terminated in post_end_per_group hook functions.
877 remove_config(Callback, Config) -> ok
879 Types:
881 Callback = atom()
883 Config = string()
884 Removes configuration variables (together with their aliases)
886 that were loaded with specified callback module and configura‐
887 tion string.
888 require(Required) -> ok | {error, Reason}
890 Types:
892 Required = Key | {Key, SubKeys} | {Key, SubKey, SubKeys}
894 Key = atom()
895 SubKeys = SubKey | [SubKey]
896 SubKey = atom()
897 Reason = term()
898 Checks if the required configuration is available. Arbitrarily
900 deep tuples can be specified as Required. Only the last element
901 of the tuple can be a list of SubKeys.
902 Example 1. Require the variable myvar:
904 ok = ct:require(myvar).
906 In this case the configuration file must at least contain:
908 {myvar,Value}.
910 Example 2. Require key myvar with subkeys sub1 and sub2:
912 ok = ct:require({myvar,[sub1,sub2]}).
914 In this case the configuration file must at least contain:
916 {myvar,[{sub1,Value},{sub2,Value}]}.
918 Example 3. Require key myvar with subkey sub1 with subsub1:
920 ok = ct:require({myvar,sub1,sub2}).
922 In this case the configuration file must at least contain:
924 {myvar,[{sub1,[{sub2,Value}]}]}.
926 See also ct:get_config/1, ct:get_config/2, ct:get_config/3,
928 ct:require/2.
929 require(Name, Required) -> ok | {error, Reason}
931 Types:
933 Name = atom()
935 Required = Key | {Key, SubKey} | {Key, SubKey, SubKey}
936 SubKey = Key
937 Key = atom()
938 Reason = term()
939 Checks if the required configuration is available and gives it a
941 name. The semantics for Required is the same as in ct:require/1
942 except that a list of SubKeys cannot be specified.
943 If the requested data is available, the subentry is associated
945 with Name so that the value of the element can be read with
946 ct:get_config/1,2 provided Name is used instead of the whole Re‐
947 quired term.
948 Example:
950 Require one node with a Telnet connection and an FTP connection.
952 Name the node a:
953 ok = ct:require(a,{machine,node}).
955 All references to this node can then use the node name. For ex‐
957 ample, a file over FTP is fetched like follows:
958 ok = ct:ftp_get(a,RemoteFile,LocalFile).
960 For this to work, the configuration file must at least contain:
962 {machine,[{node,[{telnet,IpAddr},{ftp,IpAddr}]}]}.
964 Note:
966 The behavior of this function changed radically in Common Test
967 1.6.2. To keep some backwards compatibility, it is still possi‐
968 ble to do:
969 ct:require(a,{node,[telnet,ftp]}).
970 This associates the name a with the top-level node entry. For
971 this to work, the configuration file must at least contain:
972 {node,[{telnet,IpAddr},{ftp,IpAddr}]}.
973 See also ct:get_config/1, ct:get_config/2, ct:get_config/3,
976 ct:require/1.
977 run(TestDirs) -> Result
979 Types:
981 TestDirs = TestDir | [TestDir]
983 TestDir = string()
984 Result = [TestResult] | {error, Reason}
985 TestResult = Reason = term()
986 Runs all test cases in all suites in the specified directories.
988 See also ct:run/3.
990 run(TestDir, Suite) -> Result
992 Types:
994 TestDir = string()
996 Suite = atom()
997 Result = [TestResult] | {error, Reason}
998 TestResult = Reason = term()
999 Runs all test cases in the specified suite.
1001 See also ct:run/3.
1003 run(TestDir, Suite, Cases) -> Result
1005 Types:
1007 TestDir = string()
1009 Suite = atom()
1010 Cases = atom() | [atom()]
1011 Result = [TestResult] | {error, Reason}
1012 TestResult = Reason = term()
1013 Runs the specified test cases.
1015 Requires that ct:install/1 has been run first.
1017 Suites (*_SUITE.erl) files must be stored in TestDir or Test‐
1019 Dir/test. All suites are compiled when the test is run.
1020 run_test(Opts) -> Result
1022 Types:
1024 Opts = [OptTuples]
1026 OptTuples =
1027 {dir, TestDirs} |
1028 {suite, Suites} |
1029 {group, Groups} |
1030 {testcase, Cases} |
1031 {spec, TestSpecs} |
1032 {join_specs, boolean()} |
1033 {label, Label} |
1034 {config, CfgFiles} |
1035 {userconfig, UserConfig} |
1036 {allow_user_terms, boolean()} |
1037 {logdir, LogDir} |
1038 {silent_connections, Conns} |
1039 {stylesheet, CSSFile} |
1040 {cover, CoverSpecFile} |
1041 {cover_stop, boolean()} |
1042 {step, StepOpts} |
1043 {event_handler, EventHandlers} |
1044 {include, InclDirs} |
1045 {auto_compile, boolean()} |
1046 {abort_if_missing_suites, boolean()} |
1047 {create_priv_dir, CreatePrivDir} |
1048 {multiply_timetraps, M} |
1049 {scale_timetraps, boolean()} |
1050 {repeat, N} |
1051 {duration, DurTime} |
1052 {until, StopTime} |
1053 {force_stop, ForceStop} |
1054 {decrypt, DecryptKeyOrFile} |
1055 {refresh_logs, LogDir} |
1056 {logopts, LogOpts} |
1057 {verbosity, VLevels} |
1058 {basic_html, boolean()} |
1059 {esc_chars, boolean()} |
1060 {keep_logs, KeepSpec} |
1061 {ct_hooks, CTHs} |
1062 {enable_builtin_hooks, boolean()} |
1063 {release_shell, boolean()}
1064 TestDirs = [string()] | string()
1065 Suites = [string()] | [atom()] | string() | atom()
1066 Cases = [atom()] | atom()
1067 Groups = GroupNameOrPath | [GroupNameOrPath]
1068 GroupNameOrPath = [atom()] | atom() | all
1069 TestSpecs = [string()] | string()
1070 Label = string() | atom()
1071 CfgFiles = [string()] | string()
1072 UserConfig =
1073 [{CallbackMod, CfgStrings}] | {CallbackMod, CfgStrings}
1074 CallbackMod = atom()
1075 CfgStrings = [string()] | string()
1076 LogDir = string()
1077 Conns = all | [atom()]
1078 CSSFile = CoverSpecFile = string()
1079 StepOpts = [StepOpt]
1080 StepOpt = config | keep_inactive
1081 EventHandlers = EH | [EH]
1082 EH = atom() | {atom(), InitArgs} | {[atom()], InitArgs}
1083 InitArgs = [term()]
1084 InclDirs = [string()] | string()
1085 CreatePrivDir = auto_per_run | auto_per_tc | manual_per_tc
1086 M = N = integer()
1087 DurTime = HHMMSS
1088 HHMMSS = string()
1089 StopTime = YYMoMoDDHHMMSS | HHMMSS
1090 YYMoMoDDHHMMSS = string()
1091 ForceStop = skip_rest | boolean()
1092 DecryptKeyOrFile = {key, DecryptKey} | {file, DecryptFile}
1093 DecryptKey = DecryptFile = string()
1094 LogOpts = [LogOpt]
1095 LogOpt = no_nl | no_src
1096 VLevels = VLevel | [{Category, VLevel}]
1097 VLevel = integer()
1098 Category = atom()
1099 KeepSpec = all | integer() >= 1
1100 CTHs = [CTHModule | {CTHModule, CTHInitArgs}]
1101 CTHModule = atom()
1102 CTHInitArgs = term()
1103 Result =
1104 {Ok, Failed, {UserSkipped, AutoSkipped}} |
1105 TestRunnerPid |
1106 {error, Reason}
1107 Ok = Failed = UserSkipped = AutoSkipped = integer()
1108 TestRunnerPid = pid()
1109 Reason = term()
1110 Runs tests as specified by the combination of options in Opts.
1112 The options are the same as those used with program ct_run, see
1113 Run Tests from Command Line in the ct_run manual page.
1114 Here a TestDir can be used to point out the path to a Suite. Op‐
1116 tion testcase corresponds to option -case in program ct_run.
1117 Configuration files specified in Opts are installed automati‐
1118 cally at startup.
1119 TestRunnerPid is returned if release_shell == true. For details,
1121 see ct:break/1.
1122 Reason indicates the type of error encountered.
1124 run_testspec(TestSpec) -> Result
1126 Types:
1128 TestSpec = [term()]
1130 Result =
1131 {Ok, Failed, {UserSkipped, AutoSkipped}} | {error, Rea‐
1132 son}
1133 Ok = Failed = UserSkipped = AutoSkipped = integer()
1134 Reason = term()
1135 Runs a test specified by TestSpec. The same terms are used as in
1137 test specification files.
1138 Reason indicates the type of error encountered.
1140 set_verbosity(Category, Level) -> ok
1142 Types:
1144 Category = default | atom()
1146 Level = integer()
1147 Use this function to set, or modify, the verbosity level for a
1149 logging category. See the User's Guide for details. Use the
1150 value default to set the general verbosity level.
1151 sleep(Time) -> ok
1153 Types:
1155 Time =
1157 {hours, Hours} |
1158 {minutes, Mins} |
1159 {seconds, Secs} |
1160 Millisecs | infinity
1161 Hours = Mins = Secs = integer()
1162 Millisecs = integer() | float()
1163 This function, similar to timer:sleep/1 in STDLIB, suspends the
1165 test case for a specified time. However, this function also mul‐
1166 tiplies Time with the multiply_timetraps value (if set) and un‐
1167 der certain circumstances also scales up the time automatically
1168 if scale_timetraps is set to true (default is false).
1169 start_interactive() -> ok
1171 Starts Common Test in interactive mode.
1173 From this mode, all test case support functions can be executed
1175 directly from the Erlang shell. The interactive mode can also be
1176 started from the OS command line with ct_run -shell [-config
1177 File...].
1178 If any functions (for example, Telnet or FTP) using "required
1180 configuration data" are to be called from the Erlang shell, con‐
1181 figuration data must first be required with ct:require/2.
1182 Example:
1184 > ct:require(unix_telnet, unix).
1186 ok
1187 > ct_telnet:open(unix_telnet).
1188 {ok,<0.105.0>}
1189 > ct_telnet:cmd(unix_telnet, "ls .").
1190 {ok,["ls","file1 ...",...]}
1191 step(TestDir, Suite, Case) -> Result
1193 Types:
1195 TestDir = string()
1197 Suite = Case = atom()
1198 Result = term()
1199 Steps through a test case with the debugger.
1201 See also ct:run/3.
1203 step(TestDir, Suite, Case, Opts) -> Result
1205 Types:
1207 TestDir = string()
1209 Suite = Case = atom()
1210 Opts = [Opt]
1211 Opt = config | keep_inactive
1212 Result = term()
1213 Steps through a test case with the debugger. If option config
1215 has been specified, breakpoints are also set on the configura‐
1216 tion functions in Suite.
1217 See also ct:run/3.
1219 stop_interactive() -> ok
1221 Exits the interactive mode.
1223 See also ct:start_interactive/0.
1225 sync_notify(Name, Data) -> ok
1227 Types:
1229 Name = atom()
1231 Data = term()
1232 Sends a synchronous notification of type Name with Data to the
1234 Common Test event manager. This can later be caught by any in‐
1235 stalled event manager.
1236 See also gen_event(3).
1238 testcases(TestDir, Suite) -> Testcases | {error, Reason}
1240 Types:
1242 TestDir = string()
1244 Suite = atom()
1245 Testcases = list()
1246 Reason = term()
1247 Returns all test cases in the specified suite.
1249 timetrap(Time) -> infinity | pid()
1251 Types:
1253 Time =
1255 {hours, Hours} |
1256 {minutes, Mins} |
1257 {seconds, Secs} |
1258 Millisecs | infinity | Func
1259 Hours = Mins = Secs = Millisecs = integer()
1260 Func = {M, F, A} | function()
1261 M = F = atom()
1262 A = list()
1263 Sets a new timetrap for the running test case.
1265 If the argument is Func, the timetrap is triggered when this
1267 function returns. Func can also return a new Time value, which
1268 in that case is the value for the new timetrap.
1269 userdata(TestDir, Suite) -> SuiteUserData | {error, Reason}
1271 Types:
1273 TestDir = string()
1275 Suite = atom()
1276 SuiteUserData = [term()]
1277 Reason = term()
1278 Returns any data specified with tag userdata in the list of tu‐
1280 ples returned from suite/0.
1281 userdata(TestDir, Suite, Case :: GroupOrCase) ->
1283 TCUserData | {error, Reason}
1284 Types:
1286 TestDir = string()
1288 Suite = atom()
1289 GroupOrCase = {group, GroupName} | atom()
1290 GroupName = atom()
1291 TCUserData = [term()]
1292 Reason = term()
1293 Returns any data specified with tag userdata in the list of tu‐
1295 ples returned from Suite:group(GroupName) or Suite:Case().
1296Ericsson AB common_test 1.25.1 ct(3)