Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

file 955 lines (829 sloc) 48.694 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

      <holder>Ericsson AB. All Rights Reserved.</holder>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at

      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.


    <title>Running Tests</title>
    <prepared>Peter Andersson, Kenneth Lundin</prepared>

    <title>Using the Common Test Framework</title>

    <p>The Common Test Framework provides a high level
    operator interface for testing. It adds the following features to
    the Erlang/OTP Test Server:</p>

<item>Automatic compilation of test suites (and help modules).</item>
<item>Creation of additional HTML pages for better overview.</item>
<item>Single command interface for running all available tests.</item>
<item>Handling of configuration files specifying data related to
the System Under Test (and any other variable data).</item>
<item>Mode for running multiple independent test sessions in parallel with
central control and configuration.</item>

    <title>Automatic compilation of test suites and help modules</title>
    <p>When Common Test starts, it will automatically attempt to compile any
      suites included in the specified tests. If particular
      suites have been specified, only those suites will be compiled. If a
      particular test object directory has been specified (meaning all suites
      in this directory should be part of the test), Common Test runs
      make:all/1 in the directory to compile the suites.</p>

    <p>If compilation should fail for one or more suites, the compilation errors
      are printed to tty and the operator is asked if the test run should proceed
      without the missing suites, or be aborted. If the operator chooses to proceed,
      it is noted in the HTML log which tests have missing suites.</p>

    <p>Any help module (i.e. regular Erlang module with name not ending with
      "_SUITE") that resides in the same test object directory as a suite
      which is part of the test, will also be automatically compiled. A help
      module will not be mistaken for a test suite (unless it has a "_SUITE"
      name of course). All help modules in a particular test object directory
      are compiled no matter if all or only particular suites in the directory
      are part of the test.</p>

    <p>If test suites or help modules include header files stored in other
      locations than the test directory, you may specify these include directories
      by means of the <c><![CDATA[-include]]></c> flag with <c><![CDATA[ct_run]]></c>,
      or the <c><![CDATA[include]]></c> option with <c><![CDATA[ct:run_test/1]]></c>.
      In addition to this, an include path may be specified with an OS
      environment variable; <c><![CDATA[CT_INCLUDE_PATH]]></c>. Example (bash):</p>

    <p><c>$ export CT_INCLUDE_PATH=~testuser/common_suite_files/include:~testuser/common_lib_files/include</c></p>

    <p>Common Test will pass all include directories (specified either with the
      <c><![CDATA[include]]></c> flag/option, or the <c><![CDATA[CT_INCLUDE_PATH]]></c>
      variable, or both) to the compiler.</p>

    <p>It is also possible to specify include directories in test specifications
      (see below).</p>

    <p>If the user wants to run all test suites for a test object (or OTP application)
      by specifying only the top directory (e.g. with the <c>dir</c> start flag/option),
      Common Test will primarily look for test suite modules in a subdirectory named
      <c>test</c>. If this subdirectory doesn't exist, the specified top directory
      is assumed to be the actual test directory, and test suites will be read from
      there instead.</p>

    <p>It is possible to disable the automatic compilation feature by using the
      <c><![CDATA[-no_auto_compile]]></c> flag with <c><![CDATA[ct_run]]></c>, or
      the <c><![CDATA[{auto_compile,false}]]></c> option with
      <c><![CDATA[ct:run_test/1]]></c>. With automatic compilation
      disabled, the user is responsible for compiling the test suite modules
      (and any help modules) before the test run. If the modules can not be loaded
      from the local file system during startup of Common Test, the user needs to
      pre-load the modules before starting the test. Common Test will only verify
      that the specified test suites exist (i.e. that they are, or can be, loaded).
      This is useful e.g. if the test suites are transferred and loaded as binaries via
      RPC from a remote node.</p>

  <marker id="ct_run"></marker>
    <title>Running tests from the OS command line</title>
    <p>The <c>ct_run</c> program can be used for running tests from
      the OS command line, e.g.
      <item><c><![CDATA[ct_run -config <configfilenames> -dir <dirs>]]></c></item>
      <item><c><![CDATA[ct_run -config <configfilenames> -suite <suiteswithfullpath>]]></c>
      <item><c><![CDATA[ct_run -userconfig <callbackmodulename> <configfilenames> -suite <suiteswithfullpath>]]></c>
      <item><c><![CDATA[ct_run -config <configfilenames> -suite <suitewithfullpath>
-group <groupnames> -case <casenames>]]></c></item>
    <p><c>$ ct_run -config $CFGS/sys1.cfg $CFGS/sys2.cfg -dir $SYS1_TEST $SYS2_TEST</c></p>
    <p><c>$ ct_run -userconfig ct_config_xml $CFGS/sys1.xml $CFGS/sys2.xml -dir $SYS1_TEST $SYS2_TEST</c></p>
    <p><c>$ ct_run -suite $SYS1_TEST/setup_SUITE $SYS2_TEST/config_SUITE</c></p>
    <p><c>$ ct_run -suite $SYS1_TEST/setup_SUITE -case start stop</c></p>
    <p><c>$ ct_run -suite $SYS1_TEST/setup_SUITE -group installation -case start stop</c></p>
    <p>It is also possible to combine the <c>dir</c>, <c>suite</c> and <c>group/case</c> flags. E.g, to run
    <c>x_SUITE</c> and <c>y_SUITE</c> in directory <c>testdir</c>:</p>

    <p><c>$ ct_run -dir ./testdir -suite x_SUITE y_SUITE</c></p>

    <p>This has the same effect as calling:</p>

    <p><c>$ ct_run -suite ./testdir/x_SUITE ./testdir/y_SUITE</c></p>

    <p>Other flags that may be used with <c>ct_run</c>:</p>
      <item><c><![CDATA[-logdir <dir>]]></c>, specifies where the HTML log files are to be written.</item>
      <item><c><![CDATA[-label <name_of_test_run>]]></c>, associates the test run with a name that gets printed
