From 02e8dc98b5327712f4ae00ac9fcf5feb1d856ba0 Mon Sep 17 00:00:00 2001 From: Peter Andersson Date: Tue, 28 Aug 2012 17:38:15 +0200 Subject: Update the documentation for R15B02 OTP-10050 OTP-10069 OTP-10072 OTP-10087 OTP-9865 OTP-10049 OTP-10089 OTP-10145 OTP-9896 OTP-10135 OTP-10067 OTP-9625 OTP-10127 OTP-10172 OTP-10248 OTP-9625 OTP-10086 --- lib/common_test/doc/src/write_test_chapter.xml | 109 ++++++++++++++++++++++--- 1 file changed, 96 insertions(+), 13 deletions(-) (limited to 'lib/common_test/doc/src/write_test_chapter.xml') diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml index 1fae50577e..90c08032ec 100644 --- a/lib/common_test/doc/src/write_test_chapter.xml +++ b/lib/common_test/doc/src/write_test_chapter.xml @@ -47,7 +47,7 @@ module for details about these functions.

The CT application also includes other modules named - ]]> that + ]]> that provide various support, mainly simplified use of communication protocols such as rpc, snmp, ftp, telnet, etc.

@@ -934,6 +934,99 @@ returned time.

+
+ + Logging - categories and verbosity levels +

Common Test provides three main functions for printing strings:

+ + ct:log(Category, Importance, Format, Args) + ct:print(Category, Importance, Format, Args) + ct:pal(Category, Importance, Format, Args) + +

The log/1/2/3/4 function will print a string to the test case + log file. The print/1/2/3/4 function will print the string to screen, + and the pal/1/2/3/4 function will print the same string both to file and + screen. (The functions are documented in the ct reference manual).

+ +

The optional Category argument may be used to categorize the + log printout, and categories can be used for two things:

+ + To compare the importance of the printout to a specific + verbosity level, and + to format the printout according to a user specific HTML + Style Sheet (CSS). + + +

The Importance argument specifies a level of importance + which, compared to a verbosity level (general and/or set per category), + determines if the printout should be visible or not. Importance + is an arbitrary integer in the range 0..99. Pre-defined constants + exist in the ct.hrl header file. The default importance level, + ?STD_IMPORTANCE (used if the Importance argument is not + provided), is 50. This is also the importance used for standard IO, e.g. + from printouts made with io:format/2, io:put_chars/1, etc.

+ +

Importance is compared to a verbosity level set by means of the + verbosity start flag/option. The verbosity level can be set per + category and/or generally. The default verbosity level, ?STD_VERBOSITY, + is 50, i.e. all standard IO gets printed. If a lower verbosity level is set, + standard IO printouts will be ignored. Common Test performs the following test:

+ 
Importance >= (100-VerbosityLevel)
+

This also means that verbosity level 0 effectively turns all logging off + (with the exception of printouts made by Common Test itself).

+ +

The general verbosity level is not associated with any particular + category. This level sets the threshold for the standard IO printouts, + uncategorized ct:log/print/pal printouts, as well as + printouts for categories with undefined verbosity level.

+ +

Example:

+ 
+
+      Some printouts during test case execution:
+
+        io:format("1. Standard IO, importance = ~w~n", [?STD_IMPORTANCE]),
+        ct:log("2. Uncategorized, importance = ~w", [?STD_IMPORTANCE]),
+        ct:log(info, "3. Categorized info, importance = ~w", [?STD_IMPORTANCE]]),
+        ct:log(info, ?LOW_IMPORTANCE, "4. Categorized info, importance = ~w", [?LOW_IMPORTANCE]),
+        ct:log(error, "5. Categorized error, importance = ~w", [?HI_IMPORTANCE]),
+        ct:log(error, ?HI_IMPORTANCE, "6. Categorized error, importance = ~w", [?MAX_IMPORTANCE]),
+
+      If starting the test without specifying any verbosity levels:
+
+        $ ct_run ...
+
+      the following gets printed:
+      
+        1. Standard IO, importance = 50
+        2. Uncategorized, importance = 50
+        3. Categorized info, importance = 50
+        5. Categorized error, importance = 75
+        6. Categorized error, importance = 99
+
+      If starting the test with:
+        
+        $ ct_run -verbosity 1 and info 75
+      
+      the following gets printed:
+
+        3. Categorized info, importance = 50
+	4. Categorized info, importance = 25
+        6. Categorized error, importance = 99
+
+ +

How categories can be mapped to CSS tags is documented in the + Running Tests + chapter.

+ +

The Format and Args arguments in ct:log/print/pal are + always passed on to the io:format/3 function in stdlib + (please see the io manual page for details).

+ +

For more information about log files, please see the + Running Tests chapter.

+
+
Illegal dependencies @@ -944,7 +1037,6 @@ Erlang/OTP test suites.

- Depending on current directory, and writing there:

This is a common error in test suites. It is assumed that @@ -956,19 +1048,10 @@

- Depending on the Clearcase (file version control system) - paths and files:

- -

The test suites are stored in Clearcase but are not - (necessarily) run within this environment. The directory - structure may vary from test run to test run. -

- - Depending on execution order:

-

During development of test suites, no assumption should be made - (preferrably) about the execution order of the test cases or suites. +

During development of test suites, no assumption should preferrably + be made about the execution order of the test cases or suites. E.g. a test case should not assume that a server it depends on, has already been started by a previous test case. There are several reasons for this: -- cgit v1.2.3