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() = {log_type,conn_log_type()} | {hosts,[key_or_name()]}
57 conn_log_type() = raw | pretty | html | silent
59 conn_log_mod() = ct_netconfc | ct_telnet
61
63 abort_current_testcase(Reason) -> ok | {error, ErrorReason}
64 Types:
66 Reason = term()
68 ErrorReason = no_testcase_running | parallel_group
69 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 Reason, the reason for aborting the test case, is printed in the
76 test case log.
77 add_config(Callback, Config) -> ok | {error, Reason}
79 Types:
81 Callback = atom()
83 Config = string()
84 Reason = term()
85 Loads configuration variables using the specified callback mod‐
87 ule and configuration string. The callback module is to be ei‐
88 ther loaded or present in the code path. Loaded configuration
89 variables can later be removed using function ct:remove_con‐
90 fig/2.
91 break(Comment) -> ok | {error, Reason}
93 Types:
95 Comment = string()
97 Reason = {multiple_cases_running, TestCases} | 'enable break
98 with release_shell option'
99 TestCases = [atom()]
100 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 A cancelled timetrap is not automatically reactivated after the
109 break, but must be started explicitly with ct:timetrap/1.
110 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 Er‐
115 lang Program in the User's Guide.
116 break(TestCase, Comment) -> ok | {error, Reason}
118 Types:
120 TestCase = atom()
122 Comment = string()
123 Reason = 'test case not running' | 'enable break with re‐
124 lease_shell option'
125 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 For details, see ct:break/1.
132 capture_get() -> ListOfStrings
134 Types:
136 ListOfStrings = [string()]
138 Equivalent to ct:capture_get([default]).
140 capture_get(ExclCategories) -> ListOfStrings
142 Types:
144 ExclCategories = [atom()]
146 ListOfStrings = [string()]
147 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 See also ct:capture_start/0, ct:capture_stop/0, ct:log/3.
155 capture_start() -> ok
157 Starts capturing all text strings printed to stdout during exe‐
159 cution of the test case.
160 See also ct:capture_get/1, ct:capture_stop/0.
162 capture_stop() -> ok
164 Stops capturing text strings (a session started with cap‐
166 ture_start/0).
167 See also ct:capture_get/1, ct:capture_start/0.
169 comment(Comment) -> ok
171 Types:
173 Comment = term()
175 Prints the specified Comment in the comment field in the table
177 on the test suite result page.
178 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 comment(Format, Args) -> ok
184 Types:
186 Format = string()
188 Args = list()
189 Prints the formatted string in the comment field in the table on
191 the test suite result page.
192 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 continue() -> ok
198 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 continue(TestCase) -> ok
203 Types:
205 TestCase = atom()
207 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 decrypt_config_file(EncryptFileName, TargetFileName) -> ok | {error,
214 Reason}
215 Types:
217 EncryptFileName = string()
219 TargetFileName = string()
220 Reason = term()
221 Decrypts EncryptFileName, previously generated with ct:en‐
223 crypt_config_file/2,3. The original file contents is saved in
224 the target file. The encryption key, a string, must be available
225 in a text file named .ct_config.crypt, either in the current di‐
226 rectory, or the home directory of the user (it is searched for
227 in that order).
228 decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -> ok |
230 {error, Reason}
231 Types:
233 EncryptFileName = string()
235 TargetFileName = string()
236 KeyOrFile = {key, string()} | {file, string()}
237 Reason = term()
238 Decrypts EncryptFileName, previously generated with ct:en‐
240 crypt_config_file/2,3. The original file contents is saved in
241 the target file. The key must have the same value as that used
242 for encryption.
243 encrypt_config_file(SrcFileName, EncryptFileName) -> ok | {error, Rea‐
245 son}
246 Types:
248 SrcFileName = string()
250 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) -> ok |
267 {error, Reason}
268 Types:
270 SrcFileName = string()
272 EncryptFileName = string()
273 KeyOrFile = {key, string()} | {file, string()}
274 Reason = term()
275 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 For information about using encrypted configuration files when
282 running tests, see section Encrypted Configuration Files in the
283 User's Guide.
284 For details on DES3 encryption/decryption, see application
286 Crypto.
287 fail(Reason) -> ok
289 Types:
291 Reason = term()
293 Terminates a test case with the specified error Reason.
295 fail(Format, Args) -> ok
297 Types:
299 Format = string()
301 Args = list()
302 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 get_config(Required) -> Value
308 Equivalent to ct:get_config(Required, undefined, []).
310 get_config(Required, Default) -> Value
312 Equivalent to ct:get_config(Required, Default, []).
314 get_config(Required, Default, Opts) -> ValueOrElement
316 Types:
318 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 Reads configuration data values.
329 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 Example:
335 Given the following configuration file:
337 {unix,[{telnet,IpAddr},
339 {user,[{username,Username},
340 {password,Password}]}]}.
341 Then:
343 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 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 ct:require(myuser,{unix,user}) -> ok.
356 ct:get_config(myuser,Default) -> [{username,Username}, {password,Password}]
357 If a configuration variable is defined in multiple files, use
359 option all to access all possible values. The values are re‐
360 turned in a list. The order of the elements corresponds to the
361 order that the configuration files were specified at startup.
362 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 See also ct:get_config/1, ct:get_config/2, ct:require/1, ct:re‐
368 quire/2.
369 get_event_mgr_ref() -> EvMgrRef
371 Types:
373 EvMgrRef = atom()
375 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 Example:
381 gen_event:add_handler(ct:get_event_mgr_ref(), my_ev_h, [])
383 get_progname() -> string()
385 Returns the command used to start this Erlang instance. If this
387 information could not be found, the string "no_prog_name" is re‐
388 turned.
389 get_status() -> TestStatus | {error, Reason} | no_tests_running
391 Types:
393 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 Returns status of ongoing test. The returned list contains in‐
409 formation 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 get_target_name(Handle) -> {ok, TargetName} | {error, Reason}
415 Types:
417 Handle = handle()
419 TargetName = target_name()
420 Returns the name of the target that the specified connection be‐
422 longs to.
423 get_testspec_terms() -> TestSpecTerms | undefined
425 Types:
427 TestSpecTerms = [{Tag, Value}]
429 Value = [term()]
430 Gets a list of all test specification terms used to configure
432 and run this test.
433 get_testspec_terms(Tags) -> TestSpecTerms | undefined
435 Types:
437 Tags = [Tag] | Tag
439 Tag = atom()
440 TestSpecTerms = [{Tag, Value}] | {Tag, Value}
441 Value = [{Node, term()}] | [term()]
442 Node = atom()
443 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 All value tuples returned, except user terms, have the node name
450 as first element.
451 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 get_timetrap_info() -> {Time, {Scaling,ScaleVal}}
458 Types:
460 Time = integer() | infinity
462 Scaling = true | false
463 ScaleVal = integer()
464 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 multiplier (always 1 if scaling is disabled). Note
470 the Time is not the scaled result.
471 get_verbosity(Category) -> Level | undefined
473 Types:
475 Category = default | atom()
477 Level = integer()
478 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 install(Opts) -> ok | {error, Reason}
484 Types:
486 Opts = [Opt]
488 Opt = {config, ConfigFiles} | {event_handler, Modules} | {de‐
489 crypt, KeyOrFile}
490 ConfigFiles = [ConfigFile]
491 ConfigFile = string()
492 Modules = [atom()]
493 KeyOrFile = {key, Key} | {file, KeyFile}
494 Key = string()
495 KeyFile = string()
496 Installs configuration files and event handlers.
498 Run this function once before the first test.
500 Example:
502 install([{config,["config_node.ctc","config_user.ctc"]}])
504 This function is automatically run by program ct_run.
506 listenv(Telnet) -> [Env]
508 Types:
510 Telnet = term()
512 Env = {Key, Value}
513 Key = string()
514 Value = string()
515 Performs command listenv on the specified Telnet connection and
517 returns the result as a list of key-value pairs.
518 log(Format) -> ok
520 Equivalent to ct:log(default, 50, Format, [], []).
522 log(X1, X2) -> ok
524 Types:
526 X1 = Category | Importance | Format
528 X2 = Format | FormatArgs
529 Equivalent to ct:log(Category, Importance, Format, FormatArgs,
531 []).
532 log(X1, X2, X3) -> ok
534 Types:
536 X1 = Category | Importance
538 X2 = Importance | Format
539 X3 = Format | FormatArgs | Opts
540 Equivalent to ct:log(Category, Importance, Format, FormatArgs,
542 Opts).
543 log(X1, X2, X3, X4) -> ok
545 Types:
547 X1 = Category | Importance
549 X2 = Importance | Format
550 X3 = Format | FormatArgs
551 X4 = FormatArgs | Opts
552 Equivalent to ct:log(Category, Importance, Format, FormatArgs,
554 Opts).
555 log(Category, Importance, Format, FormatArgs, Opts) -> ok
557 Types:
559 Category = atom()
561 Importance = integer()
562 Format = string()
563 FormatArgs = list()
564 Opts = [Opt]
565 Opt = {heading,string()} | no_css | esc_chars
566 Prints from a test case to the log file.
568 This function is meant for printing a string directly from a
570 test case to the test case log file.
571 Default Category is default, default Importance is ?STD_IMPOR‐
573 TANCE, and default value for FormatArgs is [].
574 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 Common Test will not escape special HTML characters (<, > and &)
580 in the text printed with this function, unless the esc_chars op‐
581 tion is used.
582 make_priv_dir() -> ok | {error, Reason}
584 Types:
586 Reason = term()
588 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 notify(Name, Data) -> ok
594 Types:
596 Name = atom()
598 Data = term()
599 Sends an asynchronous notification of type Name with Datato the
601 Common Test event manager. This can later be caught by any in‐
602 stalled event manager.
603 See also gen_event(3).
605 pal(Format) -> ok
607 Equivalent to ct:pal(default, 50, Format, [], []).
609 pal(X1, X2) -> ok
611 Types:
613 X1 = Category | Importance | Format
615 X2 = Format | FormatArgs
616 Equivalent to ct:pal(Category, Importance, Format, FormatArgs,
618 []).
619 pal(X1, X2, X3) -> ok
621 Types:
623 X1 = Category | Importance
625 X2 = Importance | Format
626 X3 = Format | FormatArgs | Opts
627 Equivalent to ct:pal(Category, Importance, Format, FormatArgs,
629 Opts).
630 pal(X1, X2, X3, X4) -> ok
632 Types:
634 X1 = Category | Importance
636 X2 = Importance | Format
637 X3 = Format | FormatArgs
638 X4 = FormatArgs | Opts
639 Equivalent to ct:pal(Category, Importance, Format, FormatArgs,
641 Opts).
642 pal(Category, Importance, Format, FormatArgs, Opts) -> ok
644 Types:
646 Category = atom()
648 Importance = integer()
649 Format = string()
650 FormatArgs = list()
651 Opts = [Opt]
652 Opt = {heading,string()} | no_css
653 Prints and logs from a test case.
655 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 Default Category is default, default Importance is ?STD_IMPOR‐
660 TANCE, and default value for FormatArgs is [].
661 For details on Category and Importance, see section Logging -
663 Categories and Verbosity Levels in the User's Guide.
664 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 parse_table(Data) -> {Heading, Table}
670 Types:
672 Data = [string()]
674 Heading = tuple()
675 Table = [tuple()]
676 Parses the printout from an SQL table and returns a list of tu‐
678 ples.
679 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 Heading is a tuple of strings representing the headings of each
685 column in the table.
686 print(Format) -> ok
688 Equivalent to ct:print(default, 50, Format, [], []).
690 print(X1, X2) -> ok
692 Types:
694 X1 = Category | Importance | Format
696 X2 = Format | FormatArgs
697 Equivalent to ct:print(Category, Importance, Format, FormatArgs,
699 []).
700 print(X1, X2, X3) -> ok
702 Types:
704 X1 = Category | Importance
706 X2 = Importance | Format
707 X3 = Format | FormatArgs | Opts
708 Equivalent to ct:print(Category, Importance, Format, FormatArgs,
710 Opts).
711 print(X1, X2, X3, X4) -> ok
713 Types:
715 X1 = Category | Importance
717 X2 = Importance | Format
718 X3 = Format | FormatArgs
719 X4 = FormatArgs | Opts
720 Equivalent to ct:print(Category, Importance, Format, FormatArgs,
722 Opts).
723 print(Category, Importance, Format, FormatArgs, Opts) -> ok
725 Types:
727 Category = atom()
729 Importance = integer()
730 Format = string()
731 FormatArgs = list()
732 Opts = [Opt]
733 Opt = {heading,string()}
734 Prints from a test case to the console.
736 This function is meant for printing a string from a test case to
738 the console.
739 Default Category is default, default Importance is ?STD_IMPOR‐
741 TANCE, and default value for FormatArgs is [].
742 For details on Category and Importance, see section Logging -
744 Categories and Verbosity Levels in the User's Guide.
745 reload_config(Required) -> ValueOrElement | {error, Reason}
747 Types:
749 Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, Sub‐
751 Key, SubKey}
752 KeyOrName = atom()
753 SubKey = atom()
754 ValueOrElement = term()
755 Reloads configuration file containing specified configuration
757 key.
758 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 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 remaining_test_procs() -> {TestProcs,SharedGL,OtherGLs}
768 Types:
770 TestProcs = [{pid(),GL}]
772 GL = pid()
773 SharedGL = pid()
774 OtherGLs = [pid()]
775 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 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 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 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 remove_config(Callback, Config) -> ok
803 Types:
805 Callback = atom()
807 Config = string()
808 Reason = term()
809 Removes configuration variables (together with their aliases)
811 that were loaded with specified callback module and configura‐
812 tion string.
813 require(Required) -> ok | {error, Reason}
815 Types:
817 Required = Key | {Key, SubKeys} | {Key, SubKey, SubKeys}
819 Key = atom()
820 SubKeys = SubKey | [SubKey]
821 SubKey = atom()
822 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 Example 1. Require the variable myvar:
828 ok = ct:require(myvar).
830 In this case the configuration file must at least contain:
832 {myvar,Value}.
834 Example 2. Require key myvar with subkeys sub1 and sub2:
836 ok = ct:require({myvar,[sub1,sub2]}).
838 In this case the configuration file must at least contain:
840 {myvar,[{sub1,Value},{sub2,Value}]}.
842 Example 3. Require key myvar with subkey sub1 with subsub1:
844 ok = ct:require({myvar,sub1,sub2}).
846 In this case the configuration file must at least contain:
848 {myvar,[{sub1,[{sub2,Value}]}]}.
850 See also ct:get_config/1, ct:get_config/2, ct:get_config/3,
852 ct:require/2.
853 require(Name, Required) -> ok | {error, Reason}
855 Types:
857 Name = atom()
859 Required = Key | {Key, SubKey} | {Key, SubKey, SubKey}
860 SubKey = Key
861 Key = atom()
862 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 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 Re‐
870 quired term.
871 Example:
873 Require one node with a Telnet connection and an FTP connection.
875 Name the node a:
876 ok = ct:require(a,{machine,node}).
878 All references to this node can then use the node name. For ex‐
880 ample, a file over FTP is fetched like follows:
881 ok = ct:ftp_get(a,RemoteFile,LocalFile).
883 For this to work, the configuration file must at least contain:
885 {machine,[{node,[{telnet,IpAddr},{ftp,IpAddr}]}]}.
887 Note:
889 The behavior of this function changed radically in Common Test
890 1.6.2. To keep some backwards compatibility, 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 See also ct:get_config/1, ct:get_config/2, ct:get_config/3,
899 ct:require/1.
900 run(TestDirs) -> Result
902 Types:
904 TestDirs = TestDir | [TestDir]
906 Runs all test cases in all suites in the specified directories.
908 See also ct:run/3.
910 run(TestDir, Suite) -> Result
912 Runs all test cases in the specified suite.
914 See also ct:run/3.
916 run(TestDir, Suite, Cases) -> Result
918 Types:
920 TestDir = string()
922 Suite = atom()
923 Cases = atom() | [atom()]
924 Result = [TestResult] | {error, Reason}
925 Runs the specified test cases.
927 Requires that ct:install/1 has been run first.
929 Suites (*_SUITE.erl) files must be stored in TestDir or Test‐
931 Dir/test. All suites are compiled when the test is run.
932 run_test(Opts) -> Result
934 Types:
936 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} | {lo‐
950 gopts, LogOpts} | {verbosity, VLevels} | {basic_html, Bool} |
951 {esc_chars, Bool} | {keep_logs,KeepSpec} | {ct_hooks, CTHs} |
952 {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 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 Here a TestDir can be used to point out the path to a Suite. Op‐
1007 tion testcase corresponds to option -case in program ct_run.
1008 Configuration files specified in Opts are installed automati‐
1009 cally at startup.
1010 TestRunnerPid is returned if release_shell == true. For details,
1012 see ct:break/1.
1013 Reason indicates the type of error encountered.
1015 run_testspec(TestSpec) -> Result
1017 Types:
1019 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 Runs a test specified by TestSpec. The same terms are used as in
1030 test specification files.
1031 Reason indicates the type of error encountered.
1033 set_verbosity(Category, Level) -> ok
1035 Types:
1037 Category = default | atom()
1039 Level = integer()
1040 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 sleep(Time) -> ok
1046 Types:
1048 Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} |
1050 Millisecs | infinity
1051 Hours = integer()
1052 Mins = integer()
1053 Secs = integer()
1054 Millisecs = integer() | float()
1055 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 un‐
1059 der certain circumstances also scales up the time automatically
1060 if scale_timetraps is set to true (default is false).
1061 start_interactive() -> ok
1063 Starts Common Test in interactive mode.
1065 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 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 Example:
1076 > 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 step(TestDir, Suite, Case) -> Result
1085 Types:
1087 Case = atom()
1089 Steps through a test case with the debugger.
1091 See also ct:run/3.
1093 step(TestDir, Suite, Case, Opts) -> Result
1095 Types:
1097 Case = atom()
1099 Opts = [Opt] | []
1100 Opt = config | keep_inactive
1101 Steps through a test case with the debugger. If option config
1103 has been specified, breakpoints are also set on the configura‐
1104 tion functions in Suite.
1105 See also ct:run/3.
1107 stop_interactive() -> ok
1109 Exits the interactive mode.
1111 See also ct:start_interactive/0.
1113 sync_notify(Name, Data) -> ok
1115 Types:
1117 Name = atom()
1119 Data = term()
1120 Sends a synchronous notification of type Name with Data to the
1122 Common Test event manager. This can later be caught by any in‐
1123 stalled event manager.
1124 See also gen_event(3).
1126 testcases(TestDir, Suite) -> Testcases | {error, Reason}
1128 Types:
1130 TestDir = string()
1132 Suite = atom()
1133 Testcases = list()
1134 Reason = term()
1135 Returns all test cases in the specified suite.
1137 timetrap(Time) -> ok
1139 Types:
1141 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 Sets a new timetrap for the running test case.
1154 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 userdata(TestDir, Suite) -> SuiteUserData | {error, Reason}
1160 Types:
1162 TestDir = string()
1164 Suite = atom()
1165 SuiteUserData = [term()]
1166 Reason = term()
1167 Returns any data specified with tag userdata in the list of tu‐
1169 ples returned from suite/0.
1170 userdata(TestDir, Suite, Case::GroupOrCase) -> TCUserData | {error,
1172 Reason}
1173 Types:
1175 TestDir = string()
1177 Suite = atom()
1178 GroupOrCase = {group, GroupName} | atom()
1179 GroupName = atom()
1180 TCUserData = [term()]
1181 Reason = term()
1182 Returns any data specified with tag userdata in the list of tu‐
1184 ples returned from Suite:group(GroupName) or Suite:Case().
1185Ericsson AB common_test 1.23.3 ct(3)