in the overview HTML log files.</item>
      <item><c>-refresh_logs</c>, refreshes the top level HTML index files.</item>
      <item><c>-vts</c>, start web based GUI (see below).</item>
      <item><c>-shell</c>, start interactive shell mode (see below).</item>
      <item><c>-step [step_opts]</c>, step through test cases using the Erlang Debugger (see below).</item>
      <item><c><![CDATA[-spec <testspecs>]]></c>, use test specification as input (see below).</item>
      <item><c>-allow_user_terms</c>, allows user specific terms in a test specification (see below).</item>
      <item><c>-silent_connections [conn_types]</c>, tells Common Test to suppress printouts for
        specified connections (see below).</item>
      <item><c><![CDATA[-stylesheet <css_file>]]></c>, points out a user HTML style sheet (see below).</item>
      <item><c><![CDATA[-cover <cover_cfg_file>]]></c>, to perform code coverage test (see
<seealso marker="cover_chapter#cover">Code Coverage Analysis</seealso>).</item>
      <item><c><![CDATA[-event_handler <event_handlers>]]></c>, to install
        <seealso marker="event_handler_chapter#event_handling">event handlers</seealso>.</item>
      <item><c><![CDATA[-event_handler_init <event_handlers>]]></c>, to install
        <seealso marker="event_handler_chapter#event_handling">event handlers</seealso> including start arguments.</item>
      <item><c><![CDATA[-ct_hooks <ct_hooks>]]></c>, to install
        <seealso marker="ct_hooks_chapter#installing">Common Test Hooks</seealso> including start arguments.</item>
      <item><c><![CDATA[-enable_builtin_hooks <bool>]]></c>, to enable/disable
        <seealso marker="ct_hooks_chapter#builtin_cths">Built-in Common Test Hooks</seealso>. Default is <c>true</c>.</item>
      <item><c><![CDATA[-include]]></c>, specifies include directories (see above).</item>
      <item><c><![CDATA[-no_auto_compile]]></c>, disables the automatic test suite compilation feature (see above).</item>
      <item><c><![CDATA[-multiply_timetraps <n>]]></c>, extends <seealso marker="write_test_chapter#timetraps">timetrap
timeout</seealso> values.</item>
      <item><c><![CDATA[-scale_timetraps <bool>]]></c>, enables automatic <seealso marker="write_test_chapter#timetraps">timetrap
timeout</seealso> scaling.</item>
      <item><c><![CDATA[-repeat <n>]]></c>, tells Common Test to repeat the tests n times (see below).</item>
      <item><c><![CDATA[-duration <time>]]></c>, tells Common Test to repeat the tests for duration of time (see below).</item>
      <item><c><![CDATA[-until <stop_time>]]></c>, tells Common Test to repeat the tests until stop_time (see below).</item>
      <item><c>-force_stop</c>, on timeout, the test run will be aborted when current test job is finished (see below).</item>
      <item><c><![CDATA[-decrypt_key <key>]]></c>, provides a decryption key for
        <seealso marker="config_file_chapter#encrypted_config_files">encrypted configuration files</seealso>.</item>
      <item><c><![CDATA[-decrypt_file <key_file>]]></c>, points out a file containing a decryption key for
        <seealso marker="config_file_chapter#encrypted_config_files">encrypted configuration files</seealso>.</item>
      <item><c><![CDATA[-basic_html]]></c>, switches off html enhancements that might not be compatible with older browsers.</item>
      <item><c><![CDATA[-logopts <opts>]]></c>, makes it possible to modify aspects of the logging behaviour, see
        <seealso marker="run_test_chapter#logopts">Log options</seealso> below.</item>

    <note><p>Directories passed to Common Test may have either relative or absolute paths.</p></note>

    <note><p>Arbitrary start flags to the Erlang Runtime System may also be passed as
             parameters to <c>ct_run</c>. It is, for example, useful to be able to
