diff options
Diffstat (limited to 'lib/common_test/doc')
| -rw-r--r-- | lib/common_test/doc/src/ct_master_chapter.xml | 2 | ||||
| -rw-r--r-- | lib/common_test/doc/src/event_handler_chapter.xml | 9 | ||||
| -rw-r--r-- | lib/common_test/doc/src/install_chapter.xml | 63 | ||||
| -rw-r--r-- | lib/common_test/doc/src/notes.xml | 220 | ||||
| -rw-r--r-- | lib/common_test/doc/src/run_test_chapter.xml | 25 |
5 files changed, 258 insertions, 61 deletions
diff --git a/lib/common_test/doc/src/ct_master_chapter.xml b/lib/common_test/doc/src/ct_master_chapter.xml index 37a0805055..adfe79e41a 100644 --- a/lib/common_test/doc/src/ct_master_chapter.xml +++ b/lib/common_test/doc/src/ct_master_chapter.xml @@ -198,7 +198,7 @@ <section> <title>Automatic startup of test target nodes</title> <marker id="ct_slave"></marker> - <p>Is is possible to automatically start, and perform initial actions, on + <p>It is possible to automatically start, and perform initial actions, on test target nodes by using the test specification term <c>init</c>.</p> <p>Currently, two sub-terms are supported, <c>node_start</c> and <c>eval</c>.</p> <p>Example:</p> diff --git a/lib/common_test/doc/src/event_handler_chapter.xml b/lib/common_test/doc/src/event_handler_chapter.xml index 45f01c12ec..f39f391818 100644 --- a/lib/common_test/doc/src/event_handler_chapter.xml +++ b/lib/common_test/doc/src/event_handler_chapter.xml @@ -59,6 +59,15 @@ Event handlers plugged into this manager will receive the events from all the test nodes as well as information from the CT Master server itself.</p> + + <p>User specific event handlers may be plugged into a Common Test event + manager, either by telling Common Test to install them before the test + run (see below), or by adding the handlers dynamically during the test + run by means of + <c>gen_event:add_handler/3</c> or <c>gen_event:add_sup_handler/3</c>. + In the latter scenario, the reference of the Common Test event manager is + required. To get it, call <c>ct:get_event_mgr_ref/0</c> or (on the CT + Master node) <c>ct_master:get_event_mgr_ref/0</c>.</p> </section> <section> <marker id="usage"></marker> diff --git a/lib/common_test/doc/src/install_chapter.xml b/lib/common_test/doc/src/install_chapter.xml index 7f8c606324..31125b945c 100644 --- a/lib/common_test/doc/src/install_chapter.xml +++ b/lib/common_test/doc/src/install_chapter.xml @@ -34,7 +34,7 @@ <title>General information</title> <p>The two main interfaces for running tests with Common Test - are an executable program named ct_run and an + are an executable program named <c>ct_run</c> and an erlang module named <c>ct</c>. The ct_run program is compiled for the underlying operating system (e.g. Unix/Linux or Windows) during the build of the Erlang/OTP system, and is @@ -43,67 +43,10 @@ The <c>ct</c> interface functions can be called from the Erlang shell, or from any Erlang function, on any supported platform.</p> - <p>A legacy Bourne shell script - named run_test - exists, - which may be manually generated and installed. This script may be used - instead of the ct_run program mentioned above, e.g. if the user - wishes to modify or customize the Common Test start flags in a simpler - way than making changes to the ct_run C program.</p> - <p>The Common Test application is installed with the Erlang/OTP system and no additional installation step is required to start using - Common Test by means of the ct_run executable program, and/or the interface - functions in the <c>ct</c> module. If you wish to use the legacy Bourne - shell script version run_test, however, this script needs to be - generated first, according to the instructions below.</p> - - <note><p>Before reading on, please note that since Common Test version - 1.5, the run_test shell script is no longer required for starting - tests with Common Test from the OS command line. The ct_run - program (descibed above) is the new recommended command line interface - for Common Test. The shell script exists mainly for legacy reasons and - may not be updated in future releases of Common Test. It may even be removed. - </p></note> - - <p>Optional step to generate a shell script for starting Common Test:</p> - <p>To generate the run_test shell script, navigate to the - <c><![CDATA[common_test-<vsn>]]></c> directory, located among the other - OTP applications (under the OTP lib directory). Here execute the - <c>install.sh</c> script with argument <c>local</c>:</p> - - <p><c> - $ ./install.sh local - </c></p> - - <p>This generates the executable run_test script in the - <c><![CDATA[common_test-<vsn>/priv/bin]]></c> directory. The script - will include absolute paths to the Common Test and Test Server - application directories, so it's possible to copy or move the script to - a different location on the file system, if desired, without having to - update it. It's of course possible to leave the script under the - <c>priv/bin</c> directory and update the PATH variable accordingly (or - create a link or alias to it).</p> - - <p>If you, for any reason, have copied Common Test and Test Server - to a different location than the default OTP lib directory, you can - generate a run_test script with a different top level directory, - simply by specifying the directory, instead of <c>local</c>, when running - <c>install.sh</c>. Example:</p> - - <p><c> - $ install.sh /usr/local/test_tools - </c></p> - - <p>Note that the <c><![CDATA[common_test-<vsn>]]></c> and - <c><![CDATA[test_server-<vsn>]]></c> directories must be located under the - same top directory. Note also that the install script does not copy files - or update environment variables. It only generates the run_test - script.</p> - - <p>Whenever you install a new version of Erlang/OTP, the run_test - script needs to be regenerated, or updated manually with new directory names - (new version numbers), for it to "see" the latest Common Test and Test Server - versions.</p> - + Common Test by means of the <c>ct_run</c> executable program, and/or + the interface functions in the <c>ct</c> module.</p> </section> </chapter> diff --git a/lib/common_test/doc/src/notes.xml b/lib/common_test/doc/src/notes.xml index 94738d2eff..472e3b7833 100644 --- a/lib/common_test/doc/src/notes.xml +++ b/lib/common_test/doc/src/notes.xml @@ -32,6 +32,226 @@ <file>notes.xml</file> </header> +<section><title>Common_Test 1.10.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A fault in the Common Test logger process, that caused + the application to crash when running on a long name + node, has been corrected.</p> + <p> + Own Id: OTP-12643</p> + </item> + <item> + <p> + A 'wait_for_prompt' option in ct_telnet:expect/3 has been + introduced which forces the function to not return until + a prompt string has been received, even if other expect + patterns have already been found.</p> + <p> + Own Id: OTP-12688 Aux Id: seq12818 </p> + </item> + <item> + <p> + If the last expression in a test case causes a timetrap + timeout, the stack trace is ignored and not printed to + the test case log file. This happens because the + {Suite,TestCase,Line} info is not available in the stack + trace in this scenario, due to tail call elimination. + Common Test has been modified to handle this situation by + inserting a {Suite,TestCase,last_expr} tuple in the + correct place and printing the stack trace as expected.</p> + <p> + Own Id: OTP-12697 Aux Id: seq12848 </p> + </item> + <item> + <p> + Fixed a buffer problem in ct_netconfc which could cause + that some messages where buffered forever.</p> + <p> + Own Id: OTP-12698 Aux Id: seq12844 </p> + </item> + <item> + <p> + The VTS mode in Common Test has been modified to use a + private version of the Webtool application (ct_webtool).</p> + <p> + Own Id: OTP-12704 Aux Id: OTP-10922 </p> + </item> + <item> + <p> + Add possibility to add user capabilities in + <c>ct_netconfc:hello/3</c>.</p> + <p> + Own Id: OTP-12707 Aux Id: seq12846 </p> + </item> + </list> + </section> + +</section> + +<section><title>Common_Test 1.10</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The tests overview file, index.html, did not always get + updated correctly after a new test run. This was because + of a bug in the Common Test log cache mechanism which has + now been corrected.</p> + <p> + Own Id: OTP-11400</p> + </item> + <item> + <p> + When a successful test case returns, Common Test should, + according to the documentation, send a tc_done event to + the event handlers with Result = ok in the data field. + However, Common Test sets Result to the return value of + the test case instead. Common Test has been modified now + to comply with the documentation.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12279 Aux Id: seq12737, OTP-12531 </p> + </item> + <item> + <p> + A ct_telnet:expect/3 call could never be aborted before + an idle_timeout, even if total_timeout had been set to a + lower value (i.e. a shorter time). This problem has been + fixed.</p> + <p> + Own Id: OTP-12335</p> + </item> + <item> + <p> + The undocumented return value {skipped,Reason} from + config functions and test cases was handled + inconsistently. Test cases were e.g. reported as + "skipped" to CT Hook functions, but "successful" to event + handlers. Now, the above return value is consistently + handled the same way as {skip,Reason} and this has also + been documented.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12359 Aux Id: seq12760 </p> + </item> + <item> + <p> + The Erlang source code to HTML generator would sometimes + fail because epp:parse_erl_form/1 could not find and + expand required macros in included header files. The + problem has been solved by making sure common_test always + passes the full include path to epp. Also, a bug that + could cause erl_syntax:revert/1 to fail because of a + badly formed syntax tree has been corrected.</p> + <p> + Own Id: OTP-12419</p> + </item> + <item> + <p> + A missing group option in the ct_run help text has been + added.</p> + <p> + Own Id: OTP-12433 Aux Id: seq12788 </p> + </item> + <item> + <p> + Printouts by means of ct:log/2/3 or ct:pal/2/3 from the + hook functions on_tc_fail/2 and on_tc_skip/2 would (quite + unexpectedly) end up in the "unexpected i/o" log file + instead of in the test case log file. This behaviour has + been changed so that now, all printouts (including stdio + printouts) from these hook functions will be routed to + the test case log file.</p> + <p> + Own Id: OTP-12468</p> + </item> + <item> + <p> + ct_netconfc:action/3 will now - if the return type is + void - accept an RPC reply on the form + {ok,[simple_xml()]}, and in this event return only the + atom ok.</p> + <p> + Own Id: OTP-12491 Aux Id: seq12797 </p> + </item> + <item> + <p> + OTP-11971 erroneously changed the handling of relative + paths for incl_dirs specified in the cover spec file. + This is now corrected so these are expected to be + relative to the directory where the cover spec file + itself is stored</p> + <p> + Own Id: OTP-12498 Aux Id: OTP-11971 </p> + </item> + <item> + <p> + Some test cases have been updated to use ct:sleep/1 + instead of timer:sleep/1. The reason being that the sleep + times need to be scaled to compensate for slow execution + (e.g. when cover is running).</p> + <p> + Own Id: OTP-12574</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Common Test now exports a function, + ct:get_event_mgr_ref/0, that returns the name of the + Common Test event manager. This makes it possible to plug + in event handlers to the event manager while tests are + running (using the gen_event API).</p> + <p> + Own Id: OTP-12506 Aux Id: seq12802 </p> + </item> + <item> + <p> + When a test case (or configuration function) fails + because of an exit signal from a linked process, Common + Test previously passed only the reason for process + termination to the CT post hook functions and the event + handlers (in the tc_done event). This has been changed so + that now the tuple {'EXIT',ReasonForProcessTermination} + is passed instead. This makes it much easier in the CT + post hook functions to distinguish a failure of this sort + from other types of errors and from the return value of a + successful test case.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12531 Aux Id: OTP-12279 </p> + </item> + <item> + <p> + A new feature has been introduced in ct_telnet:get_data/1 + that makes it possible to automatically poll the telnet + connection in case an incomplete string (one that has not + yet been terminated by a newline) remains in the receive + buffer. The polling is controlled by two new telnet + config values, which are documented in the ct_telnet + reference manual. The polling mechanism is disabled by + default (making the get_data/1 function backwards + compatible).</p> + <p> + Own Id: OTP-12627</p> + </item> + </list> + </section> + +</section> + <section><title>Common_Test 1.9</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml index 864f82cb63..df60e5f7f2 100644 --- a/lib/common_test/doc/src/run_test_chapter.xml +++ b/lib/common_test/doc/src/run_test_chapter.xml @@ -1005,6 +1005,31 @@ for starting the tests, the relaxed scanner mode is enabled by means of the tuple: <c>{allow_user_terms,true}</c></p> </section> + <section> + <title>Reading test specification terms</title> + <p>It's possible to look up terms in the current test specification + (i.e. the spec that's been used to configure and run the current test). + The function <c>get_testspec_terms()</c> returns a list of all test spec + terms (both config- and test terms) and <c>get_testspec_terms(Tags)</c> + returns the term (or a list of terms) matching the tag (or tags) in + <c>Tags</c>.</p> + <p>For example, in the test specification:</p> + <pre> + ... + {label, my_server_smoke_test}. + {config, "../../my_server_setup.cfg"}. + {config, "../../my_server_interface.cfg"}. + ...</pre> + <p>And in e.g. a test suite or a CT hook function:</p> + <pre> + ... + [{label,[{_Node,TestType}]}, {config,CfgFiles}] = + ct:get_testspec_terms([label,config]), + + [verify_my_server_cfg(TestType, CfgFile) || {Node,CfgFile} <- CfgFiles, + Node == node()]; + ...</pre> + </section> </section> <section> |