diff options
Diffstat (limited to 'lib/common_test/doc')
| -rw-r--r-- | lib/common_test/doc/src/ct.xml | 96 | ||||
| -rw-r--r-- | lib/common_test/doc/src/ct_hooks.xml | 59 | ||||
| -rw-r--r-- | lib/common_test/doc/src/ct_hooks_chapter.xml | 18 | ||||
| -rw-r--r-- | lib/common_test/doc/src/ct_netconfc.xml | 13 | ||||
| -rw-r--r-- | lib/common_test/doc/src/write_test_chapter.xml | 28 |
5 files changed, 161 insertions, 53 deletions
diff --git a/lib/common_test/doc/src/ct.xml b/lib/common_test/doc/src/ct.xml index d215d68f30..a87be21d73 100644 --- a/lib/common_test/doc/src/ct.xml +++ b/lib/common_test/doc/src/ct.xml @@ -661,52 +661,70 @@ <func> <name>log(Format) -> ok</name> - <fsummary>Equivalent to log(default, 50, Format, []).</fsummary> + <fsummary>Equivalent to log(default, 50, Format, [], []).</fsummary> <desc><marker id="log-1"/> <p>Equivalent to - <seealso marker="#log-4"><c>ct:log(default, 50, Format, [])</c></seealso>.</p> + <seealso marker="#log-5"><c>ct:log(default, 50, Format, [], [])</c></seealso>.</p> </desc> </func> <func> <name>log(X1, X2) -> ok</name> <fsummary>Equivalent to log(Category, Importance, Format, - Args).</fsummary> + FormatArgs, []).</fsummary> <type> <v>X1 = Category | Importance | Format</v> - <v>X2 = Format | Args</v> + <v>X2 = Format | FormatArgs</v> </type> <desc><marker id="log-2"/> - <p>Equivalent to <seealso marker="#log-4"><c>ct:log(Category, - Importance, Format, Args)</c></seealso>.</p> + <p>Equivalent to <seealso marker="#log-5"><c>ct:log(Category, + Importance, Format, FormatArgs, [])</c></seealso>.</p> </desc> </func> <func> <name>log(X1, X2, X3) -> ok</name> <fsummary>Equivalent to log(Category, Importance, Format, - Args).</fsummary> + FormatArgs, Opts).</fsummary> <type> <v>X1 = Category | Importance</v> <v>X2 = Importance | Format</v> - <v>X3 = Format | Args</v> + <v>X3 = Format | FormatArgs | Opts</v> </type> <desc><marker id="log-3"/> - <p>Equivalent to <seealso marker="#log-4"><c>ct:log(Category, - Importance, Format, Args)</c></seealso>.</p> + <p>Equivalent to <seealso marker="#log-5"><c>ct:log(Category, + Importance, Format, FormatArgs, Opts)</c></seealso>.</p> </desc> </func> <func> - <name>log(Category, Importance, Format, Args) -> ok</name> + <name>log(X1, X2, X3, X4) -> ok</name> + <fsummary>Equivalent to log(Category, Importance, Format, + FormatArgs, Opts).</fsummary> + <type> + <v>X1 = Category | Importance</v> + <v>X2 = Importance | Format</v> + <v>X3 = Format | FormatArgs</v> + <v>X4 = FormatArgs | Opts</v> + </type> + <desc><marker id="log-4"/> + <p>Equivalent to <seealso marker="#log-5"><c>ct:log(Category, + Importance, Format, FormatArgs, Opts)</c></seealso>.</p> + </desc> + </func> + + <func> + <name>log(Category, Importance, Format, FormatArgs, Opts) -> ok</name> <fsummary>Prints from a test case to the log file.</fsummary> <type> <v>Category = atom()</v> <v>Importance = integer()</v> <v>Format = string()</v> - <v>Args = list()</v> + <v>FormatArgs = list()</v> + <v>Opts = [Opt]</v> + <v>Opt = no_css | esc_chars</v> </type> - <desc><marker id="log-4"/> + <desc><marker id="log-5"/> <p>Prints from a test case to the log file.</p> <p>This function is meant for printing a string directly from a @@ -714,11 +732,15 @@ <p>Default <c>Category</c> is <c>default</c>, default <c>Importance</c> is <c>?STD_IMPORTANCE</c>, - and default value for <c>Args</c> is <c>[]</c>.</p> + and default value for <c>FormatArgs</c> is <c>[]</c>.</p> - <p>For details on <c>Category</c> and <c>Importance</c>, see section - <seealso marker="write_test_chapter#logging">Logging - Categories - and Verbosity Levels</seealso> in the User's Guide.</p> + <p>For details on <c>Category</c>, <c>Importance</c> and the <c>no_css</c> + option, see section <seealso marker="write_test_chapter#logging"> + Logging - Categories and Verbosity Levels</seealso> in the User's Guide.</p> + + <p>Common Test will not escape special HTML characters (<, > and &) + in the text printed with this function, unless the <c>esc_chars</c> + option is used.</p> </desc> </func> @@ -769,40 +791,40 @@ <func> <name>pal(X1, X2) -> ok</name> <fsummary>Equivalent to pal(Category, Importance, Format, - Args).</fsummary> + FormatArgs).</fsummary> <type> <v>X1 = Category | Importance | Format</v> - <v>X2 = Format | Args</v> + <v>X2 = Format | FormatArgs</v> </type> <desc><marker id="pal-2"/> <p>Equivalent to <seealso marker="#pal-4"><c>ct:pal(Category, - Importance, Format, Args)</c></seealso>.</p> + Importance, Format, FormatArgs)</c></seealso>.</p> </desc> </func> <func> <name>pal(X1, X2, X3) -> ok</name> <fsummary>Equivalent to pal(Category, Importance, Format, - Args).</fsummary> + FormatArgs).</fsummary> <type> <v>X1 = Category | Importance</v> <v>X2 = Importance | Format</v> - <v>X3 = Format | Args</v> + <v>X3 = Format | FormatArgs</v> </type> <desc><marker id="pal-3"/> <p>Equivalent to <seealso marker="#pal-4"><c>ct:pal(Category, - Importance, Format, Args)</c></seealso>.</p> + Importance, Format, FormatArgs)</c></seealso>.</p> </desc> </func> <func> - <name>pal(Category, Importance, Format, Args) -> ok</name> + <name>pal(Category, Importance, Format, FormatArgs) -> ok</name> <fsummary>Prints and logs from a test case.</fsummary> <type> <v>Category = atom()</v> <v>Importance = integer()</v> <v>Format = string()</v> - <v>Args = list()</v> + <v>FormatArgs = list()</v> </type> <desc><marker id="pal-4"/> <p>Prints and logs from a test case.</p> @@ -812,11 +834,15 @@ <p>Default <c>Category</c> is <c>default</c>, default <c>Importance</c> is <c>?STD_IMPORTANCE</c>, - and default value for <c>Args</c> is <c>[]</c>.</p> + and default value for <c>FormatArgs</c> is <c>[]</c>.</p> <p>For details on <c>Category</c> and <c>Importance</c>, see section <seealso marker="write_test_chapter#logging">Logging - Categories and Verbosity Levels</seealso> in the User's Guide.</p> + + <p>Note that special characters in the text (<, > and &) will + be escaped by Common Test before the text is printed to the log + file.</p> </desc> </func> @@ -854,40 +880,40 @@ <func> <name>print(X1, X2) -> ok</name> <fsummary>Equivalent to print(Category, Importance, Format, - Args).</fsummary> + FormatArgs).</fsummary> <type> <v>X1 = Category | Importance | Format</v> - <v>X2 = Format | Args</v> + <v>X2 = Format | FormatArgs</v> </type> <desc><marker id="print-2"/> <p>Equivalent to <seealso marker="#print-4"><c>ct:print(Category, - Importance, Format, Args)</c></seealso>.</p> + Importance, Format, FormatArgs)</c></seealso>.</p> </desc> </func> <func> <name>print(X1, X2, X3) -> ok</name> <fsummary>Equivalent to print(Category, Importance, Format, - Args).</fsummary> + FormatArgs).</fsummary> <type> <v>X1 = Category | Importance</v> <v>X2 = Importance | Format</v> - <v>X3 = Format | Args</v> + <v>X3 = Format | FormatArgs</v> </type> <desc><marker id="print-3"/> <p>Equivalent to <seealso marker="#print-4"><c>ct:print(Category, - Importance, Format, Args)</c></seealso>.</p> + Importance, Format, FormatArgs)</c></seealso>.</p> </desc> </func> <func> - <name>print(Category, Importance, Format, Args) -> ok</name> + <name>print(Category, Importance, Format, FormatArgs) -> ok</name> <fsummary>Prints from a test case to the console.</fsummary> <type> <v>Category = atom()</v> <v>Importance = integer()</v> <v>Format = string()</v> - <v>Args = list()</v> + <v>FormatArgs = list()</v> </type> <desc><marker id="print-4"/> <p>Prints from a test case to the console.</p> @@ -897,7 +923,7 @@ <p>Default <c>Category</c> is <c>default</c>, default <c>Importance</c> is <c>?STD_IMPORTANCE</c>, - and default value for <c>Args</c> is <c>[]</c>.</p> + and default value for <c>FormatArgs</c> is <c>[]</c>.</p> <p>For details on <c>Category</c> and <c>Importance</c>, see section <seealso marker="write_test_chapter#logging">Logging - Categories diff --git a/lib/common_test/doc/src/ct_hooks.xml b/lib/common_test/doc/src/ct_hooks.xml index 9c959945d2..12ec3bcec3 100644 --- a/lib/common_test/doc/src/ct_hooks.xml +++ b/lib/common_test/doc/src/ct_hooks.xml @@ -293,6 +293,63 @@ </func> <func> + <name>Module:post_init_per_testcase(TestcaseName, Config, Return, CTHState) -> Result</name> + <fsummary>Called after init_per_testcase.</fsummary> + <type> + <v>TestcaseName = atom()</v> + <v>Config = [{Key,Value}]</v> + <v>Return = NewReturn = Config | SkipOrFail | term()</v> + <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v> + <v>CTHState = NewCTHState = term()</v> + <v>Result = {NewReturn, NewCTHState}</v> + <v>Key = atom()</v> + <v>Value = term()</v> + <v>Reason = term()</v> + </type> + <desc> + <p>OPTIONAL</p> + + <p>This function is called after + <seealso marker="common_test#Module:init_per_testcase-2"><c>init_per_testcase</c></seealso> + if it exists. It behaves the same way as + <seealso marker="ct_hooks#Module:post_init_per_suite-4"><c>post_init_per_suite</c></seealso>, + but for function + <seealso marker="common_test#Module:init_per_testcase-2"><c>init_per_testcase</c></seealso> + instead.</p> + </desc> + </func> + + <func> + <name>Module:pre_end_per_testcase(TestcaseName, InitData, CTHState) -> Result</name> + <fsummary>Called before end_per_testcase.</fsummary> + <type> + <v>TestcaseName = atom()</v> + <v>InitData = Config</v> + <v>Config = NewConfig = [{Key,Value}]</v> + <v>CTHState = NewCTHState = term()</v> + <v>Result = {NewConfig, NewCTHState}</v> + <v>Key = atom()</v> + <v>Value = term()</v> + <v>Reason = term()</v> + </type> + <desc> + <p>OPTIONAL</p> + + <p>This function is called before + <seealso marker="common_test#Module:end_per_testcase-2"><c>end_per_testcase</c></seealso> + if it exists. It behaves the same way as + <seealso marker="ct_hooks#Module:pre_end_per_suite-3"><c>pre_end_per_suite</c></seealso>, + but for function + <seealso marker="common_test#Module:end_per_testcase-2"><c>end_per_testcase</c></seealso> + instead.</p> + + <p>This function can not change the result of the test case by returning skip or fail + tuples, but it may insert items in <c>Config</c> that can be read in + <c>end_per_testcase/2</c> or in <c>post_end_per_testcase/4</c>.</p> + </desc> + </func> + + <func> <name>Module:post_end_per_testcase(TestcaseName, Config, Return, CTHState) -> Result</name> <fsummary>Called after end_per_testcase.</fsummary> <type> @@ -312,7 +369,7 @@ <p>This function is called after <seealso marker="common_test#Module:end_per_testcase-2"><c>end_per_testcase</c></seealso> if it exists. It behaves the same way as - <seealso marker="ct_hooks#Module:post_init_per_suite-4"><c>post_init_per_suite</c></seealso>, + <seealso marker="ct_hooks#Module:post_end_per_suite-4"><c>post_end_per_suite</c></seealso>, but for function <seealso marker="common_test#Module:end_per_testcase-2"><c>end_per_testcase</c></seealso> instead.</p> diff --git a/lib/common_test/doc/src/ct_hooks_chapter.xml b/lib/common_test/doc/src/ct_hooks_chapter.xml index 95943ced94..3eb1945a61 100644 --- a/lib/common_test/doc/src/ct_hooks_chapter.xml +++ b/lib/common_test/doc/src/ct_hooks_chapter.xml @@ -239,6 +239,7 @@ <item><seealso marker="common_test#Module:init_per_suite-1"><c>init_per_suite</c></seealso></item> <item><seealso marker="common_test#Module:init_per_group-2"><c>init_per_group</c></seealso></item> <item><seealso marker="common_test#Module:init_per_testcase-2"><c>init_per_testcase</c></seealso></item> + <item><seealso marker="common_test#Module:end_per_testcase-2"><c>end_per_testcase</c></seealso></item> <item><seealso marker="common_test#Module:end_per_group-2"><c>end_per_group</c></seealso></item> <item><seealso marker="common_test#Module:end_per_suite-1"><c>end_per_suite</c></seealso></item> </list> @@ -281,6 +282,7 @@ <list type="bulleted"> <item><seealso marker="common_test#Module:init_per_suite-1"><c>init_per_suite</c></seealso></item> <item><seealso marker="common_test#Module:init_per_group-2"><c>init_per_group</c></seealso></item> + <item><seealso marker="common_test#Module:init_per_testcase-2"><c>init_per_testcase</c></seealso></item> <item><seealso marker="common_test#Module:end_per_testcase-2"><c>end_per_testcase</c></seealso></item> <item><seealso marker="common_test#Module:end_per_group-2"><c>end_per_group</c></seealso></item> <item><seealso marker="common_test#Module:end_per_suite-1"><c>end_per_suite</c></seealso></item> @@ -393,6 +395,8 @@ -export([post_end_per_group/4]). -export([pre_init_per_testcase/3]). + -export([post_init_per_testcase/4]). + -export([pre_end_per_testcase/3]). -export([post_end_per_testcase/4]). -export([on_tc_fail/3]). @@ -438,7 +442,7 @@ post_init_per_group(Group,Config,Return,State) -> {Return, State}. - %% @doc Called after each end_per_group. + %% @doc Called before each end_per_group. pre_end_per_group(Group,Config,State) -> {Config, State}. @@ -446,11 +450,19 @@ post_end_per_group(Group,Config,Return,State) -> {Return, State}. - %% @doc Called before each test case. + %% @doc Called before each init_per_testcase. pre_init_per_testcase(TC,Config,State) -> {Config, State#state{ ts = now(), total = State#state.suite_total + 1 } }. - %% @doc Called after each test case. + %% Called after each init_per_testcase (immediately before the test case). + post_init_per_testcase(TC,Config,Return,State) -> + {Return, State} + +%% @doc Called before each end_per_testcase (immediately after the test case). + pre_end_per_testcase(TC,Config,State) -> + {Config, State}. + + %% @doc Called after each end_per_testcase. post_end_per_testcase(TC,Config,Return,State) -> TCInfo = {testcase, TC, Return, timer:now_diff(now(), State#state.ts)}, {Return, State#state{ ts = undefined, tcs = [TCInfo | State#state.tcs] } }. diff --git a/lib/common_test/doc/src/ct_netconfc.xml b/lib/common_test/doc/src/ct_netconfc.xml index 77366da891..d8c82c7f2c 100644 --- a/lib/common_test/doc/src/ct_netconfc.xml +++ b/lib/common_test/doc/src/ct_netconfc.xml @@ -218,13 +218,14 @@ <tag><c>notification_content() = [event_time() | simple_xml()]</c></tag> <item><marker id="type-notification_content"/> </item> - <tag><c>option() = {ssh, host()} | {port, <seealso marker="kernel:inet#type-port_number"><c>inet:port_number()</c></seealso>} | {timeout, timeout()} | ssh_connect_option()</c></tag> + <tag><c>option() = {ssh, host()} | {port, <seealso marker="kernel:inet#type-port_number"><c>inet:port_number()</c></seealso>} | {timeout, timeout()} | SshConnectOption</c></tag> <item><marker id="type-option"/> - <p>For <c>ssh_connect_option()</c>, see - <seealso marker="ssh:ssh#connect-3"><c>ssh:connect/3,4</c></seealso>. Common - SSH connect options are <c>user</c>, <c>password</c> - and <c>user_dir</c>, but any option that is verified as valid - by application <c>SSH</c> is allowed.</p></item> + + <p><c>SshConnectOption</c> is any valid option to + <seealso marker="ssh:ssh#connect-3"><c>ssh:connect/3,4</c></seealso>. + Common options used are <c>user</c>, <c>password</c> + and <c>user_dir</c>. The <c>SshConnectOptions</c> are + verfied by the SSH application.</p></item> <tag><c>options() = [option()]</c></tag> <item><marker id="type-options"/> diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml index 8c1d104949..e3811ec4cf 100644 --- a/lib/common_test/doc/src/write_test_chapter.xml +++ b/lib/common_test/doc/src/write_test_chapter.xml @@ -953,11 +953,11 @@ <p><c>Common Test</c> provides the following three main functions for printing strings:</p> <list type="bulleted"> - <item><c>ct:log(Category, Importance, Format, Args)</c></item> - <item><c>ct:print(Category, Importance, Format, Args)</c></item> - <item><c>ct:pal(Category, Importance, Format, Args)</c></item> + <item><c>ct:log(Category, Importance, Format, FormatArgs, Opts)</c></item> + <item><c>ct:print(Category, Importance, Format, FormatArgs)</c></item> + <item><c>ct:pal(Category, Importance, Format, FormatArgs)</c></item> </list> - <p>The <seealso marker="ct#log-1"><c>log/1,2,3,4</c></seealso> function + <p>The <seealso marker="ct#log-1"><c>log/1,2,3,4,5</c></seealso> function prints a string to the test case log file. The <seealso marker="ct#print-1"><c>print/1,2,3,4</c></seealso> function prints the string to screen. @@ -1031,14 +1031,26 @@ 4. Categorized info, importance = 25 6. Categorized error, importance = 99</pre> + <p>The arguments <c>Format</c> and <c>FormatArgs</c> in <c>ct:log/print/pal</c> are + always passed on to the <c>stdlib</c> function <c>io:format/3</c> (For details, + see the <seealso marker="stdlib:io"><c>stdlib:io</c></seealso> manual page).</p> + + <p><c>ct:pal/4</c> and <c>ct:log/5</c> add headers to strings being printed to the + log file. The strings are also wrapped in div tags with a CSS class + attribute, so that stylesheet formatting can be applied. To disable this feature for + a printout (i.e. to get a result similar to using <c>io:format/2</c>), + call <c>ct:log/5</c> with the <c>no_css</c> option.</p> + <p>How categories can be mapped to CSS tags is documented in section <seealso marker="run_test_chapter#html_stylesheet">HTML Style Sheets</seealso> in section Running Tests and Analyzing Results.</p> - - <p>The arguments <c>Format</c> and <c>Args</c> in <c>ct:log/print/pal</c> are - always passed on to function <c>stdlib:io:format/3</c> (For details, see the - <seealso marker="stdlib:io"><c>stdlib:io</c></seealso> manual page).</p> + <p>Common Test will escape special HTML characters (<, > and &) in printouts + to the log file made with <c>ct:pal/4</c> and <c>io:format/2</c>. In order to print + strings with HTML tags to the log, use the <c>ct:log/5</c> function. The character escaping + feature is per default disabled for <c>ct:log/5</c>, but can be enabled with the + <c>esc_chars</c> option.</p> + <p>For more information about log files, see section <seealso marker="run_test_chapter#log_files">Log Files</seealso> in section Running Tests and Analyzing Results.</p> |