pass directories that should be added to the Erlang code server search path
with the <c>-pa</c> or <c>-pz</c> flag. If you have common help- or library
modules for test suites (separately compiled), stored in other directories
than the test suite directories, these help/lib directories are preferrably
added to the code path this way. Example:</p>
<p><c>$ ct_run -dir ./chat_server -logdir ./chat_server/testlogs -pa $PWD/chat_server/ebin</c></p>
<p>Note how in this example, the absolute path of the <c>chat_server/ebin</c>
directory is passed to the code server. This is essential since relative
paths are stored by the code server as relative, and Common Test changes
the current working directory of the Erlang Runtime System during the test run!</p>
    <p>For more information about the <c>ct_run</c> program, see the
      <seealso marker="install_chapter#general">Installation</seealso> chapter.
    <title>Running tests from the Web based GUI</title>
    <p>The web based GUI, VTS, is started with the <c>ct_run</c>
      program. From the GUI you can load config files, and select
      directories, suites and cases to run. You can also state the
      config files, directories, suites and cases on the command line
      when starting the web based GUI.
      <item><c>ct_run -vts</c></item>
      <item><c><![CDATA[ct_run -vts -config <configfilename>]]></c></item>
      <item><c><![CDATA[ct_run -vts -config <configfilename> -suite <suitewithfullpath>
-case <casename>]]></c></item>
    <p>From the GUI you can run tests and view the result and the logs.
    <p>Note that <c>ct_run -vts</c> will try to open the Common Test start
      page in an existing web browser window or start the browser if it is
      not running. Which browser should be started may be specified with
      the browser start command option:</p>
      <p><c><![CDATA[ct_run -vts -browser <browser_start_cmd>]]></c></p>
      <p><c><![CDATA[$ ct_run -vts -browser 'firefox&']]></c></p>
      <p>Note that the browser must run as a separate OS process or VTS will hang!</p>
      <p>If no specific browser start command is specified, Firefox will
        be the default browser on Unix platforms and Internet Explorer on Windows.
If Common Test fails to start a browser automatically, or <c>'none'</c> is
specified as the value for -browser (i.e. <c>-browser none</c>), start your
favourite browser manually and type in the URL that Common Test
displays in the shell.</p>
    <title>Running tests from the Erlang shell or from an Erlang program</title>
    <p>Common Test provides an Erlang API for running tests. The main (and most
      flexible) function for specifying and executing tests is called
      <c>ct:run_test/1</c>. This function takes the same start parameters as
      the <c>ct_run</c> program described above, only the flags are instead
      given as options in a list of key-value tuples. E.g. a test specified
      with <c>ct_run</c> like:</p>
      <p><c>$ ct_run -suite ./my_SUITE -logdir ./results</c></p>
      <p>is with <c>ct:run_test/1</c> specified as:</p>
      <p><c>1> ct:run_test([{suite,"./my_SUITE"},{logdir,"./results"}]).</c></p>
      <p>For detailed documentation, please see the <c>ct</c> manual page.</p>
    <title>Running the interactive shell mode</title>
    <p>You can start Common Test in an interactive shell mode where no
      automatic testing is performed. Instead, in this mode, Common Test
      starts its utility processes, installs configuration data (if any),
      and waits for the user to call functions (typically test case support
      functions) from the Erlang shell.</p>

    <p>The shell mode is useful e.g. for debugging test suites, for analysing
      and debugging the SUT during "simulated" test case execution, and
      for trying out various operations during test suite development.</p>

    <p>To invoke the interactive shell mode, you can start an Erlang shell
      manually and call <c>ct:install/1</c> to install any configuration
      data you might need (use <c>[]</c> as argument otherwise), then
      call <c>ct:start_interactive/0</c> to start Common Test. If you use
      the <c>ct_run</c> program, you may start the Erlang shell and Common Test
      in the same go by using the <c>-shell</c> and, optionally, the <c>-config</c>
      and/or <c>-userconfig</c> flag. Examples:
      <item><c>ct_run -shell</c></item>
      <item><c><![CDATA[ct_run -shell -config cfg/db.cfg]]></c></item>
      <item><c><![CDATA[ct_run -shell -userconfig db_login testuser x523qZ]]></c></item>
    <p>If no config file is given with the <c>ct_run</c> command,
      a warning will be displayed. If Common Test has been run from the same
      directory earlier, the same config file(s) will be used
      again. If Common Test has not been run from this directory before, no
      config files will be available.</p>
    <p>If any functions using "required config data" (e.g. ct_telnet or
      ct_ftp functions) are to be called from the erlang shell, config
      data must first be required with <c>ct:require/[1,2]</c>. This is
      equivalent to a <c>require</c> statement in the <seealso
