From cd932144bd4716b1fa311c909baf0beb3ca77d13 Mon Sep 17 00:00:00 2001 From: Anthony Ramine Date: Sat, 21 Mar 2015 13:11:28 +0100 Subject: Undocument the line macro in test_server Reported-by: Magnus Ottenklinger --- lib/test_server/doc/src/example_chapter.xml | 28 ++++++------ lib/test_server/doc/src/test_server.xml | 66 ++++++----------------------- 2 files changed, 28 insertions(+), 66 deletions(-) (limited to 'lib/test_server/doc/src') diff --git a/lib/test_server/doc/src/example_chapter.xml b/lib/test_server/doc/src/example_chapter.xml index 0ebc85da09..6bc0cfaebe 100644 --- a/lib/test_server/doc/src/example_chapter.xml +++ b/lib/test_server/doc/src/example_chapter.xml @@ -47,7 +47,7 @@ -define(default_timeout, ?t:minutes(1)). init_per_testcase(_Case, Config) -> - ?line Dog=?t:timetrap(?default_timeout), + Dog=?t:timetrap(?default_timeout), [{watchdog, Dog}|Config]. end_per_testcase(_Case, Config) -> Dog=?config(watchdog, Config), @@ -72,8 +72,8 @@ not_started_func1(suite) -> not_started_func1(doc) -> ["Testing function 1 when application is not started"]. not_started_func1(Config) when list(Config) -> - ?line {error, not_started} = myapp:func1(dummy_ref,1), - ?line {error, not_started} = myapp:func1(dummy_ref,2), + {error, not_started} = myapp:func1(dummy_ref,1), + {error, not_started} = myapp:func1(dummy_ref,2), ok. not_started_func2(suite) -> @@ -81,8 +81,8 @@ not_started_func2(suite) -> not_started_func2(doc) -> ["Testing function 2 when application is not started"]. not_started_func2(Config) when list(Config) -> - ?line {error, not_started} = myapp:func2(dummy_ref,1), - ?line {error, not_started} = myapp:func2(dummy_ref,2), + {error, not_started} = myapp:func2(dummy_ref,1), + {error, not_started} = myapp:func2(dummy_ref,2), ok. @@ -90,7 +90,7 @@ not_started_func2(Config) when list(Config) -> start(doc) -> ["Testing start of my application."]; start(Config) when list(Config) -> - ?line Ref = myapp:start(), + Ref = myapp:start(), case erlang:whereis(my_main_process) of Pid when pid(Pid) -> [{myapp_ref,Ref}|Config]; @@ -105,9 +105,9 @@ func1(suite) -> func1(doc) -> ["Test that func1 returns ok when argument is 1 and error if argument is 2"]; func1(Config) when list(Config) -> - ?line Ref = ?config(myapp_ref,Config), - ?line ok = myapp:func1(Ref,1), - ?line error = myapp:func1(Ref,2), + Ref = ?config(myapp_ref,Config), + ok = myapp:func1(Ref,1), + error = myapp:func1(Ref,2), ok. func2(suite) -> @@ -115,17 +115,17 @@ func2(suite) -> func2(doc) -> ["Test that func1 returns ok when argument is 3 and error if argument is 4"]; func2(Config) when list(Config) -> - ?line Ref = ?config(myapp_ref,Config), - ?line ok = myapp:func2(Ref,3), - ?line error = myapp:func2(Ref,4), + Ref = ?config(myapp_ref,Config), + ok = myapp:func2(Ref,3), + error = myapp:func2(Ref,4), ok. %% No specification clause needed for a cleanup function in a conf case!!! stop(doc) -> ["Testing termination of my application"]; stop(Config) when list(Config) -> - ?line Ref = ?config(myapp_ref,Config), - ?line ok = myapp:stop(Ref), + Ref = ?config(myapp_ref,Config), + ok = myapp:stop(Ref), case erlang:whereis(my_main_process) of undefined -> lists:keydelete(myapp_ref,1,Config); diff --git a/lib/test_server/doc/src/test_server.xml b/lib/test_server/doc/src/test_server.xml index ed5569e1fe..b98e434c03 100644 --- a/lib/test_server/doc/src/test_server.xml +++ b/lib/test_server/doc/src/test_server.xml @@ -811,46 +811,12 @@ Only valid for peer nodes. Note that slave nodes always -
- TEST SUITE LINE NUMBERS -

If a test case fails, the test server can report the exact line - number at which it failed. There are two ways of doing this, - either by using the line macro or by using the - test_server_line parse transform. -

-

The line macro is described under TEST SUITE SUPPORT - MACROS below. The line macro will only report the last line - executed when a test case failed. -

-

The test_server_line parse transform is activated by - including the headerfile test_server_line.hrl in the test - suite. When doing this, it is important that the - test_server_line module is in the code path of the erlang - node compiling the test suite. The parse transform will report a - history of a maximum of 10 lines when a test case - fails. Consecutive lines in the same function are not shown. -

-

The attribute -no_lines(FuncList). can be used in the - test suite to exclude specific functions from the parse - transform. This is necessary e.g. for functions that are executed - on old (i.e. <R10B) OTP releases. FuncList = [{Func,Arity}]. -

-

If both the line macro and the parse transform is used in - the same module, the parse transform will overrule the macro. -

-
TEST SUITE SUPPORT MACROS

There are some macros defined in the test_server.hrl that are quite useful for test suite programmers:

-

The line macro, is quite - essential when writing test cases. It tells the test server - exactly what line of code that is being executed, so that it can - report this line back if the test case fails. Use this macro at - the beginning of every test case line of code. -

The config macro, is used to retrieve information from the Config variable sent to all test cases. It is used with two arguments, where the first is the @@ -867,24 +833,20 @@ Only valid for peer nodes. Note that slave nodes always Whatever added by conf test cases or init_per_testcase/2 -

Examples of the line and config macros can be - seen in the Examples chapter in the user's guide. -

-

If the line_trace macro is defined, you will get a - timestamp (erlang:now()) in your minor log for each - line macro in your suite. This way you can at any time see - which line is currently being executed, and when the line was - called. -

-

The line_trace macro can also be used together with the - test_server_line parse transform described above. A - timestamp will then be written for each line in the suite, except - for functions stated in the -no_lines attribute. -

-

The line_trace macro can e.g. be defined as a compile - option, like this: -

-erlc -W -Dline_trace my_SUITE.erl

+

Examples of the config macro can be seen in the Examples chapter + in the user's guide.

+

The line and line_trace macros are deprecated, see + below.

+
+ +
+ TEST SUITE LINE NUMBERS +

In the past, ERTS did not produce line numbers when generating + stacktraces, test_server was thus unable to provide them when reporting + test failures. It had instead two different mecanisms to do it: either by + using the line macro or by using the test_server_line parse + transform. Both are deprecated and should not be used in new tests + anymore.

-- cgit v1.2.3