aboutsummaryrefslogtreecommitdiffstats
path: root/lib/common_test/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/common_test/doc')
-rw-r--r--lib/common_test/doc/src/ct.xml96
-rw-r--r--lib/common_test/doc/src/ct_hooks.xml59
-rw-r--r--lib/common_test/doc/src/ct_hooks_chapter.xml18
-rw-r--r--lib/common_test/doc/src/ct_netconfc.xml13
-rw-r--r--lib/common_test/doc/src/write_test_chapter.xml28
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) -&gt; 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) -&gt; 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) -&gt; 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) -&gt; ok</name>
+ <name>log(X1, X2, X3, X4) -&gt; 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) -&gt; 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 (&lt;, &gt; and &amp;)
+ 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) -&gt; 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) -&gt; 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) -&gt; ok</name>
+ <name>pal(Category, Importance, Format, FormatArgs) -&gt; 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 (&lt;, &gt; and &amp;) 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) -&gt; 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) -&gt; 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) -&gt; ok</name>
+ <name>print(Category, Importance, Format, FormatArgs) -&gt; 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) -&gt; 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) -&gt; 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) -&gt; 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 (&lt;, &gt; and &amp;) 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>