marker="write_test_chapter#suite">Test Suite Info
Function</seealso> or in the <seealso
marker="write_test_chapter#info_function">Test Case Info
       1> ct:require(unix_telnet, unix).
       2> ct_telnet:open(unix_telnet).
       4> ct_telnet:cmd(unix_telnet, "ls .").
       {ok,["ls .","file1 ...",...]}
    <p>Everything that Common Test normally prints in the test case logs,
      will in the interactive mode be written to a log named
      <c>ctlog.html</c> in the <c><![CDATA[ct_run.<timestamp>]]></c>
      directory. A link to this file will be available in the file
      named <c>last_interactive.html</c> in the directory from which
      you executed <c>ct_run</c>. Currently, specifying a different
      root directory for the logs than the current working directory,
      is not supported.</p>
    <p>If you wish to exit the interactive mode (e.g. to start an
      automated test run with <c>ct:run_test/1</c>), call the function
      <c>ct:stop_interactive/0</c>. This shuts down the
      running <c>ct</c> application. Associations between
      configuration names and data created with <c>require</c> are
      consequently deleted. <c>ct:start_interactive/0</c> will get you
      back into interactive mode, but the previous state is not restored.</p>

    <title>Step by step execution of test cases with the Erlang Debugger</title>
    <p>By means of <c>ct_run -step [opts]</c>, or by passing the
       <c>{step,Opts}</c> option to <c>ct:run_test/1</c>, it is possible
       to get the Erlang Debugger started automatically and use its
       graphical interface to investigate the state of the current test
       case and to execute it step by step and/or set execution breakpoints.</p>
    <p>If no extra options are given with the <c>step</c> flag/option,
       breakpoints will be set automatically on the test cases that
       are to be executed by Common Test, and those functions only. If
       the step option <c>config</c> is specified, breakpoints will
       also be initially set on the configuration functions in the suite, i.e.
       <c>init_per_suite/1</c>, <c>end_per_suite/1</c>,
       <c>init_per_group/2</c>, <c>end_per_group/2</c>,
       <c>init_per_testcase/2</c> and <c>end_per_testcase/2</c>.</p>
    <p>Common Test enables the Debugger auto attach feature, which means
       that for every new interpreted test case function that starts to execute,
       a new trace window will automatically pop up. (This is because each test
       case executes on a dedicated Erlang process). Whenever a new test case starts,
       Common Test will attempt to close the inactive trace window of the previous
       test case. However, if you prefer that Common Test leaves inactive trace
       windows, use the <c>keep_inactive</c> option.</p>
    <p>The step functionality can be used together with the <c>suite</c> and
       the <c>suite</c> + <c>case/testcase</c> flag/option, but not together
       with <c>dir</c>.</p>

  <marker id="test_specifications"></marker>
    <title>Using test specifications</title>
    <p>The most flexible way to specify what to test, is to use a so
      called test specification. A test specification is a sequence of
      Erlang terms. The terms may be declared in a text file or passed
      to the test server at runtime as a list
      (see <c>run_testspec/1</c> in the manual page
      for <c>ct</c>). There are two general types of terms:
      configuration terms and test specification terms.</p>
    <p>With configuration terms it is possible to e.g. label the test
      run (similar to <c>ct_run -label</c>), evaluate arbitrary expressions
      before starting a test, import configuration
      data (similar to
      <c>ct_run -config/-userconfig</c>), specify HTML log directories (similar
      <c>ct_run -logdir</c>), give aliases to test nodes and test
      directories (to make a specification easier to read and
      maintain), enable code coverage analysis (see
      the <seealso marker="cover_chapter#cover">Code Coverage
      Analysis</seealso> chapter) and specify event_handler plugins
      (see the <seealso marker="event_handler_chapter#event_handling">
      Event Handling</seealso> chapter). There is also a term for
      specifying include directories that should be passed on to the
      compiler when automatic compilation is performed (similar
      to <c>ct_run -include</c>, see above).</p>
    <p>With test specification terms it is possible to state exactly
      which tests should run and in which order. A test term specifies
      either one or more suites, one or more test case groups, or one
      or more test cases in a group or suite.</p>
    <p>An arbitrary number of test terms may be declared in sequence.
      Common Test will by default compile the terms into one or more tests
      to be performed in one resulting test run. Note that a term that
      specifies a set of test cases will "swallow" one that only
      specifies a subset of these cases. E.g. the result of merging
      one term that specifies that all cases in suite S should be
      executed, with another term specifying only test case X and Y in
      S, is a test of all cases in S. However, if a term specifying
      test case X and Y in S is merged with a term specifying case Z
      in S, the result is a test of X, Y and Z in S. To disable this
      behaviour, it is possible in test specification to set the
      <c>merge_tests</c> term to <c>false</c>.</p>
    <p>A test term can also specify one or more test suites, groups,
      or test cases to be skipped. Skipped suites, groups and cases
      are not executed and show up in the HTML test log files as
    <p>When a test case group is specified, the resulting test
      executes the
      <c>init_per_group</c> function, followed by all test cases and
      sub groups (including their configuration functions), and
      finally the <c>end_per_group</c> function. Also if particular
      test cases in a group are specified, <c>init_per_group</c>
      and <c>end_per_group</c> for the group in question are
      called. If a group which is defined (in <c>Suite:group/0</c>) to
      be a sub group of another group, is specified (or particular test
      cases of a sub group are), Common Test will call the configuration
      functions for the top level groups as well as for the sub group
      in question (making it possible to pass configuration data all
      the way from <c>init_per_suite</c> down to the test cases in the
      sub group).</p>

    <p>With the <c>GroupSpec</c> element (below) it's possible to specify
      group execution properties that will override those specified in the
      group definition (i.e. in <c>groups/0</c>). Execution properties for
      sub-groups may be overridden as well. This feature makes it possible to
      change properties of groups at the time of execution,
      without even having to edit the test suite. More detailed documentation,
      and examples, can be found in the
      <seealso marker="write_test_chapter#test_case_groups">
      Test case groups</seealso> chapter.</p>

    <p>Below is the test specification syntax. Test specifications can
      be used to run tests both in a single test host environment and
      in a distributed Common Test environment (Large Scale
      Testing). The node parameters in the init term are only
      relevant in the latter (see the
      <seealso marker="ct_master_chapter#test_specifications">Large
      Scale Testing</seealso> chapter for information). For details on
      the event_handler term, see the
      <seealso marker="event_handler_chapter#event_handling">Event
      Handling</seealso> chapter.</p>
      <p>Config terms:</p>
      {node, NodeAlias, Node}.

      {init, InitOptions}.
      {init, [NodeAlias], InitOptions}.

      {label, Label}.
      {label, NodeRefs, Label}.

      {multiply_timetraps, N}.
      {multiply_timetraps, NodeRefs, N}.

      {scale_timetraps, Bool}.
      {scale_timetraps, NodeRefs, Bool}.
      {cover, CoverSpecFile}.
      {cover, NodeRefs, CoverSpecFile}.
      {include, IncludeDirs}.
      {include, NodeRefs, IncludeDirs}.

      {config, ConfigFiles}.
      {config, NodeRefs, ConfigFiles}.

      {userconfig, {CallbackModule, ConfigStrings}}.
      {userconfig, NodeRefs, {CallbackModule, ConfigStrings}}.
      {alias, DirAlias, Dir}.

      {merge_tests, Bool}.
      {logdir, LogDir}.
      {logdir, NodeRefs, LogDir}.

      {create_priv_dir, PrivDirOption}.
      {create_priv_dir, NodeRefs, PrivDirOption}.
      {event_handler, EventHandlers}.
      {event_handler, NodeRefs, EventHandlers}.
      {event_handler, EventHandlers, InitArgs}.
      {event_handler, NodeRefs, EventHandlers, InitArgs}.

      {ct_hooks, CTHModules}.
      {ct_hooks, NodeRefs, CTHModules}.

      {enable_builtin_hooks, Bool}.
      <p>Test terms:</p>
      {suites, DirRef, Suites}.
      {suites, NodeRefs, DirRef, Suites}.
      {groups, DirRef, Suite, Groups}.
      {groups, NodeRefsDirRef, Suite, Groups}.

      {groups, DirRef, Suite, GroupSpec, {cases,Cases}}.
      {groups, NodeRefsDirRef, Suite, GroupSpec, {cases,Cases}}.

      {cases, DirRef, Suite, Cases}.
      {cases, NodeRefs, DirRef, Suite, Cases}.

      {skip_suites, DirRef, Suites, Comment}.
      {skip_suites, NodeRefs, DirRef, Suites, Comment}.

      {skip_groups, DirRef, Suite, GroupNames, Comment}.
      {skip_groups, NodeRefs, DirRef, Suite, GroupNames, Comment}.
      {skip_cases, DirRef, Suite, Cases, Comment}.
      {skip_cases, NodeRefs, DirRef, Suite, Cases, Comment}.
      NodeAlias = atom()
      InitOptions = term()
      Node = node()
      NodeRef = NodeAlias | Node | master
      NodeRefs = all_nodes | [NodeRef] | NodeRef
      N = integer()
      Bool = true | false
      CoverSpecFile = string()
      IncludeDirs = string() | [string()]
      ConfigFiles = string() | [string()]
      DirAlias = atom()
      Dir = string()
      LogDir = string()
      PrivDirOption = auto_per_run | auto_per_tc | manual_per_tc
      EventHandlers = atom() | [atom()]
      InitArgs = [term()]
      CTHModules = [CTHModule | {CTHModule, CTHInitArgs} | {CTHModule, CTHInitArgs, CTHPriority}]
      CTHModule = atom()
      CTHInitArgs = term()
      DirRef = DirAlias | Dir
      Suites = atom() | [atom()] | all
      Suite = atom()
      Groups = GroupSpec | [GroupSpec] | all
      GroupSpec = GroupName | {GroupName,Properties} | {GroupName,Properties,GroupSpec}
      GroupName = atom()
      GroupNames = GroupName | [GroupName]
      Cases = atom() | [atom()] | all
      Comment = string() | ""
      {logdir, "/home/test/logs"}.
      {config, "/home/test/t1/cfg/config.cfg"}.
      {config, "/home/test/t2/cfg/config.cfg"}.
      {config, "/home/test/t3/cfg/config.cfg"}.
      {alias, t1, "/home/test/t1"}.
      {alias, t2, "/home/test/t2"}.
      {alias, t3, "/home/test/t3"}.
      {suites, t1, all}.
      {skip_suites, t1, [t1B_SUITE,t1D_SUITE], "Not implemented"}.
      {skip_cases, t1, t1A_SUITE, [test3,test4], "Irrelevant"}.
      {skip_cases, t1, t1C_SUITE, [test1], "Ignore"}.
      {suites, t2, [t2B_SUITE,t2C_SUITE]}.
      {cases, t2, t2A_SUITE, [test4,test1,test7]}.
      {skip_suites, t3, all, "Not implemented"}.
    <p>The example specifies the following:</p>
      <item>The specified logdir directory will be used for storing
