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
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 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.
35 config_key() = atom():
37 A configuration key which exists in a configuration file
38 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 key_or_name() = config_key() | target_name():
45 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 conn_log_option() = {log_type,conn_log_type()} |
53 {hosts,[key_or_name()]}:
54 conn_log_type() = raw | pretty | html | silent:
57 conn_log_mod() = ct_netconfc | ct_telnet:
60
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
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 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 exlicitly 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
115 Erlang 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
124 release_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
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 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
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 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
360 returned 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,
368 ct:require/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_status() -> TestStatus | {error, Reason} | no_tests_running
385 Types:
387 TestStatus = [StatusElem]
389 StatusElem = {current, TestCaseInfo} | {successful, Success‐
390 ful} | {failed, Failed} | {skipped, Skipped} | {total, Total}
391 TestCaseInfo = {Suite, TestCase} | [{Suite, TestCase}]
392 Suite = atom()
393 TestCase = atom()
394 Successful = integer()
395 Failed = integer()
396 Skipped = {UserSkipped, AutoSkipped}
397 UserSkipped = integer()
398 AutoSkipped = integer()
399 Total = integer()
400 Reason = term()
401 Returns status of ongoing test. The returned list contains
403 information about which test case is executing (a list of cases
404 when a parallel test case group is executing), as well as coun‐
405 ters for successful, failed, skipped, and total test cases so
406 far.
407 get_target_name(Handle) -> {ok, TargetName} | {error, Reason}
409 Types:
411 Handle = handle()
413 TargetName = target_name()
414 Returns the name of the target that the specified connection
416 belongs to.
417 get_testspec_terms() -> TestSpecTerms | undefined
419 Types:
421 TestSpecTerms = [{Tag, Value}]
423 Value = [term()]
424 Gets a list of all test specification terms used to configure
426 and run this test.
427 get_testspec_terms(Tags) -> TestSpecTerms | undefined
429 Types:
431 Tags = [Tag] | Tag
433 Tag = atom()
434 TestSpecTerms = [{Tag, Value}] | {Tag, Value}
435 Value = [{Node, term()}] | [term()]
436 Node = atom()
437 Reads one or more terms from the test specification used to con‐
439 figure and run this test. Tag is any valid test specification
440 tag, for example, label, config, or logdir. User-specific terms
441 are also available to read if option allow_user_terms is set.
442 All value tuples returned, except user terms, have the node name
444 as first element.
445 To read test terms, use Tag = tests (rather than suites, groups,
447 or cases). Value is then the list of all tests on the form
448 [{Node,Dir,[{TestSpec,GroupsAndCases1},...]},...], where Group‐
449 sAndCases = [{Group,[Case]}] | [Case].
450 get_timetrap_info() -> {Time, {Scaling,ScaleVal}}
452 Types:
454 Time = integer() | infinity
456 Scaling = true | false
457 ScaleVal = integer()
458 Reads information about the timetrap set for the current test
460 case. Scaling indicates if Common Test will attempt to compen‐
461 sate timetraps automatically for runtime delays introduced by,
462 for example, tools like cover. ScaleVal is the value of the cur‐
463 rent scaling multipler (always 1 if scaling is disabled). Note
464 the Time is not the scaled result.
465 get_verbosity(Category) -> Level | undefined
467 Types:
469 Category = default | atom()
471 Level = integer()
472 This function returns the verbosity level for the specified log‐
474 ging category. See the User's Guide for details. Use the value
475 default to read the general verbosity level.
476 install(Opts) -> ok | {error, Reason}
478 Types:
480 Opts = [Opt]
482 Opt = {config, ConfigFiles} | {event_handler, Modules} |
483 {decrypt, KeyOrFile}
484 ConfigFiles = [ConfigFile]
485 ConfigFile = string()
486 Modules = [atom()]
487 KeyOrFile = {key, Key} | {file, KeyFile}
488 Key = string()
489 KeyFile = string()
490 Installs configuration files and event handlers.
492 Run this function once before the first test.
494 Example:
496 install([{config,["config_node.ctc","config_user.ctc"]}])
498 This function is automatically run by program ct_run.
500 listenv(Telnet) -> [Env]
502 Types:
504 Telnet = term()
506 Env = {Key, Value}
507 Key = string()
508 Value = string()
509 Performs command listenv on the specified Telnet connection and
511 returns the result as a list of key-value pairs.
512 log(Format) -> ok
514 Equivalent to ct:log(default, 50, Format, [], []).
516 log(X1, X2) -> ok
518 Types:
520 X1 = Category | Importance | Format
522 X2 = Format | FormatArgs
523 Equivalent to ct:log(Category, Importance, Format, FormatArgs,
525 []).
526 log(X1, X2, X3) -> ok
528 Types:
530 X1 = Category | Importance
532 X2 = Importance | Format
533 X3 = Format | FormatArgs | Opts
534 Equivalent to ct:log(Category, Importance, Format, FormatArgs,
536 Opts).
537 log(X1, X2, X3, X4) -> ok
539 Types:
541 X1 = Category | Importance
543 X2 = Importance | Format
544 X3 = Format | FormatArgs
545 X4 = FormatArgs | Opts
546 Equivalent to ct:log(Category, Importance, Format, FormatArgs,
548 Opts).
549 log(Category, Importance, Format, FormatArgs, Opts) -> ok
551 Types:
553 Category = atom()
555 Importance = integer()
556 Format = string()
557 FormatArgs = list()
558 Opts = [Opt]
559 Opt = {heading,string()} | no_css | esc_chars
560 Prints from a test case to the log file.
562 This function is meant for printing a string directly from a
564 test case to the test case log file.
565 Default Category is default, default Importance is ?STD_IMPOR‐
567 TANCE, and default value for FormatArgs is [].
568 For details on Category, Importance and the no_css option, see
570 section Logging - Categories and Verbosity Levels in the User's
571 Guide.
572 Common Test will not escape special HTML characters (<, > and &)
574 in the text printed with this function, unless the esc_chars
575 option is used.
576 make_priv_dir() -> ok | {error, Reason}
578 Types:
580 Reason = term()
582 If the test is started with option create_priv_dir set to man‐
584 ual_per_tc, in order for the test case to use the private direc‐
585 tory, it must first create it by calling this function.
586 notify(Name, Data) -> ok
588 Types:
590 Name = atom()
592 Data = term()
593 Sends an asynchronous notification of type Name with Datato the
595 Common Test event manager. This can later be caught by any
596 installed event manager.
597 See also gen_event(3).
599 pal(Format) -> ok
601 Equivalent to ct:pal(default, 50, Format, [], []).
603 pal(X1, X2) -> ok
605 Types:
607 X1 = Category | Importance | Format
609 X2 = Format | FormatArgs
610 Equivalent to ct:pal(Category, Importance, Format, FormatArgs,
612 []).
613 pal(X1, X2, X3) -> ok
615 Types:
617 X1 = Category | Importance
619 X2 = Importance | Format
620 X3 = Format | FormatArgs | Opts
621 Equivalent to ct:pal(Category, Importance, Format, FormatArgs,
623 Opts).
624 pal(X1, X2, X3, X4) -> ok
626 Types:
628 X1 = Category | Importance
630 X2 = Importance | Format
631 X3 = Format | FormatArgs
632 X4 = FormatArgs | Opts
633 Equivalent to ct:pal(Category, Importance, Format, FormatArgs,
635 Opts).
636 pal(Category, Importance, Format, FormatArgs, Opts) -> ok
638 Types:
640 Category = atom()
642 Importance = integer()
643 Format = string()
644 FormatArgs = list()
645 Opts = [Opt]
646 Opt = {heading,string()} | no_css
647 Prints and logs from a test case.
649 This function is meant for printing a string from a test case,
651 both to the test case log file and to the console.
652 Default Category is default, default Importance is ?STD_IMPOR‐
654 TANCE, and default value for FormatArgs is [].
655 For details on Category and Importance, see section Logging -
657 Categories and Verbosity Levels in the User's Guide.
658 Note that special characters in the text (<, > and &) will be
660 escaped by Common Test before the text is printed to the log
661 file.
662 parse_table(Data) -> {Heading, Table}
664 Types:
666 Data = [string()]
668 Heading = tuple()
669 Table = [tuple()]
670 Parses the printout from an SQL table and returns a list of
672 tuples.
673 The printout to parse is typically the result of a select com‐
675 mand in SQL. The returned Table is a list of tuples, where each
676 tuple is a row in the table.
677 Heading is a tuple of strings representing the headings of each
679 column in the table.
680 print(Format) -> ok
682 Equivalent to ct:print(default, 50, Format, [], []).
684 print(X1, X2) -> ok
686 Types:
688 X1 = Category | Importance | Format
690 X2 = Format | FormatArgs
691 Equivalent to ct:print(Category, Importance, Format, FormatArgs,
693 []).
694 print(X1, X2, X3) -> ok
696 Types:
698 X1 = Category | Importance
700 X2 = Importance | Format
701 X3 = Format | FormatArgs | Opts
702 Equivalent to ct:print(Category, Importance, Format, FormatArgs,
704 Opts).
705 print(X1, X2, X3, X4) -> ok
707 Types:
709 X1 = Category | Importance
711 X2 = Importance | Format
712 X3 = Format | FormatArgs
713 X4 = FormatArgs | Opts
714 Equivalent to ct:print(Category, Importance, Format, FormatArgs,
716 Opts).
717 print(Category, Importance, Format, FormatArgs, Opts) -> ok
719 Types:
721 Category = atom()
723 Importance = integer()
724 Format = string()
725 FormatArgs = list()
726 Opts = [Opt]
727 Opt = {heading,string()}
728 Prints from a test case to the console.
730 This function is meant for printing a string from a test case to
732 the console.
733 Default Category is default, default Importance is ?STD_IMPOR‐
735 TANCE, and default value for FormatArgs is [].
736 For details on Category and Importance, see section Logging -
738 Categories and Verbosity Levels in the User's Guide.
739 reload_config(Required) -> ValueOrElement | {error, Reason}
741 Types:
743 Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, Sub‐
745 Key, SubKey}
746 KeyOrName = atom()
747 SubKey = atom()
748 ValueOrElement = term()
749 Reloads configuration file containing specified configuration
751 key.
752 This function updates the configuration data from which the
754 specified configuration variable was read, and returns the (pos‐
755 sibly) new value of this variable.
756 If some variables were present in the configuration, but are not
758 loaded using this function, they are removed from the configura‐
759 tion table together with their aliases.
760 remaining_test_procs() -> {TestProcs,SharedGL,OtherGLs}
762 Types:
764 TestProcs = [{pid(),GL}]
766 GL = pid()
767 SharedGL = pid()
768 OtherGLs = [pid()]
769 This function will return the identity of test- and group leader
771 processes that are still running at the time of this call. Test‐
772 Procs are processes in the system that have a Common Test IO
773 process as group leader. SharedGL is the central Common Test IO
774 process, responsible for printing to log files for configuration
775 functions and sequentially executing test cases. OtherGLs are
776 Common Test IO processes that print to log files for test cases
777 in parallel test case groups.
778 The process information returned by this function may be used to
780 locate and terminate remaining processes after tests have fin‐
781 ished executing. The function would typically by called from
782 Common Test Hook functions.
783 Note that processes that execute configuration functions or test
785 cases are never included in TestProcs. It is therefore safe to
786 use post configuration hook functions (such as
787 post_end_per_suite, post_end_per_group, post_end_per_testcase)
788 to terminate all processes in TestProcs that have the current
789 group leader process as its group leader.
790 Note also that the shared group leader (SharedGL) must never be
792 terminated by the user, only by Common Test. Group leader pro‐
793 cesses for parallel test case groups (OtherGLs) may however be
794 terminated in post_end_per_group hook functions.
795 remove_config(Callback, Config) -> ok
797 Types:
799 Callback = atom()
801 Config = string()
802 Reason = term()
803 Removes configuration variables (together wih their aliases)
805 that were loaded with specified callback module and configura‐
806 tion string.
807 require(Required) -> ok | {error, Reason}
809 Types:
811 Required = Key | {Key, SubKeys} | {Key, SubKey, SubKeys}
813 Key = atom()
814 SubKeys = SubKey | [SubKey]
815 SubKey = atom()
816 Checks if the required configuration is available. Arbitrarily
818 deep tuples can be specified as Required. Only the last element
819 of the tuple can be a list of SubKeys.
820 Example 1. Require the variable myvar:
822 ok = ct:require(myvar).
824 In this case the configuration file must at least contain:
826 {myvar,Value}.
828 Example 2. Require key myvar with subkeys sub1 and sub2:
830 ok = ct:require({myvar,[sub1,sub2]}).
832 In this case the configuration file must at least contain:
834 {myvar,[{sub1,Value},{sub2,Value}]}.
836 Example 3. Require key myvar with subkey sub1 with subsub1:
838 ok = ct:require({myvar,sub1,sub2}).
840 In this case the configuration file must at least contain:
842 {myvar,[{sub1,[{sub2,Value}]}]}.
844 See also ct:get_config/1, ct:get_config/2, ct:get_config/3,
846 ct:require/2.
847 require(Name, Required) -> ok | {error, Reason}
849 Types:
851 Name = atom()
853 Required = Key | {Key, SubKey} | {Key, SubKey, SubKey}
854 SubKey = Key
855 Key = atom()
856 Checks if the required configuration is available and gives it a
858 name. The semantics for Required is the same as in ct:require/1
859 except that a list of SubKeys cannot be specified.
860 If the requested data is available, the subentry is associated
862 with Name so that the value of the element can be read with
863 ct:get_config/1,2 provided Name is used instead of the whole
864 Required term.
865 Example:
867 Require one node with a Telnet connection and an FTP connection.
869 Name the node a:
870 ok = ct:require(a,{machine,node}).
872 All references to this node can then use the node name. For
874 example, a file over FTP is fetched like follows:
875 ok = ct:ftp_get(a,RemoteFile,LocalFile).
877 For this to work, the configuration file must at least contain:
879 {machine,[{node,[{telnet,IpAddr},{ftp,IpAddr}]}]}.
881 Note:
883 The behavior of this function changed radically in Common Test
884 1.6.2. To keep some backwards compatability, it is still possi‐
885 ble to do:
886 ct:require(a,{node,[telnet,ftp]}).
887 This associates the name a with the top-level node entry. For
888 this to work, the configuration file must at least contain:
889 {node,[{telnet,IpAddr},{ftp,IpAddr}]}.
890 See also ct:get_config/1, ct:get_config/2, ct:get_config/3,
893 ct:require/1.
894 run(TestDirs) -> Result
896 Types:
898 TestDirs = TestDir | [TestDir]
900 Runs all test cases in all suites in the specified directories.
902 See also ct:run/3.
904 run(TestDir, Suite) -> Result
906 Runs all test cases in the specified suite.
908 See also ct:run/3.
910 run(TestDir, Suite, Cases) -> Result
912 Types:
914 TestDir = string()
916 Suite = atom()
917 Cases = atom() | [atom()]
918 Result = [TestResult] | {error, Reason}
919 Runs the specified test cases.
921 Requires that ct:install/1 has been run first.
923 Suites (*_SUITE.erl) files must be stored in TestDir or Test‐
925 Dir/test. All suites are compiled when the test is run.
926 run_test(Opts) -> Result
928 Types:
930 Opts = [OptTuples]
932 OptTuples = {dir, TestDirs} | {suite, Suites} | {group,
933 Groups} | {testcase, Cases} | {spec, TestSpecs} |
934 {join_specs, Bool} | {label, Label} | {config, CfgFiles} |
935 {userconfig, UserConfig} | {allow_user_terms, Bool} |
936 {logdir, LogDir} | {silent_connections, Conns} | {stylesheet,
937 CSSFile} | {cover, CoverSpecFile} | {cover_stop, Bool} |
938 {step, StepOpts} | {event_handler, EventHandlers} | {include,
939 InclDirs} | {auto_compile, Bool} | {abort_if_missing_suites,
940 Bool} | {create_priv_dir, CreatePrivDir} | {multiply_time‐
941 traps, M} | {scale_timetraps, Bool} | {repeat, N} | {dura‐
942 tion, DurTime} | {until, StopTime} | {force_stop, ForceStop}
943 | {decrypt, DecryptKeyOrFile} | {refresh_logs, LogDir} |
944 {logopts, LogOpts} | {verbosity, VLevels} | {basic_html,
945 Bool} | {esc_chars, Bool} | {keep_logs,KeepSpec} | {ct_hooks,
946 CTHs} | {enable_builtin_hooks, Bool} | {release_shell, Bool}
947 TestDirs = [string()] | string()
948 Suites = [string()] | [atom()] | string() | atom()
949 Cases = [atom()] | atom()
950 Groups = GroupNameOrPath | [GroupNameOrPath]
951 GroupNameOrPath = [atom()] | atom() | all
952 TestSpecs = [string()] | string()
953 Label = string() | atom()
954 CfgFiles = [string()] | string()
955 UserConfig = [{CallbackMod, CfgStrings}] | {CallbackMod,
956 CfgStrings}
957 CallbackMod = atom()
958 CfgStrings = [string()] | string()
959 LogDir = string()
960 Conns = all | [atom()]
961 CSSFile = string()
962 CoverSpecFile = string()
963 StepOpts = [StepOpt] | []
964 StepOpt = config | keep_inactive
965 EventHandlers = EH | [EH]
966 EH = atom() | {atom(), InitArgs} | {[atom()], InitArgs}
967 InitArgs = [term()]
968 InclDirs = [string()] | string()
969 CreatePrivDir = auto_per_run | auto_per_tc | manual_per_tc
970 M = integer()
971 N = integer()
972 DurTime = string(HHMMSS)
973 StopTime = string(YYMoMoDDHHMMSS) | string(HHMMSS)
974 ForceStop = skip_rest | Bool
975 DecryptKeyOrFile = {key, DecryptKey} | {file, DecryptFile}
976 DecryptKey = string()
977 DecryptFile = string()
978 LogOpts = [LogOpt]
979 LogOpt = no_nl | no_src
980 VLevels = VLevel | [{Category, VLevel}]
981 VLevel = integer()
982 Category = atom()
983 KeepSpec = all | pos_integer()
984 CTHs = [CTHModule | {CTHModule, CTHInitArgs}]
985 CTHModule = atom()
986 CTHInitArgs = term()
987 Result = {Ok, Failed, {UserSkipped, AutoSkipped}} | TestRun‐
988 nerPid | {error, Reason}
989 Ok = integer()
990 Failed = integer()
991 UserSkipped = integer()
992 AutoSkipped = integer()
993 TestRunnerPid = pid()
994 Reason = term()
995 Runs tests as specified by the combination of options in Opts.
997 The options are the same as those used with program ct_run, see
998 Run Tests from Command Line in the ct_run manual page.
999 Here a TestDir can be used to point out the path to a Suite.
1001 Option testcase corresponds to option -case in program ct_run.
1002 Configuration files specified in Opts are installed automati‐
1003 cally at startup.
1004 TestRunnerPid is returned if release_shell == true. For details,
1006 see ct:break/1.
1007 Reason indicates the type of error encountered.
1009 run_testspec(TestSpec) -> Result
1011 Types:
1013 TestSpec = [term()]
1015 Result = {Ok, Failed, {UserSkipped, AutoSkipped}} | {error,
1016 Reason}
1017 Ok = integer()
1018 Failed = integer()
1019 UserSkipped = integer()
1020 AutoSkipped = integer()
1021 Reason = term()
1022 Runs a test specified by TestSpec. The same terms are used as in
1024 test specification files.
1025 Reason indicates the type of error encountered.
1027 set_verbosity(Category, Level) -> ok
1029 Types:
1031 Category = default | atom()
1033 Level = integer()
1034 Use this function to set, or modify, the verbosity level for a
1036 logging category. See the User's Guide for details. Use the
1037 value default to set the general verbosity level.
1038 sleep(Time) -> ok
1040 Types:
1042 Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} |
1044 Millisecs | infinity
1045 Hours = integer()
1046 Mins = integer()
1047 Secs = integer()
1048 Millisecs = integer() | float()
1049 This function, similar to timer:sleep/1 in STDLIB, suspends the
1051 test case for a specified time. However, this function also mul‐
1052 tiplies Time with the multiply_timetraps value (if set) and
1053 under certain circumstances also scales up the time automati‐
1054 cally if scale_timetraps is set to true (default is false).
1055 start_interactive() -> ok
1057 Starts Common Test in interactive mode.
1059 From this mode, all test case support functions can be executed
1061 directly from the Erlang shell. The interactive mode can also be
1062 started from the OS command line with ct_run -shell [-config
1063 File...].
1064 If any functions (for example, Telnet or FTP) using "required
1066 configuration data" are to be called from the Erlang shell, con‐
1067 figuration data must first be required with ct:require/2.
1068 Example:
1070 > ct:require(unix_telnet, unix).
1072 ok
1073 > ct_telnet:open(unix_telnet).
1074 {ok,<0.105.0>}
1075 > ct_telnet:cmd(unix_telnet, "ls .").
1076 {ok,["ls","file1 ...",...]}
1077 step(TestDir, Suite, Case) -> Result
1079 Types:
1081 Case = atom()
1083 Steps through a test case with the debugger.
1085 See also ct:run/3.
1087 step(TestDir, Suite, Case, Opts) -> Result
1089 Types:
1091 Case = atom()
1093 Opts = [Opt] | []
1094 Opt = config | keep_inactive
1095 Steps through a test case with the debugger. If option config
1097 has been specifed, breakpoints are also set on the configuration
1098 functions in Suite.
1099 See also ct:run/3.
1101 stop_interactive() -> ok
1103 Exits the interactive mode.
1105 See also ct:start_interactive/0.
1107 sync_notify(Name, Data) -> ok
1109 Types:
1111 Name = atom()
1113 Data = term()
1114 Sends a synchronous notification of type Name with Data to the
1116 Common Test event manager. This can later be caught by any
1117 installed event manager.
1118 See also gen_event(3).
1120 testcases(TestDir, Suite) -> Testcases | {error, Reason}
1122 Types:
1124 TestDir = string()
1126 Suite = atom()
1127 Testcases = list()
1128 Reason = term()
1129 Returns all test cases in the specified suite.
1131 timetrap(Time) -> ok
1133 Types:
1135 Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} |
1137 Millisecs | infinity | Func
1138 Hours = integer()
1139 Mins = integer()
1140 Secs = integer()
1141 Millisecs = integer() | float()
1142 Func = {M, F, A} | function()
1143 M = atom()
1144 F = atom()
1145 A = list()
1146 Sets a new timetrap for the running test case.
1148 If the argument is Func, the timetrap is triggered when this
1150 function returns. Func can also return a new Time value, which
1151 in that case is the value for the new timetrap.
1152 userdata(TestDir, Suite) -> SuiteUserData | {error, Reason}
1154 Types:
1156 TestDir = string()
1158 Suite = atom()
1159 SuiteUserData = [term()]
1160 Reason = term()
1161 Returns any data specified with tag userdata in the list of
1163 tuples returned from suite/0.
1164 userdata(TestDir, Suite, Case::GroupOrCase) -> TCUserData | {error,
1166 Reason}
1167 Types:
1169 TestDir = string()
1171 Suite = atom()
1172 GroupOrCase = {group, GroupName} | atom()
1173 GroupName = atom()
1174 TCUserData = [term()]
1175 Reason = term()
1176 Returns any data specified with tag userdata in the list of
1178 tuples returned from Suite:group(GroupName) or Suite:Case().
1179Ericsson AB common_test 1.15.4.2 ct(3)