the HTML log files (in subdirectories tagged with node name,
date and time).</item>
      <item>The variables in the specified test system config files will be
imported for the test.</item>
      <item>Aliases are given for three test system directories. The suites in
this example are stored in "/home/test/tX/test".</item>
      <item>The first test to run includes all suites for system t1. Excluded from
the test are however the t1B and t1D suites. Also test cases test3 and
test4 in t1A as well as the test1 case in t1C are excluded from
the test.</item>
      <item>Secondly, the test for system t2 should run. The included suites are
t2B and t2C. Included are also test cases test4, test1 and test7 in suite
t2A. Note that the test cases will be executed in the specified order.</item>
      <item>Lastly, all suites for systems t3 are to be completely skipped and this
should be explicitly noted in the log files.</item>
    <p>It is possible to specify initialization options for nodes defined in the
      test specification. Currently, there are options to start the node and/or to
      evaluate any function on the node.
      See the <seealso marker="ct_master_chapter#ct_slave">Automatic startup of
      the test target nodes</seealso> chapter for details.</p>
    <p>It is possible for the user to provide a test specification that
      includes (for Common Test) unrecognizable terms. If this is desired,
      the <c>-allow_user_terms</c> flag should be used when starting tests with
      <c>ct_run</c>. This forces Common Test to ignore unrecognizable terms.
      Note that in this mode, Common Test is not able to check the specification
      for errors as efficiently as if the scanner runs in default mode.
      If <c>ct:run_test/1</c> is used for starting the tests, the relaxed scanner
      mode is enabled by means of the tuple: <c>{allow_user_terms,true}</c></p>
    <title>Log files</title>
    <p>As the execution of the test suites proceed, events are logged in
      four different ways:</p>
<item>Text to the operator's console.</item>
<item>Suite related information is sent to the major log file.</item>
<item>Case related information is sent to the minor log file.</item>
<item>The HTML overview log file gets updated with test results.</item>
<item>A link to all runs executed from a certain directory is written in
the log named "all_runs.html" and direct links to all tests (the
latest results) are written to the top level "index.html".</item>
      <p>Typically the operator, who may run hundreds or thousands of
test cases, doesn't want to fill the console with details
about, or printouts from, the specific test cases. By default, the
operator will only see:</p>
<item>A confirmation that the test has started and information about how
many test cases will be executed totally.</item>
<item>A small note about each failed test case.</item>
<item>A summary of all the run test cases.</item>
<item>A confirmation that the test run is complete.</item>
<item>Some special information like error reports and progress
reports, printouts written with erlang:display/1, or io:format/3
specifically addressed to a receiver other than <c>standard_io</c>
(e.g. the default group leader process 'user').</item>

      <p>If/when the operator wants to dig deeper into the general results, or
        the result of a specific test case, he should do so by
following the links in the HTML presentation and take a look in the
major or minor log files. The "all_runs.html" page is a practical
starting point usually. It's located in <c>logdir</c> and contains
a link to each test run including a quick overview (date and time,
node name, number of tests, test names and test result totals).</p>

      <p>An "index.html" page is written for each test run (i.e. stored in
the "ct_run" directory tagged with node name, date and time). This
file gives a short overview of all individual tests performed in the
same test run. The test names follow this convention:</p>
<item><em>TopLevelDir.TestDir</em> (all suites in TestDir executed)</item>
<item><em>TopLevelDir.TestDir:suites</em> (specific suites were executed)</item>
<item><em>TopLevelDir.TestDir.Suite</em> (all cases in Suite executed)</item>
<item><em>TopLevelDir.TestDir.Suite:cases</em> (specific test cases were executed)</item>
<item><em>TopLevelDir.TestDir.Suite.Case</em> (only Case was executed)</item>
      <p>On the test run index page there is a link to the Common Test
Framework log file in which information about imported
configuration data and general test progress is written. This
log file is useful to get snapshot information about the test
run during execution. It can also be very helpful when
analyzing test results or debugging test suites.</p>

      <p>On the test run index page it is noted if a test has missing
        suites (i.e. suites that Common Test has failed to
        compile). Names of the missing suites can be found in the
        Common Test Framework log file.</p>

      <p>The major logfile shows a detailed report of the test run. It
        includes test suite and test case names, execution time, the
exact reason for failures etc. The information is available in both
a file with textual and with HTML representation. The HTML file shows a
summary which gives a good overview of the test run. It also has links
to each individual test case log file for quick viewing with an HTML
      <p>The minor log files contain full details of every single test
case, each one in a separate file. This way, it should be
straightforward to compare the latest results to that of previous
test runs, even if the set of test cases changes. If SASL is running,
its logs will also be printed to the current minor log file by the
<seealso marker="common_test:ct_hooks_chapter#builtin_cths">
cth_log_redirect built-in hook</seealso>.

      <p>The full name of the minor log file (i.e. the name of the file
including the absolute directory path) can be read during execution
of the test case. It comes as value in the tuple
<c>{tc_logfile,LogFileName}</c> in the <c>Config</c> list (which means it
can also be read by a pre- or post Common Test hook function). Also,
at the start of a test case, this data is sent with an event
to any installed event handler. Please see the
<seealso marker="event_handler_chapter#event_handling">Event Handling</seealso>
chapter for details.
      <p>Which information goes where is user configurable via the
test server controller. Three threshold values determine what
comes out on screen, and in the major or minor log files. See
the OTP Test Server manual for information. The contents that
goes to the HTML log file is fixed however and cannot be altered.</p>

      <p>The log files are written continously during a test run and links are
always created initially when a test starts. This makes it possible
to follow test progress simply by refreshing pages in the HTML browser.
Statistics totals are not presented until a test is complete however.</p>

<marker id="logopts"></marker>
<title>Log options</title>
<p>With the <c>logopts</c> start flag, it's possible to specify
options that modify some aspects of the logging behaviour.
Currently, the following options are available:</p>
<p>With <c>no_src</c>, the html version of the test suite source
code will not be generated during the test run (and consequently
not be available in the log file system).</p>
<p>With <c>no_nl</c>, Common Test will not add a newline character
(\n) to the end of an output string that it receives from a call to e.g.
<c>io:format/2</c>, and which it prints to the test case log.</p>
<p>For example, if a test is started with:</p>
<p><c>$ ct_run -suite my_SUITE -logopts no_src</c></p>
<p>then printouts during the test made by successive calls to <c>io:format("x")</c>,
will appear in the test case log as:</p>
<p>instead of each <c>x</c> printed on a new line, which is the default behaviour.</p>

<marker id="html_stylesheet"></marker>
<title>HTML Style Sheets</title>
<p>Common Test uses a CSS file to control the look of the HTML
files generated during test runs. If, for some reason, the
log files are not displayed correctly in the HTML browser of your
choice, or you prefer the "pre Common Test v1.6 look"
of the log files (i.e. not using CSS), use the start flag/option
<c>basic_html</c> to revert to the old style.</p>

<p>Common Test includes an <em>optional</em> feature to allow
user HTML style sheets for customizing printouts. The
functions in <c>ct</c> that print to a test case HTML log
file (<c>log/3</c> and <c>pal/3</c>) accept <c>Category</c>
as first argument. With this argument it's possible to
specify a category that can be mapped to a selector in a CSS
definition. This is useful especially for coloring text
differently depending on the type of (or reason for) the
printout. Say you want one color for test system
configuration information, a different one for test system
state information and finally one for errors detected by the
test case functions. The corresponding style sheet may
look like this:</p>

div.sys_config { background:blue; color:white }
div.sys_state { background:yellow; color:black }
div.error { background:red; color:white }</pre>

<p>To install the CSS file (Common Test inlines the definition in the
HTML code), the name may be provided when executing <c>ct_run</c>.

$ ct_run -dir $TEST/prog -stylesheet $TEST/styles/test_categories.css</pre>

<p>Categories in a CSS file installed with the <c>-stylesheet</c> flag
are on a global test level in the sense that they can be used in any
suite which is part of the test run.</p>

<p>It is also possible to install style sheets on a per suite and
per test case basis. Example:</p>

suite() -> [..., {stylesheet,"suite_categories.css"}, ...].
my_testcase(_) ->
ct:log(sys_config, "Test node version: ~p", [VersionInfo]),
ct:log(sys_state, "Connections: ~p", [ConnectionInfo]),
ct:pal(error, "Error ~p detected! Info: ~p", [SomeFault,ErrorInfo]),

<p>If the style sheet is installed as in this example, the categories are
private to the suite in question. They can be used by all test cases in the
suite, but can not be used by other suites. A suite private style sheet,
if specified, will be used in favour of a global style sheet (one specified
with the <c>-stylesheet</c> flag). A stylesheet tuple (as returned by <c>suite/0</c>
above) can also be returned from a test case info function. In this case the
categories specified in the style sheet can only be used in that particular
test case. A test case private style sheet is used in favour of a suite or
global level style sheet.

<p>In a tuple <c>{stylesheet,CSSFile}</c>, if <c>CSSFile</c> is specified
with a path, e.g. <c>"$TEST/styles/categories.css"</c>, this full
name will be used to locate the file. If only the file name is specified
however, e.g. "categories.css", then the CSS file is assumed to be located
in the data directory, <c>data_dir</c>, of the suite. The latter usage is
recommended since it is portable compared to hard coding path names in the

<p>The <c>Category</c> argument in the example above may have the
value (atom) <c>sys_config</c> (white on blue), <c>sys_state</c>
(black on yellow) or <c>error</c> (white on red).</p>

    <marker id="repeating_tests"></marker>
    <title>Repeating tests</title>
    <p>You can order Common Test to repeat the tests you specify. You can choose
       to repeat tests a certain number of times, repeat tests for a specific period of time,
       or repeat tests until a particular stop time is reached. If repetition is controlled by
       means of time, it is also possible to specify what action Common Test should
       take upon timeout. Either Common Test performs all tests in the current run before stopping,
       or it stops as soon as the current test job is finished. Repetition can be activated by
       means of <c>ct_run</c> start flags, or tuples in the <c>ct:run:test/1</c>
       option list argument. The flags (options in parenthesis) are:</p>
       <item><c>-repeat N ({repeat,N})</c>, where <c>N</c> is a positive integer.</item>
       <item><c>-duration DurTime ({duration,DurTime})</c>, where <c>DurTime</c> is the duration, see below.</item>
       <item><c>-until StopTime ({until,StopTime})</c>, where <c>StopTime</c> is finish time, see below.</item>
       <item><c>-force_stop ({force_stop,true})</c></item>
       <p>The duration time, <c>DurTime</c>, is specified as <c>HHMMSS</c>. Example:
          <c>-duration 012030</c> or <c>{duration,"012030"}</c>, means the tests will
be executed and (if time allows) repeated, until timeout occurs after 1 h, 20 min
and 30 secs.
<c>StopTime</c> can be specified as <c>HHMMSS</c> and is then interpreted as a time today
(or possibly tomorrow). <c>StopTime</c> can also be specified as <c>YYMoMoDDHHMMSS</c>.
Example: <c>-until 071001120000</c> or <c>{until,"071001120000"}</c>, which means the tests
will be executed and (if time allows) repeated, until 12 o'clock on the 1st of Oct 2007.</p>

       <p>When timeout occurs, Common Test will never abort the test run immediately, since
          this might leave the system under test in an undefined, and possibly bad, state.
Instead Common Test will finish the current test job, or the complete test
run, before stopping. The latter is the default behaviour. The <c>force_stop</c>
flag/option tells Common Test to stop as soon as the current test job is finished.
Note that since Common Test always finishes off the current test job or test session,
the time specified with <c>duration</c> or <c>until</c> is never definitive!</p>

       <p>Log files from every single repeated test run is saved in normal Common Test fashion (see above).
          Common Test may later support an optional feature to only store the last (and possibly
the first) set of logs of repeated test runs, but for now the user must be careful not
to run out of disk space if tests are repeated during long periods of time.</p>

       <p>Note that for each test run that is part of a repeated session, information about the
          particular test run is printed in the Common Test Framework Log. There you can read
the repetition number, remaining time, etc.</p>

       <p>Example 1:</p>
          $ ct_run -dir $TEST_ROOT/to1 $TEST_ROOT/to2 -duration 001000 -force_stop</pre>
       <p>Here the suites in test directory to1, followed by the suites in to2, will be executed
          in one test run. A timeout event will occur after 10 minutes. As long as there is time
left, Common Test will repeat the test run (i.e. starting over with the to1 test).
When the timeout occurs, Common Test will stop as soon as the current job is finished
(because of the <c>force_stop</c> flag). As a result, the specified test run might be
aborted after the to1 test and before the to2 test.</p>

       <p>Example 2:</p>
          $ date
Fri Sep 28 15:00:00 MEST 2007

          $ ct_run -dir $TEST_ROOT/to1 $TEST_ROOT/to2 -until 160000</pre>
       <p>Here the same test run as in the example above will be executed (and possibly repeated).
          In this example, however, the timeout will occur after 1 hour and when that happens,
Common Test will finish the entire test run before stopping (i.e. the to1 and to2 test
will always both be executed in the same test run).</p>
       <p>Example 3:</p>
          $ ct_run -dir $TEST_ROOT/to1 $TEST_ROOT/to2 -repeat 5</pre>
       <p>Here the test run, including both the to1 and the to2 test, will be repeated 5 times.</p>

       <note><p>This feature should not be confused with the <c>repeat</c> property of a test
          case group. The options described here are used to repeat execution of entire test runs,
while the <c>repeat</c> property of a test case group makes it possible to repeat
execution of sets of test cases within a suite. For more information about the latter,
see the <seealso marker="write_test_chapter#test_case_groups">Writing Test Suites</seealso>

    <marker id="silent_connections"></marker>
      <title>Silent Connections</title>
      <p>The protocol handling processes in Common Test, implemented by ct_telnet, ct_ftp etc,
do verbose printing to the test case logs. This can be switched off by means
of the <c>-silent_connections</c> flag:</p>
ct_run -silent_connections [conn_types]
      <p>where <c>conn_types</c> specifies <c>telnet, ftp, rpc</c> and/or <c>snmp</c>.</p>
ct_run ... -silent_connections telnet ftp</pre>
      <p>switches off logging for telnet and ftp connections.</p>
ct_run ... -silent_connections</pre>
      <p>switches off logging for all connection types.</p>
      <p>Basic and important information such as opening and closing a connection,
fatal communication error and reconnection attempts will always be printed even
if logging has been suppressed for the connection type in question. However, operations
such as sending and receiving data may be performed silently.</p>
      <p>It is possible to also specify <c>silent_connections</c> in a test suite. This is
accomplished by returning a tuple, <c>{silent_connections,ConnTypes}</c>, in the
<c>suite/0</c> or test case info list. If <c>ConnTypes</c> is a list of atoms
(<c>telnet, ftp, rpc</c> and/or <c>snmp</c>), output for any corresponding connections
will be suppressed. Full logging is per default enabled for any connection of type not
specified in <c>ConnTypes</c>. Hence, if <c>ConnTypes</c> is the empty list, logging
is enabled for all connections.</p>
      <p>The <c>silent_connections</c> setting returned from a test case info function overrides,
for the test case in question, any setting made with <c>suite/0</c> (which is the setting
used for all cases in the suite). Example:</p>

suite() -> [..., {silent_connections,[telnet,ftp]}, ...].
my_testcase1() ->
my_testcase1(_) ->
my_testcase2(_) ->
      <p>In this example, <c>suite/0</c> tells Common Test to suppress
printouts from telnet and ftp connections. This is valid for
all test cases. However, <c>my_testcase1/0</c> specifies that
for this test case, only ftp should be silent. The result is
that <c>my_testcase1</c> will get telnet info (if any) printed
in the log, but not ftp info. <c>my_testcase2</c> will get no
info from either connection printed.</p>
      <p>The <c>-silent_connections</c> tag (or
<c>silent_connections</c> tagged tuple in the call to
<c>ct:run_test/1</c>) overrides any settings in the test
      <p>Note that in the current Common Test version, the
<c>silent_connections</c> feature only works for telnet
connections. Support for other connection types will be added
in future Common Test versions.</p>
Something went wrong with that request. Please try again.