File 0158-eunit-Complete-the-transition-away-from-edoc-markup.patch of Package erlang
From 2d3650a19ad9212dfa9422382e81d70bde1a58df Mon Sep 17 00:00:00 2001
From: Richard Carlsson <carlsson.richard@gmail.com>
Date: Sat, 6 Dec 2025 16:11:23 +0100
Subject: [PATCH] eunit: Complete the transition away from edoc markup
---
lib/eunit/doc/overview.edoc | 1085 ----------------------------
lib/eunit/src/eunit.erl | 61 --
lib/eunit/src/eunit_autoexport.erl | 5 +-
lib/eunit/src/eunit_data.erl | 189 ++---
lib/eunit/src/eunit_lib.erl | 35 +-
lib/eunit/src/eunit_listener.erl | 5 +-
lib/eunit/src/eunit_proc.erl | 34 +-
lib/eunit/src/eunit_serial.erl | 5 +-
lib/eunit/src/eunit_server.erl | 7 +-
lib/eunit/src/eunit_striptests.erl | 6 +-
lib/eunit/src/eunit_surefire.erl | 10 -
lib/eunit/src/eunit_test.erl | 35 +-
lib/eunit/src/eunit_tests.erl | 5 +-
lib/eunit/src/eunit_tty.erl | 5 +-
14 files changed, 160 insertions(+), 1327 deletions(-)
delete mode 100644 lib/eunit/doc/overview.edoc
diff --git a/lib/eunit/doc/overview.edoc b/lib/eunit/doc/overview.edoc
deleted file mode 100644
index c5f8402dac..0000000000
--- a/lib/eunit/doc/overview.edoc
+++ /dev/null
@@ -1,1085 +0,0 @@
-
- -*- html -*-
-
-<!--
-%CopyrightBegin%
-
-SPDX-License-Identifier: Apache-2.0
-
-Copyright Ericsson AB 2000-2025. All Rights Reserved.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-
-%CopyrightEnd%
--->
-
- EUnit overview page
-
-@title EUnit - a Lightweight Unit Testing Framework for Erlang
-
-@author Richard Carlsson <carlsson.richard@gmail.com>
-@author Mickaël Rémond <mickael.remond@process-one.net>
- [http://www.process-one.net/]
-@copyright 2004-2007 Mickaël Rémond, Richard Carlsson
-@version {@version}, {@date} {@time}
-
-@doc EUnit is a unit testing framework for Erlang. It is very powerful
-and flexible, is easy to use, and has small syntactical overhead.
-
-<ul>
-<li>{@section Unit testing}</li>
-<li>{@section Terminology}</li>
-<li>{@section Getting started}</li>
-<li>{@section EUnit macros}</li>
-<li>{@section EUnit test representation}</li>
-</ul>
-
-EUnit builds on ideas from the family of unit testing frameworks for
-Object Oriented languages that originated with JUnit by Beck and Gamma
-(and Beck's previous framework SUnit for Smalltalk). However, EUnit uses
-techniques more adapted to functional and concurrent programming, and is
-typically less verbose than its relatives.
-
-Although EUnit uses many preprocessor macros, they have been designed to
-be as nonintrusive as possible, and should not cause conflicts with
-existing code. Adding EUnit tests to a module should thus not normally
-require changing existing code. Furthermore, tests that only exercise
-the exported functions of a module can always be placed in a completely
-separate module, avoiding any conflicts entirely.
-
-== Unit testing ==
-
-Unit Testing is testing of individual program "units" in relative
-isolation. There is no particular size requirement: a unit can be a
-function, a module, a process, or even a whole application, but the most
-typical testing units are individual functions or modules. In order to
-test a unit, you specify a set of individual tests, set up the smallest
-necessary environment for being able to run those tests (often, you
-don't need to do any setup at all), you run the tests and collect the
-results, and finally you do any necessary cleanup so that the test can
-be run again later. A Unit Testing Framework tries to help you in each
-stage of this process, so that it is easy to write tests, easy to run
-them, and easy to see which tests failed (so you can fix the bugs).
-
-=== Advantages of unit testing ===
-
-<dl>
- <dt>Reduces the risks of changing the program</dt>
- <dd>Most programs will be modified during their lifetime: bugs will be
- fixed, features will be added, optimizations may become necessary, or
- the code will need to be refactored or cleaned up in other ways to
- make it easier to work with. But every change to a working program is
- a risk of introducing new bugs - or reintroducing bugs that had
- previously been fixed. Having a set of unit tests that you can run
- with very little effort makes it easy to know that the code still
- works as it should (this use is called <em>regression testing</em>;
- see {@section Terminology}). This goes a long way to reduce the
- resistance to changing and refactoring code.</dd>
- <dt>Helps guide and speed up the development process</dt>
- <dd>By focusing on getting the code to pass the tests, the programmer
- can become more productive, not overspecify or get lost in premature
- optimizations, and create code that is correct from the very beginning
- (so-called <em>test-driven development</em>; see {@section
- Terminology}).</dd>
- <dt>Helps separate interface from implementation</dt>
- <dd>When writing tests, the programmer may discover dependencies
- (in order to get the tests to run) that ought not to be there, and
- which need to be abstracted away to get a cleaner design. This helps
- eliminate bad dependencies before they spread throughout the
- code.</dd>
- <dt>Makes component integration easier</dt>
- <dd>By testing in a bottom-up fashion, beginning with the smallest
- program units and creating a confidence in that they work as they
- should, it becomes easier to test that a higher-level component,
- consisting of several such units, also behaves according to
- specification (known as <em>integration testing</em>; see {@section
- Terminology}).</dd>
- <dt>Is self-documenting</dt>
- <dd>The tests can be read as documentation, typically showing both
- examples of correct and incorrect usage, along with the expected
- consequences.</dd>
-</dl>
-
-== Terminology ==
-
-<dl>
- <dt>Unit testing</dt>
- <dd>Testing that a program unit behaves as it is supposed to do (in
- itself), according to its specifications. Unit tests have an important
- function as regression tests, when the program later is modified for
- some reason, since they check that the program still behaves according
- to specification.</dd>
- <dt>Regression testing</dt>
- <dd>Running a set of tests after making changes to a program, to check
- that the program behaves as it did before the changes (except, of
- course, for any intentional changes in behaviour). Unit tests are
- important as regression tests, but regression testing can involve more
- than just unit testing, and may also test behaviour that might not be
- part of the normal specification (such as bug-for-bug-compatibility).
- </dd>
- <dt>Integration testing</dt>
- <dd>Testing that a number of individually developed program units
- (assumed to already have been separately unit tested) work together as
- expected. Depending on the system being developed, integration testing
- may be as simple as "just another level of unit testing", but might
- also involve other kinds of tests (compare <em>system testing</em>).
-</dd>
- <dt>System testing</dt>
- <dd>Testing that a complete system behaves according to its
- specification. Specifically, system testing should not require knowing
- any details about the implementation. It typically involves testing
- many different aspects of the system behaviour apart from the basic
- functionality, such as performance, usability, and reliability.</dd>
- <dt>Test-driven development</dt>
- <dd>A program development technique where you continuously write tests
- <em>before</em> you implement the code that is supposed to pass those
- tests. This can help you focus on solving the right problems, and not
- make a more complicated implementation than necessary, by letting the
- unit tests determine when a program is "done": if it fulfils its
- specifications, there is no need to keep adding functionality.</dd>
- <dt>Mock object</dt>
- <dd>Sometimes, testing some unit `A' (e.g., a function) requires that
- it collaborates somehow with some other unit `B' (perhaps being passed
- as an argument, or by reference) - but `B' has not been implemented
- yet. A "mock object" - an object which, for the purposes of testing
- `A', looks and behaves like a real `B' - might then be used instead.
- (This is of course only useful if it would be significantly more work
- to implement a real `B' than to create a mock object.)</dd>
- <dt>Test case</dt>
- <dd>A single, well-defined test, that somehow can be uniquely
- identified. When executed, the test case either <em>passes</em> or
- <em>fails</em>; the test report should identify exactly which test
- cases failed.</dd>
- <dt>Test suite</dt>
- <dd>A collection of test cases, generally with a specific, common
- target for testing, such as a single function, module, or subsystem. A
- test suite may also be recursively composed by smaller test
- suites.</dd>
-</dl>
-
-== Getting started ==
-<ul>
- <li>{@section Including the EUnit header file}</li>
- <li>{@section Writing simple test functions}</li>
- <li>{@section Running EUnit}</li>
- <li>{@section Writing test generating functions}</li>
- <li>{@section An example}</li>
- <li>{@section Disabling testing}</li>
- <li>{@section Avoiding compile-time dependency on EUnit}</li>
-</ul>
-
-=== Including the EUnit header file ===
-
-The simplest way to use EUnit in an Erlang module is to add the
-following line at the beginning of the module (after the `-module'
-declaration, but before any function definitions):
-```-include_lib("eunit/include/eunit.hrl").'''
-
-This will have the following effect:
-<ul>
- <li>Creates an exported function `test()' (unless testing is turned
- off, and the module does not already contain a test() function), that
- can be used to run all the unit tests defined in the module</li>
- <li>Causes all functions whose names match `..._test()' or `..._test_()'
- to be automatically exported from the module (unless testing is
- turned off, or the `EUNIT_NOAUTO' macro is defined)</li>
- <li>Makes all the preprocessor macros of EUnit available, to help
- writing tests</li>
-</ul>
-
-<strong>Note:</strong> For `-include_lib(...)' to work, the Erlang
-module search path <em>must</em> contain a directory whose name ends in
-`eunit/ebin' (pointing to the `ebin' subdirectory of the EUnit
-installation directory). If EUnit is installed as `lib/eunit' under your
-Erlang/OTP system directory, its `ebin' subdirectory will be
-automatically added to the search path when Erlang starts. Otherwise,
-you need to add the directory explicitly, by passing a `-pa' flag to the
-`erl' or `erlc' command. For example, a Makefile could contain the
-following action for compiling `.erl' files:
-```erlc -pa "path/to/eunit/ebin" $(ERL_COMPILE_FLAGS) -o$(EBIN) $<'''
-or if you want Eunit to always be available when you run Erlang
-interactively, you can add a line like the following to your
-`$HOME/.erlang' file:
-```code:add_path("/path/to/eunit/ebin").'''
-
-=== Writing simple test functions ===
-
-The EUnit framework makes it extremely easy to write unit tests in
-Erlang. There are a few different ways of writing them, though, so we
-start with the simplest:
-
-A function with a name ending in `..._test()' is recognized by EUnit as
-a simple test function - it takes no arguments, and its execution either
-succeeds (returning some arbitrary value that EUnit will throw away), or
-fails by throwing an exception of some kind (or by not terminating, in
-which case it will be aborted after a while).
-
-An example of a simple test function could be the following:
-```reverse_test() -> lists:reverse([1,2,3]).'''
-This just tests that the function `lists:reverse(List)' does not crash
-when `List' is `[1,2,3]'. It is not a great test, but many people write
-simple functions like this one to test the basic functionality of their
-code, and those tests can be used directly by EUnit, without changes,
-as long as their function names match.
-
-==== Use exceptions to signal failure ====
-
-To write more interesting tests, we need to make them crash (throw an
-exception) when they don't get the result they expect. A simple way of
-doing this is to use pattern matching with `=', as in the following
-examples:
-```reverse_nil_test() -> [] = lists:reverse([]).
- reverse_one_test() -> [1] = lists:reverse([1]).
- reverse_two_test() -> [2,1] = lists:reverse([1,2]).
-'''
-If there was some bug in `lists:reverse/1' that made it return something
-other than `[2,1]' when it got `[1,2]' as input, then the last test
-above would throw a `badmatch' error. The first two (we assume they do
-not get a `badmatch') would simply return `[]' and `[1]', respectively,
-so both succeed. (Note that EUnit is not psychic: if you write a test
-that returns a value, even if it is the wrong value, EUnit will consider
-it a success. You must make sure that the test is written so that it
-causes a crash if the result is not what it should be.)
-
-==== Using assert macros ====
-
-If you want to use Boolean operators for your tests, the `assert'
-macro comes in handy (see {@section EUnit macros} for details):
-```length_test() -> ?assert(length([1,2,3]) =:= 3).'''
-The `?assert(Expression)' macro will evaluate `Expression', and if that
-does not evaluate to `true', it will throw an exception; otherwise it
-just returns `ok'. In the above example, the test will thus fail if the
-call to `length' does not return 3.
-
-=== Running EUnit ===
-
-If you have added the declaration
-`-include_lib("eunit/include/eunit.hrl")' to your module, as described
-above, you only need to compile the module, and run the automatically
-exported function `test()'. For example, if your module was named `m',
-then calling `m:test()' will run EUnit on all the tests defined in the
-module. You do not need to write `-export' declarations for the test
-functions. This is all done by magic.
-
-You can also use the function {@link eunit:test/1} to run arbitrary
-tests, for example to try out some more advanced test descriptors (see
-{@section EUnit test representation}). For example, running
-``eunit:test(m)'' does the same thing as the auto-generated function
-``m:test()'', while ``eunit:test({inparallel, m})'' runs the same test
-cases but executes them all in parallel.
-
-==== Putting tests in separate modules ====
-
-If you want to separate your test code from your normal code (at least
-for testing the exported functions), you can simply write the test
-functions in a module named `m_tests' (note: not `m_test'), if your
-module is named `m'. Then, whenever you ask EUnit to test the module
-`m', it will also look for the module `m_tests' and run those tests as
-well. See `ModuleName' in the section {@section Primitives} for details.
-
-==== EUnit captures standard output ====
-
-If your test code writes to the standard output, you may be surprised to
-see that the text does not appear on the console when the tests are
-running. This is because EUnit captures all standard output from test
-functions (this also includes setup and cleanup functions, but not
-generator functions), so that it can be included in the test report if
-errors occur. To bypass EUnit and print text directly to the console
-while testing, you can write to the `user' output stream, as in
-`io:format(user, "~w", [Term])'. The recommended way of doing this is to
-use the EUnit {@section Debugging macros}, which make it much simpler.
-
-For checking the output produced by the unit under test, see
-{@section Macros for checking output}.
-
-=== Writing test generating functions ===
-
-A drawback of simple test functions is that you must write a separate
-function (with a separate name) for each test case. A more compact way
-of writing tests (and much more flexible, as we shall see), is to write
-functions that <em>return</em> tests, instead of <em>being</em> tests.
-
-A function with a name ending in `..._test_()' (note the final
-underscore) is recognized by EUnit as a <em>test generator</em>
-function. Test generators return a <em>representation</em> of a <em>set
-of tests</em> to be executed by EUnit.
-
-==== Representing a test as data ====
-
-The most basic representation of a test is a single fun-expression that
-takes no arguments. For example, the following test generator:
-```basic_test_() ->
- fun () -> ?assert(1 + 1 =:= 2) end.'''
-will have the same effect as the following simple test:
-```simple_test() ->
- ?assert(1 + 1 =:= 2).'''
-(in fact, EUnit will handle all simple tests just like it handles
-fun-expressions: it will put them in a list, and run them one by one).
-
-==== Using macros to write tests ====
-
-To make tests more compact and readable, as well as automatically add
-information about the line number in the source code where a test
-occurred (and reduce the number of characters you have to type), you can
-use the `_test' macro (note the initial underscore character), like
-this:
-```basic_test_() ->
- ?_test(?assert(1 + 1 =:= 2)).'''
-The `_test' macro takes any expression (the "body") as argument, and
-places it within a fun-expression (along with some extra information).
-The body can be any kind of test expression, just like the body of a
-simple test function.
-
-==== Underscore-prefixed macros create test objects ====
-
-But this example can be made even shorter! Most test macros, such as the
-family of `assert' macros, have a corresponding form with an initial
-underscore character, which automatically adds a `?_test(...)' wrapper.
-The above example can then simply be written:
-```basic_test_() ->
- ?_assert(1 + 1 =:= 2).'''
-which has exactly the same meaning (note the `_assert' instead of
-`assert'). You can think of the initial underscore as signalling
-<em>test object</em>.
-
-=== An example ===
-
-Sometimes, an example says more than a thousand words. The following
-small Erlang module shows how EUnit can be used in practice.
-```-module(fib).
- -export([fib/1]).
- -include_lib("eunit/include/eunit.hrl").
-
- fib(0) -> 1;
- fib(1) -> 1;
- fib(N) when N > 1 -> fib(N-1) + fib(N-2).
-
- fib_test_() ->
- [?_assert(fib(0) =:= 1),
- ?_assert(fib(1) =:= 1),
- ?_assert(fib(2) =:= 2),
- ?_assert(fib(3) =:= 3),
- ?_assert(fib(4) =:= 5),
- ?_assert(fib(5) =:= 8),
- ?_assertException(error, function_clause, fib(-1)),
- ?_assert(fib(31) =:= 2178309)
- ].'''
-
-(Author's note: When I first wrote this example, I happened to write a
-`*' instead of `+' in the `fib' function. Of course, this showed up
-immediately when I ran the tests.)
-
-See {@section EUnit test representation} for a full list of all the ways
-you can specify test sets in EUnit.
-
-=== Disabling testing ===
-
-Testing can be turned off by defining the `NOTEST' macro when compiling,
-for example as an option to `erlc', as in:
-```erlc -DNOTEST my_module.erl'''
-or by adding a macro definition to the code, <em>before the EUnit header
-file is included</em>:
-```-define(NOTEST, 1).'''
-(the value is not important, but should typically be 1 or `true').
-Note that unless the `EUNIT_NOAUTO' macro is defined, disabling testing
-will also automatically strip all test functions from the code, except
-for any that are explicitly declared as exported.
-
-For instance, to use EUnit in your application, but with testing turned
-off by default, put the following lines in a header file:
-```-define(NOTEST, true).
- -include_lib("eunit/include/eunit.hrl").'''
-and then make sure that every module of your application includes that
-header file. This means that you have a single place to modify in
-order to change the default setting for testing. To override the `NOTEST'
-setting without modifying the code, you can define `TEST' in a compiler
-option, like this:
-```erlc -DTEST my_module.erl'''
-
-See {@section Compilation control macros} for details about these
-macros.
-
-=== Avoiding compile-time dependency on EUnit ===
-
-If you are distributing the source code for your application for other
-people to compile and run, you probably want to ensure that the code
-compiles even if EUnit is not available. Like the example in the
-previous section, you can put the following lines in a common header
-file:
-```-ifdef(TEST).
- -include_lib("eunit/include/eunit.hrl").
- -endif.'''
-and, of course, also make sure that you place all test code that uses
-EUnit macros within `-ifdef(TEST)' or `-ifdef(EUNIT)' sections.
-
-
-== EUnit macros ==
-
-Although all the functionality of EUnit is available even without the
-use of preprocessor macros, the EUnit header file defines a number of
-such macros in order to make it as easy as possible to write unit tests
-as compactly as possible and without getting too many details in the
-way.
-
-Except where explicitly stated, using EUnit macros will never introduce
-run-time dependencies on the EUnit library code, regardless of whether
-your code is compiled with testing enabled or disabled.
-
-<ul>
-<li>{@section Basic macros}</li>
-<li>{@section Compilation control macros}</li>
-<li>{@section Utility macros}</li>
-<li>{@section Assert macros}</li>
-<li>{@section Macros for checking output}</li>
-<li>{@section Macros for running external commands}</li>
-<li>{@section Debugging macros}</li>
-</ul>
-
-=== Basic macros ===
-
-<dl>
-<dt>`_test(Expr)'</dt>
-<dd>Turns `Expr' into a "test object", by wrapping it in a
-fun-expression and a source line number. Technically, this is the same
-as `{?LINE, fun () -> (Expr) end}'.
-</dd>
-</dl>
-
-=== Compilation control macros ===
-
-<dl>
-<dt>`EUNIT'</dt>
-<dd>This macro is always defined to `true' whenever EUnit is enabled at
-compile time. This is typically used to place testing code within
-conditional compilation, as in:
-```-ifdef(EUNIT).
- % test code here
- ...
- -endif.'''
-e.g., to ensure that the code can be compiled without including the
-EUnit header file, when testing is disabled. See also the macros `TEST'
-and `NOTEST'.
-</dd>
-
-<dt>`EUNIT_NOAUTO'</dt>
-<dd>If this macro is defined, the automatic exporting or stripping of
-test functions will be disabled.
-</dd>
-
-<dt>`TEST'</dt>
-<dd>This macro is always defined (to `true', unless previously defined
-by the user to have another value) whenever EUnit is enabled at compile
-time. This can be used to place testing code within conditional
-compilation; see also the macros `NOTEST' and `EUNIT'.
-
-For testing code that is strictly dependent on EUnit, it may be
-preferable to use the `EUNIT' macro for this purpose, while for code
-that uses more generic testing conventions, using the `TEST' macro may
-be preferred.
-
-The `TEST' macro can also be used to override the `NOTEST' macro. If
-`TEST' is defined <em>before</em> the EUnit header file is
-included (even if `NOTEST' is also defined), then the code will be
-compiled with EUnit enabled.
-</dd>
-
-<dt>`NOTEST'</dt>
-<dd>This macro is always defined (to `true', unless previously defined
-by the user to have another value) whenever EUnit is <em>disabled</em>
-at compile time. (Compare the `TEST' macro.)
-
-This macro can also be used for conditional compilation, but is more
-typically used to disable testing: If `NOTEST' is defined
-<em>before</em> the EUnit header file is included, and `TEST'
-is <em>not</em> defined, then the code will be compiled with EUnit
-disabled. See also {@section Disabling testing}.
-</dd>
-
-<dt>`NOASSERT'</dt>
-<dd>If this macro is defined, the assert macros will have no effect,
-when testing is also disabled. See {@section Assert macros}. When
-testing is enabled, the assert macros are always enabled automatically
-and cannot be disabled.
-</dd>
-
-<dt>`ASSERT'</dt>
-<dd>If this macro is defined, it overrides the NOASSERT macro, forcing
-the assert macros to always be enabled regardless of other settings.
-</dd>
-
-<dt>`NODEBUG'</dt>
-<dd>If this macro is defined, the debugging macros will have no effect.
-See {@section Debugging macros}. `NODEBUG' also implies `NOASSERT',
-unless testing is enabled.
-</dd>
-
-<dt>`DEBUG'</dt>
-<dd>If this macro is defined, it overrides the NODEBUG macro, forcing
-the debugging macros to be enabled.
-</dd>
-</dl>
-
-=== Utility macros ===
-
-The following macros can make tests more compact and readable:
-
-<dl>
-<dt>`LET(Var,Arg,Expr)'</dt>
-<dd>Creates a local binding `Var = Arg' in `Expr'. (This is the same as
-`(fun(Var)->(Expr)end)(Arg)'.) Note that the binding is not exported
-outside of `Expr', and that within `Expr', this binding of `Var' will
-shadow any binding of `Var' in the surrounding scope.
-</dd>
-<dt>`IF(Cond,TrueCase,FalseCase)'</dt>
-<dd>Evaluates `TrueCase' if `Cond' evaluates to `true', or otherwise
-evaluates `FalseCase' if `Cond' evaluates to `false'. (This is the same
-as `(case (Cond) of true->(TrueCase); false->(FalseCase) end)'.) Note
-that it is an error if `Cond' does not yield a boolean value.
-</dd>
-</dl>
-
-=== Assert macros ===
-
-(Note that these macros also have corresponding forms which start with
-an "`_'" (underscore) character, as in `?_assert(BoolExpr)', that create
-a "test object" instead of performing the test immediately. This is
-equivalent to writing `?_test(assert(BoolExpr))', etc.)
-
-If the macro `NOASSERT' is defined before the EUnit header file is
-included, these macros have no effect when testing is also disabled; see
-{@section Compilation control macros} for details.
-
-<dl>
-<dt>`assert(BoolExpr)'</dt>
-<dd>Evaluates the expression `BoolExpr', if testing is enabled. Unless
-the result is `true', an informative exception will be generated. If
-there is no exception, the result of the macro expression is the atom
-`ok', and the value of `BoolExpr' is discarded. If testing is disabled,
-the macro will not generate any code except the atom `ok', and
-`BoolExpr' will not be evaluated.
-
-Typical usage:
-```?assert(f(X, Y) =:= [])'''
-
-The `assert' macro can be used anywhere in a program, not just in unit
-tests, to check pre/postconditions and invariants. For example:
-```some_recursive_function(X, Y, Z) ->
- ?assert(X + Y > Z),
- ...'''
-</dd>
-<dt>`assertNot(BoolExpr)'</dt>
-<dd>Equivalent to `assert(not (BoolExpr))'.
-</dd>
-<dt>`assertMatch(GuardedPattern, Expr)'</dt>
-<dd>Evaluates `Expr' and matches the result against `GuardedPattern', if
-testing is enabled. If the match fails, an informative exception will be
-generated; see the `assert' macro for further details. `GuardedPattern'
-can be anything that you can write on the left hand side of the `->'
-symbol in a case-clause, except that it cannot contain comma-separated
-guard tests.
-
-The main reason for using `assertMatch' also for simple matches, instead
-of matching with `=', is that it produces more detailed error messages.
-
-Examples:
-```?assertMatch({found, {fred, _}}, lookup(bloggs, Table))'''
-```?assertMatch([X|_] when X > 0, binary_to_list(B))'''
-</dd>
-<dt>`assertNotMatch(GuardedPattern, Expr)'</dt>
-<dd>The inverse case of assertMatch, for convenience.
-</dd>
-<dt>`assertEqual(Expect, Expr)'</dt>
-<dd>Evaluates the expressions `Expect' and `Expr' and compares the
-results for equality, if testing is enabled. If the values are not
-equal, an informative exception will be generated; see the `assert'
-macro for further details.
-
-`assertEqual' is more suitable than `assertMatch' when the
-left-hand side is a computed value rather than a simple pattern, and
-gives more details than `?assert(Expect =:= Expr)'.
-
-Examples:
-```?assertEqual("b" ++ "a", lists:reverse("ab"))'''
-```?assertEqual(foo(X), bar(Y))'''
-</dd>
-<dt>`assertNotEqual(Unexpected, Expr)'</dt>
-<dd>The inverse case of assertEqual, for convenience.
-</dd>
-<dt>`assertException(ClassPattern, TermPattern, Expr)'</dt>
-<dt>`assertError(TermPattern, Expr)'</dt>
-<dt>`assertExit(TermPattern, Expr)'</dt>
-<dt>`assertThrow(TermPattern, Expr)'</dt>
-<dd>Evaluates `Expr', catching any exception and testing that it matches
-the expected `ClassPattern:TermPattern'. If the match fails, or if no
-exception is thrown by `Expr', an informative exception will be
-generated; see the `assert' macro for further details. The
-`assertError', `assertExit', and `assertThrow' macros, are equivalent to
-using `assertException' with a `ClassPattern' of `error', `exit', or
-`throw', respectively.
-
-Examples:
-```?assertError(badarith, X/0)'''
-```?assertExit(normal, exit(normal))'''
-```?assertException(throw, {not_found,_}, throw({not_found,42}))'''
-</dd>
-</dl>
-
-=== Macros for checking output ===
-
-The following macro can be used within a test case to retrieve the
-output written to standard output.
-
-<dl>
-<dt>`capturedOutput'</dt>
-<dd>The output captured by EUnit in the current test case, as a string.
-
-Examples:
-
-```io:format("Hello~n"),
- ?assertEqual("Hello\n", ?capturedOutput)'''
-</dd>
-</dl>
-
-=== Macros for running external commands ===
-
-Keep in mind that external commands are highly dependent on the
-operating system. You can use the standard library function `os:type()'
-in test generator functions, to produce different sets of tests
-depending on the current operating system.
-
-Note: these macros introduce a run-time dependency on the EUnit library
-code, if compiled with testing enabled.
-
-<dl>
-<dt>`assertCmd(CommandString)'</dt>
-<dd>Runs `CommandString' as an external command, if testing is enabled.
-Unless the returned status value is 0, an informative exception will be
-generated. If there is no exception, the result of the macro expression
-is the atom `ok'. If testing is disabled, the macro will not generate
-any code except the atom `ok', and the command will not be executed.
-
-Typical usage:
-```?assertCmd("mkdir foo")'''
-</dd>
-<dt>`assertCmdStatus(N, CommandString)'</dt>
-<dd>Like the `assertCmd(CommandString)' macro, but generates an
-exception unless the returned status value is `N'.
-</dd>
-<dt>`assertCmdOutput(Text, CommandString)'</dt>
-<dd>Runs `CommandString' as an external command, if testing is enabled.
-Unless the output produced by the command exactly matches the specified
-string `Text', an informative exception will be generated. (Note that
-the output is normalized to use a single LF character as line break on
-all platforms.) If there is no exception, the result of the macro
-expression is the atom `ok'. If testing is disabled, the macro will not
-generate any code except the atom `ok', and the command will not be
-executed.
-</dd>
-<dt>`cmd(CommandString)'</dt>
-<dd>Runs `CommandString' as an external command. Unless the returned
-status value is 0 (indicating success), an informative exception will be
-generated; otherwise, the result of the macro expression is the output
-produced by the command, as a flat string. The output is normalized to
-use a single LF character as line break on all platforms.
-
-This macro is useful in the setup and cleanup sections of fixtures,
-e.g., for creating and deleting files or perform similar operating
-system specific tasks, to make sure that the test system is informed of
-any failures.
-
-A Unix-specific example:
-```{setup,
- fun () -> ?cmd("mktemp") end,
- fun (FileName) -> ?cmd("rm " ++ FileName) end,
- ...}'''
-</dd>
-</dl>
-
-=== Debugging macros ===
-
-To help with debugging, EUnit defines several useful macros for printing
-messages directly to the console (rather than to the standard output).
-Furthermore, these macros all use the same basic format, which includes
-the file and line number where they occur, making it possible in some
-development environments (e.g., when running Erlang in an Emacs buffer)
-to simply click on the message and jump directly to the corresponding
-line in the code.
-
-If the macro `NODEBUG' is defined before the EUnit header file is
-included, these macros have no effect; see
-{@section Compilation control macros} for details.
-
-<dl>
-<dt>`debugHere'</dt>
-<dd>Just prints a marker showing the current file and line number. Note
-that this is an argument-less macro. The result is always `ok'.</dd>
-<dt>`debugMsg(Text)'</dt>
-<dd>Outputs the message `Text' (which can be a plain string, an IO-list,
-or just an atom). The result is always `ok'.</dd>
-<dt>`debugFmt(FmtString, Args)'</dt>
-<dd>This formats the text like `io:format(FmtString, Args)' and outputs
-it like `debugMsg'. The result is always `ok'.</dd>
-<dt>`debugVal(Expr)'</dt>
-<dd>Prints both the source code for `Expr' and its current value. E.g.,
-`?debugVal(f(X))' might be displayed as "`f(X) = 42'". (Large terms are
-truncated to the depth given by the macro `EUNIT_DEBUG_VAL_DEPTH', which
-defaults to 15 but can be overridden by the user.) The result is always the
-value of `Expr', so this macro can be wrapped around any expression to
-display its value when the code is compiled with debugging enabled.</dd>
-<dt>`debugVal(Expr, Depth)'</dt>
-<dd>Like `debugVal(Expr)', but prints terms truncated to the given depth.</dd>
-<dt>`debugTime(Text,Expr)'</dt>
-<dd>Prints `Text' and the wall clock time for evaluation of `Expr'. The
-result is always the value of `Expr', so this macro can be wrapped
-around any expression to show its run time when the code is compiled
-with debugging enabled. For example, `List1 = ?debugTime("sorting",
-lists:sort(List))' might show as "`sorting: 0.015 s'".</dd>
-
-</dl>
-
-
-== EUnit test representation ==
-
-The way EUnit represents tests and test sets as data is flexible,
-powerful, and concise. This section describes the representation in
-detail.
-
-<ul>
-<li>{@section Simple test objects}</li>
-<li>{@section Test sets and deep lists}</li>
-<li>{@section Titles}</li>
-<li>{@section Primitives}</li>
-<li>{@section Control}</li>
-<li>{@section Fixtures}</li>
-<li>{@section Lazy generators}</li>
-</ul>
-
-=== Simple test objects ===
-
-A <em>simple test object</em> is one of the following:
-<ul>
- <li>A nullary functional value (i.e., a fun that takes zero
- arguments). Examples:
-```fun () -> ... end'''
-```fun some_function/0'''
-```fun some_module:some_function/0'''
- </li>
- <li>A tuple `{test, ModuleName, FunctionName}', where `ModuleName' and
- `FunctionName' are atoms, referring to the function
- `ModuleName:FunctionName/0'</li>
- <li>(Obsolete) A pair of atoms `{ModuleName, FunctionName}', equivalent to
- `{test, ModuleName, FunctionName}' if nothing else matches first. This
- might be removed in a future version.</li>
- <li>A pair `{LineNumber, SimpleTest}', where `LineNumber' is a
- nonnegative integer and `SimpleTest' is another simple test
- object. `LineNumber' should indicate the source line of the test.
- Pairs like this are usually only created via `?_test(...)' macros;
- see {@section Basic macros}.</li>
-</ul>
-In brief, a simple test object consists of a single function that takes
-no arguments (possibly annotated with some additional metadata, i.e., a
-line number). Evaluation of the function either <em>succeeds</em>, by
-returning some value (which is ignored), or <em>fails</em>, by throwing
-an exception.
-
-=== Test sets and deep lists ===
-
-A test set can be easily created by placing a sequence of test objects
-in a list. If `T_1', ..., `T_N' are individual test objects, then `[T_1,
-..., T_N]' is a test set consisting of those objects (in that order).
-
-Test sets can be joined in the same way: if `S_1', ..., `S_K' are test
-sets, then `[S_1, ..., S_K]' is also a test set, where the tests of
-`S_i' are ordered before those of `S_(i+1)', for each subset `S_i'.
-
-Thus, the main representation of test sets is <em>deep lists</em>, and
-a simple test object can be viewed as a test set containing only a
-single test; there is no difference between `T' and `[T]'.
-
-A module can also be used to represent a test set; see `ModuleName'
-under {@section Primitives} below.
-
-=== Titles ===
-
-Any test or test set `T' can be annotated with a title, by wrapping it
-in a pair `{Title, T}', where `Title' is a string. For convenience, any
-test which is normally represented using a tuple can simply be given a
-title string as the first element, i.e., writing `{"The Title", ...}'
-instead of adding an extra tuple wrapper as in `{"The Title", {...}}'.
-
-
-=== Primitives ===
-
-The following are primitives, which do not contain other test sets as
-arguments:
-<dl>
-<dt>`ModuleName::atom()'
-</dt>
-<dd>A single atom represents a module name, and is equivalent to
-`{module, ModuleName}'. This is often used as in the call
-`eunit:test(some_module)'.
-</dd>
-<dt>`{module, ModuleName::atom()}'
-</dt>
-<dd>This composes a test set from the exported test functions of the
-named module, i.e., those functions with arity zero whose names end
-with `_test' or `_test_'. Basically, the `..._test()' functions become
-simple tests, while the `..._test_()' functions become generators.
-
-In addition, EUnit will also look for another module whose name is
-`ModuleName' plus the suffix `_tests', and if it exists, all the tests
-from that module will also be added. (If `ModuleName' already contains
-the suffix `_tests', this is not done.) E.g., the specification
-`{module, mymodule}' will run all tests in the modules `mymodule' and
-`mymodule_tests'. Typically, the `_tests' module should only contain
-test cases that use the public interface of the main module (and no
-other code).
-</dd>
-<dt>`{application, AppName::atom(), Info::list()}'
-</dt>
-<dd>This is a normal Erlang/OTP application descriptor, as found in an
- `.app' file. The resulting test set consists of the modules listed in
- the `modules' entry in `Info'.
-</dd>
-<dt>`{application, AppName::atom()}'
-</dt>
-<dd>This creates a test set from all the modules belonging to the
-specified application, by consulting the application's `.app' file
-(see `{file, FileName}'), or if no such file exists, by testing all
-object files in the application's <code>ebin</code>-directory (see `{dir,
-Path}'); if that does not exist, the `code:lib_dir(AppName)' directory
-is used.
-</dd>
-<dt>`Path::string()'
-</dt>
-<dd>A single string represents the path of a file or directory, and is
-equivalent to `{file, Path}', or `{dir, Path}', respectively, depending
-on what `Path' refers to in the file system.
-</dd>
-<dt>`{file, FileName::string()}'
-</dt>
-<dd>If `FileName' has a suffix that indicates an object file (`.beam'),
-EUnit will try to reload the module from the specified file and test it.
-Otherwise, the file is assumed to be a text file containing test
-specifications, which will be read using the standard library function
-`file:path_consult/2'.
-
-Unless the file name is absolute, the file is first searched for
-relative to the current directory, and then using the normal search path
-(`code:get_path()'). This means that the names of typical "app" files
-can be used directly, without a path, e.g., `"mnesia.app"'.
-</dd>
-<dt>`{dir, Path::string()}'
-</dt>
-<dd>This tests all object files in the specified directory, as if they
-had been individually specified using `{file, FileName}'.
-</dd>
-<dt>`{generator, GenFun::(() -> Tests)}'
-</dt>
-<dd>The generator function `GenFun' is called to produce a test
-set.
-</dd>
-<dt>`{generator, ModuleName::atom(), FunctionName::atom()}'
-</dt>
-<dd>The function `ModuleName:FunctionName()' is called to produce a test
-set.
-</dd>
-<dt>`{with, X::any(), [AbstractTestFun::((any()) -> any())]}'
-</dt>
-<dd>Distributes the value `X' over the unary functions in the list,
-turning them into nullary test functions. An `AbstractTestFun' is like
-an ordinary test fun, but takes one argument instead of zero - it's
-basically missing some information before it can be a proper test. In
-practice, `{with, X, [F_1, ..., F_N]}' is equivalent to `[fun () ->
-F_1(X) end, ..., fun () -> F_N(X) end]'. This is particularly useful if
-your abstract test functions are already implemented as proper
-functions: `{with, FD, [fun filetest_a/1, fun filetest_b/1, fun
-filetest_c/1]}' is equivalent to `[fun () -> filetest_a(FD) end, fun ()
--> filetest_b(FD) end, fun () -> filetest_c(FD) end]', but much more
-compact. See also {@section Fixtures}, below.
-</dd>
-</dl>
-
-=== Control ===
-
-The following representations control how and where tests are executed:
-<dl>
-<dt>`{spawn, Tests}'</dt>
-<dd>Runs the specified tests in a separate subprocess, while the current
-test process waits for it to finish. This is useful for tests that need
-a fresh, isolated process state. (Note that EUnit always starts at least
-one such a subprocess automatically; tests are never executed by the
-caller's own process.)</dd>
-<dt>`{spawn, Node::atom(), Tests}'</dt>
-<dd>Like `{spawn, Tests}', but runs the specified tests on the given
-Erlang node.</dd>
-<dt>`{timeout, Time::number(), Tests}'</dt>
-<dd>Runs the specified tests under the given timeout. Time is in
-seconds; e.g., 60 means one minute and 0.1 means 1/10th of a second. If
-the timeout is exceeded, the unfinished tests will be forced to
-terminate. Note that if a timeout is set around a fixture, it includes
-the time for setup and cleanup, and if the timeout is triggered, the
-entire fixture is abruptly terminated (without running the
-cleanup). The default timeout for an individual test is 5 seconds.</dd>
-<dt>`{inorder, Tests}'</dt>
-<dd>Runs the specified tests in strict order. Also see `{inparallel,
-Tests}'. By default, tests are neither marked as `inorder' or
-`inparallel', but may be executed as the test framework chooses.</dd>
-<dt>`{inparallel, Tests}'</dt>
-<dd>Runs the specified tests in parallel (if possible). Also see
-`{inorder, Tests}'.</dd>
-<dt>`{inparallel, N::integer(), Tests}'</dt>
-<dd>Like `{inparallel, Tests}', but running no more than `N' subtests
-simultaneously.</dd>
-</dl>
-
-=== Fixtures ===
-
-A "fixture" is some state that is necessary for a particular set of
-tests to run. EUnit's support for fixtures makes it easy to set up such
-state locally for a test set, and automatically tear it down again when
-the test set is finished, regardless of the outcome (success, failures,
-timeouts, etc.).
-
-To make the descriptions simpler, we first list some definitions:
-<table border="0" cellspacing="4">
-<tr>
-<td>`Setup'</td><td>`() -> (R::any())'</td>
-</tr>
-<tr>
-<td>`SetupX'</td><td>`(X::any()) -> (R::any())'</td>
-</tr>
-<tr>
-<td>`Cleanup'</td><td>`(R::any()) -> any()'</td>
-</tr>
-<tr>
-<td>`CleanupX'</td><td>`(X::any(), R::any()) -> any()'</td>
-</tr>
-<tr>
-<td>`Instantiator'</td><td>`((R::any()) -> Tests) | {with, [AbstractTestFun::((any()) -> any())]}'</td>
-</tr>
-<tr>
-<td>`Where'</td><td>`local | spawn | {spawn, Node::atom()}'</td>
-</tr>
-</table>
-(these are explained in more detail further below.)
-
-The following representations specify fixture handling for test sets:
-<dl>
-<dt>`{setup, Setup, Tests | Instantiator}'</dt>
-<dt>`{setup, Setup, Cleanup, Tests | Instantiator}'</dt>
-<dt>`{setup, Where, Setup, Tests | Instantiator}'</dt>
-<dt>`{setup, Where, Setup, Cleanup, Tests | Instantiator}'</dt>
-<dd>`setup' sets up a single fixture for running all of the specified
-tests, with optional teardown afterwards. The arguments are described in
-detail below.
-</dd>
-<dt>`{node, Node::atom(), Tests | Instantiator}'</dt>
-<dt>`{node, Node::atom(), Args::[string()] | string(), Tests | Instantiator}'</dt>
-<dd>`node' is like `setup', but with a built-in behaviour: it starts a
-peer node for the duration of the tests. The atom `Node' should have
-the format `nodename@full.machine.name', and `Args' are the optional
-arguments to the new node; see `peer:start_link/1' for details. To remain compatible
-with pre-existing user tests, `Args' accepts both a list of strings and a string
-If a string is passed, it is parsed into a list of arguments, treating
-single- and double-quoted text as single arguments and removing the quotes.
-If you wish a quote character to remain a part of the parsed argument list,
-escape it with a backslash "\". Unbalanced quotes also become a part of the output.
-</dd>
-<dt>`{foreach, Where, Setup, Cleanup, [Tests | Instantiator]}'</dt>
-<dt>`{foreach, Setup, Cleanup, [Tests | Instantiator]}'</dt>
-<dt>`{foreach, Where, Setup, [Tests | Instantiator]}'</dt>
-<dt>`{foreach, Setup, [Tests | Instantiator]}'</dt>
-<dd>`foreach' is used to set up a fixture and optionally tear it down
-afterwards, repeated for each single one of the specified test sets.
-</dd>
-<dt>`{foreachx, Where, SetupX, CleanupX,
- Pairs::[{X::any(), ((X::any(), R::any()) -> Tests)}]}'</dt>
-<dt>`{foreachx, SetupX, CleanupX, Pairs}'</dt>
-<dt>`{foreachx, Where, SetupX, Pairs}'</dt>
-<dt>`{foreachx, SetupX, Pairs}'</dt>
-<dd>`foreachx' is like `foreach', but uses a list of pairs, each
-containing an extra argument `X' and an extended instantiator function.
-</dd>
-</dl>
-
-A `Setup' function is executed just before any of the specified tests
-are run, and a `Cleanup' function is executed when no more of the
-specified tests will be run, regardless of the reason. A `Setup'
-function takes no argument, and returns some value which will be passed
-as it is to the `Cleanup' function. A `Cleanup' function should do
-whatever necessary and return some arbitrary value, such as the atom
-`ok'. (`SetupX' and `CleanupX' functions are similar, but receive one
-additional argument: some value `X', which depends on the context.) When
-no `Cleanup' function is specified, a dummy function is used which has
-no effect.
-
-An `Instantiator' function receives the same value as the `Cleanup'
-function, i.e., the value returned by the `Setup' function. It should
-then behave much like a generator (see {@section Primitives}), and
-return a test set whose tests have been <em>instantiated</em> with the
-given value. A special case is the syntax `{with, [AbstractTestFun]}'
-which represents an instantiator function that distributes the value
-over a list of unary functions; see {@section Primitives}: `{with, X,
-[...]}' for more details.
-
-A `Where' term controls how the specified tests are executed. The
-default is `spawn', which means that the current process handles the
-setup and teardown, while the tests are executed in a subprocess.
-`{spawn, Node}' is like `spawn', but runs the subprocess on the
-specified node. `local' means that the current process will handle both
-setup/teardown and running the tests - the drawback is that if a test
-times out so that the process is killed, the <em>cleanup will not be
-performed</em>; hence, avoid this for persistent fixtures such as file
-operations. In general, `local' should only be used when:
-<ul>
- <li>the setup/teardown needs to be executed by the process that will
- run the tests;</li>
- <li>no further teardown needs to be done if the process is killed
- (i.e., no state outside the process was affected by the setup)</li>
-</ul>
-
-=== Lazy generators ===
-
-Sometimes, it can be convenient not to produce the whole set of test
-descriptions before the testing begins; for example, if you want to
-generate a huge amount of tests that would take up too much space to
-keep in memory all at once.
-
-It is fairly easy to write a generator which, each time it is called,
-either produces an empty list if it is done, or otherwise produces a
-list containing a single test case plus a new generator which will
-produce the rest of the tests. This demonstrates the basic pattern:
-
-```lazy_test_() ->
- lazy_gen(10000).
-
- lazy_gen(N) ->
- {generator,
- fun () ->
- if N > 0 ->
- [?_test(...)
- | lazy_gen(N-1)];
- true ->
- []
- end
- end}.'''
-
-When EUnit traverses the test representation in order to run the tests,
-the new generator will not be called to produce the next test until the
-previous test has been executed.
-
-Note that it is easiest to write this kind of recursive generator using
-a help function, like the `lazy_gen/1' function above. It can also be
-written using a recursive fun, if you prefer to not clutter your
-function namespace and are comfortable with writing that kind of code.
diff --git a/lib/eunit/src/eunit.erl b/lib/eunit/src/eunit.erl
index 0f20243e28..fa19a34c76 100644
--- a/lib/eunit/src/eunit.erl
+++ b/lib/eunit/src/eunit.erl
@@ -28,12 +28,6 @@
%% either the Apache License or the LGPL.
%%
%% %CopyrightEnd%
-%%
-%% @author Mickaël Rémond <mickael.remond@process-one.net>
-%% [http://www.process-one.net/]
-%% @author Richard Carlsson <carlsson.richard@gmail.com>
-%% @version {@version}, {@date} {@time}
-%% @doc This module is the main EUnit user interface.
-module(eunit).
-moduledoc "This module is the main EUnit user interface.".
@@ -54,8 +48,6 @@
%% TODO: Command line interface similar to that of edoc?
-%% @doc Starts the EUnit server. Normally, you don't need to call this
-%% function; it is started automatically.
-doc """
start()
@@ -66,14 +58,10 @@ started automatically.
start() ->
start(?SERVER).
-%% @private
-%% @doc See {@link start/0}.
-doc false.
start(Server) ->
eunit_server:start(Server).
-%% @doc Stops the EUnit server. Normally, you don't need to call this
-%% function.
-doc """
Stops the EUnit server. Normally, you don't need to call this function.
""".
@@ -81,68 +69,54 @@ Stops the EUnit server. Normally, you don't need to call this function.
stop() ->
stop(?SERVER).
-%% @private
-%% @doc See {@link stop/0}.
-doc false.
stop(Server) ->
eunit_server:stop(Server).
-%% @private
-doc false.
watch(Target) ->
watch(Target, []).
-%% @private
-doc false.
watch(Target, Options) ->
watch(?SERVER, Target, Options).
-%% @private
-doc false.
watch(Server, Target, Options) ->
eunit_server:watch(Server, Target, Options).
-%% @private
-doc false.
watch_path(Target) ->
watch_path(Target, []).
-%% @private
-doc false.
watch_path(Target, Options) ->
watch_path(?SERVER, Target, Options).
-%% @private
-doc false.
watch_path(Server, Target, Options) ->
eunit_server:watch_path(Server, Target, Options).
-%% @private
-doc false.
watch_regexp(Target) ->
watch_regexp(Target, []).
-%% @private
-doc false.
watch_regexp(Target, Options) ->
watch_regexp(?SERVER, Target, Options).
-%% @private
-doc false.
watch_regexp(Server, Target, Options) ->
eunit_server:watch_regexp(Server, Target, Options).
-%% @private
-doc false.
watch_app(Name) ->
watch_app(Name, []).
-%% @private
-doc false.
watch_app(Name, Options) ->
watch_app(?SERVER, Name, Options).
-%% @private
-doc false.
watch_app(Server, Name, Options) ->
case code:lib_dir(Name) of
@@ -157,36 +131,6 @@ watch_app(Server, Name, Options) ->
test(Tests) ->
test(Tests, []).
-%% @spec test(Tests::term(), Options::[term()]) -> ok | {error, term()}
-%% @doc Runs a set of tests. The format of `Tests' is described in the
-%% section <a
-%% href="overview-summary.html#EUnit_test_representation">EUnit test
-%% representation</a> of the overview.
-%%
-%% Example: ```eunit:test(fred)''' runs all tests in the module `fred'
-%% and also any tests in the module `fred_tests', if that module exists.
-%%
-%% Options:
-%% <dl>
-%% <dt>`verbose'</dt>
-%% <dd>Displays more details about the running tests.</dd>
-%% <dt>`print_depth'</dt>
-%% <dd>Maximum depth to which terms are printed in case of error.</dd>
-%% <dt>`exact_execution'</dt>
-%% <dd>If this boolean flag is set to `true' framework will
-%% not automatically execute tests found in related module suffixed with "_tests".
-%% This behaviour might be unwanted if execution of modules found in a folder
-%% is ordered while it contains both source and test modules.</dd>
-%% <dt>`scale_timeouts'</dt>
-%% <dd>If this numeric value is set, timeouts will get scaled accordingly.
-%% It may be useful when running a set of tests on a slower host.
-%% Examples: `{scale_timeouts,10}' make the timeouts 10 times longer, while
-%% `{scale_timeouts,0.1}' would shorten them by a factor of 10.</dd>
-%% </dl>
-%%
-%% Options in the environment variable EUNIT are also included last in
-%% the option list, i.e., have lower precedence than those in `Options'.
-%% @see test/1
-doc """
Runs a set of tests. The format of `Tests` is described in the section
[EUnit test representation](chapter.md#EUnit_test_representation) of the
@@ -226,8 +170,6 @@ _See also: _`test/1`.
test(Tests, Options) ->
test(?SERVER, Tests, all_options(Options)).
-%% @private
-%% @doc See {@link test/2}.
-doc false.
test(Server, Tests, Options) ->
Listeners = listeners(Options),
@@ -271,17 +213,14 @@ wait_until_listeners_have_terminated([]) ->
%% TODO: maybe some functions could check for a globally registered server?
%% TODO: some synchronous but completely quiet interface function
-%% @private
-doc false.
submit(T) ->
submit(T, []).
-%% @private
-doc false.
submit(T, Options) ->
submit(?SERVER, T, Options).
-%% @private
-doc false.
submit(Server, T, Options) ->
Dummy = spawn(fun devnull/0),
diff --git a/lib/eunit/src/eunit_autoexport.erl b/lib/eunit/src/eunit_autoexport.erl
index 2f54cec5be..cfcceb07d4 100644
--- a/lib/eunit/src/eunit_autoexport.erl
+++ b/lib/eunit/src/eunit_autoexport.erl
@@ -29,10 +29,7 @@
%%
%% %CopyrightEnd%
%%
-%% @author Richard Carlsson <carlsson.richard@gmail.com>
-%% @private
-%% @see eunit
-%% @doc Parse transform for automatic exporting of test functions.
+%% Parse transform for automatic exporting of test functions.
-module(eunit_autoexport).
-moduledoc false.
diff --git a/lib/eunit/src/eunit_data.erl b/lib/eunit/src/eunit_data.erl
index 72be36166f..2bb842082e 100644
--- a/lib/eunit/src/eunit_data.erl
+++ b/lib/eunit/src/eunit_data.erl
@@ -29,11 +29,7 @@
%%
%% %CopyrightEnd%
%%
-%% @author Richard Carlsson <carlsson.richard@gmail.com>
-%% @copyright 2006 Richard Carlsson
-%% @private
-%% @see eunit
-%% @doc Interpretation of symbolic test representation
+%% Interpretation of symbolic test representation
-module(eunit_data).
-moduledoc false.
@@ -47,73 +43,83 @@
enter_context/3, get_module_tests/2]).
-export([parse_command_line/2]). % for unit testing
+-export_type([tests/0, simple_test/0, testfunction/0,
+ abstract_testfunction/0, instantiator/0, setup_fun/0,
+ cleanup_fun/0, setup_x_fun/0, cleanup_x_fun/0,
+ abstract_instantiator/0, proc/0, module_name/0,
+ function_name/0, app_name/0, filename/0, test_iterator/0]).
+
-define(TICKS_PER_SECOND, 1000).
-%% @type tests() =
-%% SimpleTest
-%% | [tests()]
-%% | moduleName()
-%% | {module, moduleName()}
-%% | {application, appName()}
-%% | {application, appName(), [term()]}
-%% | fileName()
-%% | {file, fileName()}
-%% | {string(), tests()}
-%% | {generator, () -> tests()}
-%% | {generator, M::moduleName(), F::functionName()}
-%% | {spawn, tests()}
-%% | {spawn, Node::atom(), tests()}
-%% | {timeout, T::number(), tests()}
-%% | {inorder, tests()}
-%% | {inparallel, tests()}
-%% | {inparallel, N::integer(), tests()}
-%% | {with, X::any(), [AbstractTestFunction]}
-%% | {setup, Where::local | spawn | {spawn, Node::atom()},
-%% Setup::() -> (R::any()),
-%% Cleanup::(R::any()) -> any(),
-%% tests() | Instantiator
-%% }
-%% | {setup, Setup, Cleanup, tests() | Instantiator}
-%% | {setup, Where, Setup, tests() | Instantiator}
-%% | {setup, Setup, tests() | Instantiator}
-%% | {foreach, Where::local | spawn | {spawn, Node::atom()},
-%% Setup::() -> (R::any()),
-%% Cleanup::(R::any()) -> any(),
-%% [tests() | Instantiator]
-%% }
-%% | {foreach, Setup, Cleanup, [tests() | Instantiator]}
-%% | {foreach, Where, Setup, [tests() | Instantiator]}
-%% | {foreach, Setup, [tests() | Instantiator]}
-%% | {foreachx, Where::local | spawn | {spawn, Node::atom()},
-%% SetupX::(X::any()) -> (R::any()),
-%% CleanupX::(X::any(), R::any()) -> any(),
-%% Pairs::[{X::any(),
-%% (X::any(), R::any()) -> tests()}]
-%% }
-%% | {foreachx, SetupX, CleanupX, Pairs}
-%% | {foreachx, Where, SetupX, Pairs}
-%% | {foreachx, SetupX, Pairs}
-%% | {node, Node::atom(), tests() | Instantiator}
-%% | {node, Node, Args::string(), tests() | Instantiator}
-%%
-%% SimpleTest = TestFunction | {Line::integer(), SimpleTest}
-%%
-%% TestFunction = () -> any()
-%% | {test, M::moduleName(), F::functionName()}
-%% | {M::moduleName(), F::functionName()}.
-%%
-%% AbstractTestFunction = (X::any()) -> any()
-%%
-%% Instantiator = (R::any()) -> tests()
-%% | {with, [AbstractTestFunction]}
-%%
+-type tests() ::
+ simple_test()
+ | [tests()]
+ | module_name()
+ | {module, module_name()}
+ | {application, app_name()}
+ | {application, app_name(), [term()]}
+ | filename()
+ | {file, filename()}
+ | {string(), tests()}
+ | {generator, fun (() -> tests())}
+ | {generator, M::module_name(), F::function_name()}
+ | {spawn, tests()}
+ | {spawn, Node::atom(), tests()}
+ | {timeout, Time::number(), tests()}
+ | {inorder, tests()}
+ | {inparallel, tests()}
+ | {inparallel, N::integer(), tests()}
+ | {with, X::any(), [abstract_testfunction()]}
+ | {setup, proc(),
+ setup_fun(),
+ cleanup_fun(),
+ tests() | instantiator()
+ }
+ | {setup, setup_fun(), cleanup_fun(), tests() | instantiator()}
+ | {setup, proc(), setup_fun(), tests() | instantiator()}
+ | {setup, setup_fun(), tests() | instantiator()}
+ | {foreach, proc(),
+ setup_fun(),
+ cleanup_fun(),
+ [tests() | instantiator()]
+ }
+ | {foreach, setup_fun(), cleanup_fun(), [tests() | instantiator()]}
+ | {foreach, proc(), setup_fun(), [tests() | instantiator()]}
+ | {foreach, setup_fun(), [tests() | instantiator()]}
+ | {foreachx, proc(),
+ setup_x_fun(),
+ cleanup_x_fun(),
+ Pairs::[{X::any(), abstract_instantiator()}]
+ }
+ | {foreachx, setup_x_fun(), cleanup_x_fun(),
+ Pairs::[{X::any(), abstract_instantiator()}]}
+ | {foreachx, proc(), setup_x_fun(),
+ Pairs::[{X::any(), abstract_instantiator()}]}
+ | {foreachx, setup_x_fun(),
+ Pairs::[{X::any(), abstract_instantiator()}]}
+ | {node, Node::atom(), tests() | instantiator()}
+ | {node, Node::atom(), Args::string(), tests() | instantiator()}.
+-type simple_test() :: testfunction() | {Line::integer(), simple_test()}.
+-type testfunction() :: fun (() -> any())
+ | {test, M::module_name(), F::function_name()}
+ | {M::module_name(), F::function_name()}.
+-type abstract_testfunction() :: fun ((X::any()) -> any()).
+-type instantiator() :: fun ((R::any()) -> tests())
+ | {with, [abstract_testfunction()]}.
+-type setup_fun() :: fun (() -> (SetupInfo::any())).
+-type cleanup_fun() :: fun ((SetupInfo::any()) -> any()).
+-type setup_x_fun() :: fun ((X::any()) -> SetupInfo::any()).
+-type cleanup_x_fun() :: fun ((X::any(), SetupInfo::any()) -> any()).
+-type abstract_instantiator() :: fun ((X::any(), SetupInfo::any()) -> tests()).
+-type proc() :: local | spawn | {spawn, Node::atom()}.
+
%% Note that `{string(), ...}' is a short-hand for `{string(), {...}}'
%% if the tuple contains more than two elements.
-%%
-%% @type moduleName() = atom()
-%% @type functionName() = atom()
-%% @type appName() = atom()
-%% @type fileName() = string()
+
+-type module_name() :: atom().
+-type function_name() :: atom().
+-type app_name() :: atom().
+-type filename() :: string().
%% TODO: Can we mark up tests as known-failures?
%% TODO: Is it possible to handle known timeout/setup failures?
@@ -130,18 +136,21 @@
pos = 0,
parent = []}).
-%% @spec (tests(), [integer()]) -> testIterator()
-%% @type testIterator()
+-opaque test_iterator() :: #iter{}.
+
+-type opts() :: [any()].
+
+-spec iter_init(tests(), [integer()], opts()) -> test_iterator().
iter_init(Tests, ParentID, Options) ->
#iter{tests = Tests, parent = lists:reverse(ParentID), options = Options}.
-%% @spec (testIterator()) -> [integer()]
+-spec iter_id(test_iterator()) -> [integer()].
iter_id(#iter{pos = N, parent = Ns}) ->
lists:reverse(Ns, [N]).
-%% @spec (testIterator()) -> none | {testItem(), testIterator()}
+-spec iter_next(test_iterator()) -> none | {test_item(), test_iterator()}.
iter_next(I = #iter{next = [], options = Options}) ->
case next(I#iter.tests, Options) of
@@ -157,7 +166,7 @@ iter_next(I = #iter{next = [T | Ts]}) ->
prev = [T | I#iter.prev],
pos = I#iter.pos + 1}}.
-%% @spec (testIterator()) -> none | {testItem(), testIterator()}
+-spec iter_prev(test_iterator()) -> none | {test_item(), test_iterator()}.
iter_prev(#iter{prev = []}) ->
none;
@@ -170,16 +179,18 @@ iter_prev(#iter{prev = [T | Ts]} = I) ->
%% ---------------------------------------------------------------------
%% Concrete test set representation iterator
-%% @spec (tests()) -> none | {testItem(), tests()}
-%% @type testItem() = #test{} | #group{}
-%% @throws {bad_test, term()}
+-type test_item() :: #test{} | #group{}.
+
+-spec next(tests(), opts()) -> none | {test_item(), tests()}.
+
+%% Throws {bad_test, term()}
%% | {generator_failed, {{M::atom(),F::atom(),A::integer()},
%% exception()}}
%% | {no_such_function, mfa()}
-%% | {module_not_found, moduleName()}
-%% | {application_not_found, appName()}
+%% | {module_not_found, module_name()}
+%% | {application_not_found, app_name()}
%% | {file_read_error, {Reason::atom(), Message::string(),
-%% fileName()}}
+%% filename()}}
next(Tests, Options) ->
case eunit_lib:dlist_next(Tests) of
@@ -636,7 +647,7 @@ push_order(_, _, G) ->
%% ---------------------------------------------------------------------
%% Extracting test funs from a module
-%% @throws {module_not_found, moduleName()}
+%% Throws {module_not_found, module_name()}
get_module_tests(Module, Options) ->
try Module:module_info(exports) of
@@ -699,8 +710,7 @@ extract_testfuns(Exports, Module, TestSuffix, GeneratorSuffix) ->
%% ---------------------------------------------------------------------
%% Getting a test set from a file (text file or object file)
-%% @throws {file_read_error, {Reason::atom(), Message::string(),
-%% fileName()}}
+%% Throws {file_read_error, {Reason::atom(), Message::string(), filename()}}
get_file_tests(F) ->
case is_module_filename(F) of
@@ -753,8 +763,7 @@ objfile_module(File) ->
%% ---------------------------------------------------------------------
%% Getting a set of module tests from the object files in a directory
-%% @throws {file_read_error,
-%% {Reason::atom(), Message::string(), fileName()}}
+%% Throws {file_read_error, {Reason::atom(), Message::string(), filename()}}
get_directory_module_tests(D) ->
Ms = get_directory_modules(D),
@@ -786,11 +795,13 @@ get_directory_modules(D) ->
%% ---------------------------------------------------------------------
%% Entering a setup-context, with guaranteed cleanup.
-%% @spec (Tests::#context{}, Instantiate, Callback) -> any()
-%% Instantiate = (any()) -> tests()
-%% Callback = (tests()) -> any()
-%% @throws {context_error, Error, eunit_lib:exception()}
-%% Error = setup_failed | instantiation_failed | cleanup_failed
+-spec enter_context(Tests::#context{}, Instantiate, Callback) -> any()
+ when
+ Instantiate :: fun ((any()) -> tests()),
+ Callback :: fun ((tests()) -> any()).
+
+%% Throws {context_error, Error, eunit_lib:exception()}
+%% where Error = setup_failed | instantiation_failed | cleanup_failed
enter_context(#context{setup = S, cleanup = C, process = P}, I, F) ->
F1 = case P of
diff --git a/lib/eunit/src/eunit_lib.erl b/lib/eunit/src/eunit_lib.erl
index 25c31c522f..b580415b98 100644
--- a/lib/eunit/src/eunit_lib.erl
+++ b/lib/eunit/src/eunit_lib.erl
@@ -29,12 +29,7 @@
%%
%% %CopyrightEnd%
%%
-%% @author Mickaël Rémond <mickael.remond@process-one.net>
-%% [http://www.process-one.net/]
-%% @author Richard Carlsson <carlsson.richard@gmail.com>
-%% @private
-%% @see eunit
-%% @doc Utility functions for eunit
+%% Utility functions for eunit
-module(eunit_lib).
-moduledoc false.
@@ -49,20 +44,19 @@
format_exception/1, format_exception/2, format_error/1, format_error/2,
format_stacktrace/1, is_not_test/1]).
+-export_type([exception/0, exception_class/0, stack_trace/0, module_name/0,
+ function_name/0, arg_list/0]).
+
-define(DEFAULT_DEPTH, 20).
%% Type definitions for describing exceptions
-%%
-%% @type exception() = {exceptionClass(), Reason::term(), stackTrace()}
-%%
-%% @type exceptionClass() = error | exit | throw
-%%
-%% @type stackTrace() = [{moduleName(), functionName(), arity() | argList()}]
-%%
-%% @type moduleName() = atom()
-%% @type functionName() = atom()
-%% @type argList() = [term()]
-%% @type fileName() = string()
+
+-type exception() :: {exception_class(), Reason::term(), stack_trace()}.
+-type exception_class() :: error | exit | throw.
+-type stack_trace() :: [{module_name(), function_name(), arity() | arg_list()}].
+-type module_name() :: atom().
+-type function_name() :: atom().
+-type arg_list() :: [term()].
%% ---------------------------------------------------------------------
@@ -501,8 +495,8 @@ win32_cmd_tests() ->
%% ---------------------------------------------------------------------
%% Wrapper around file:path_consult
-%% @throws {file_read_error, {Reason::atom(), Message::string(),
-%% fileName()}}
+%% Throws {file_read_error, {Reason::atom(), Message::string(),
+%% filename()}}
consult_file(File) ->
case file:path_consult(["."]++code:get_path(), File) of
@@ -516,8 +510,7 @@ consult_file(File) ->
%% ---------------------------------------------------------------------
%% Wrapper around file:list_dir
-%% @throws {file_read_error, {Reason::atom(), Message::string(),
-%% fileName()}}
+%% Throws {file_read_error, {Reason::atom(), Message::string(), filename()}}
list_dir(Dir) ->
case file:list_dir(Dir) of
diff --git a/lib/eunit/src/eunit_listener.erl b/lib/eunit/src/eunit_listener.erl
index 522a6e26d0..4920e918f6 100644
--- a/lib/eunit/src/eunit_listener.erl
+++ b/lib/eunit/src/eunit_listener.erl
@@ -29,10 +29,7 @@
%%
%% %CopyrightEnd%
%%
-%% @copyright 2009 Richard Carlsson
-%% @private
-%% @see eunit
-%% @doc Generic listener process for eunit.
+%% Generic listener process for eunit.
-module(eunit_listener).
-moduledoc false.
diff --git a/lib/eunit/src/eunit_proc.erl b/lib/eunit/src/eunit_proc.erl
index 7ec4d23d42..f3371fe2a7 100644
--- a/lib/eunit/src/eunit_proc.erl
+++ b/lib/eunit/src/eunit_proc.erl
@@ -29,10 +29,7 @@
%%
%% %CopyrightEnd%
%%
-%% @author Richard Carlsson <carlsson.richard@gmail.com>
-%% @private
-%% @see eunit
-%% @doc Test runner process tree functions
+%% Test runner process tree functions
-module(eunit_proc).
-moduledoc false.
@@ -45,6 +42,8 @@
%% This must be exported; see new_group_leader/1 for details.
-export([group_leader_process/1]).
+-export_type([abort_exception/0]).
+
-record(procstate, {ref, id, super, insulator, parent, order, options}).
%% Spawns test process and returns the process Pid; sends {done,
@@ -127,7 +126,7 @@ message_super(Id, Info, St) ->
St#procstate.super ! {status, Id, Info}.
-%% @TODO implement synchronized mode for insulator/child execution
+%% TODO implement synchronized mode for insulator/child execution
%% Ideas for synchronized mode:
%%
@@ -167,8 +166,8 @@ message_super(Id, Info, St) ->
%% which contains the process id:s of the parent, the insulator, and the
%% supervisor.
-%% @spec (Type, (#procstate{}) -> () -> term(), #procstate{}) -> pid()
-%% Type = local | {remote, Node::atom()}
+-spec start_task(Type, fun ((#procstate{}) -> fun (() -> any())), #procstate{}) -> pid()
+ when Type :: local | {remote, Node::atom()}.
start_task(Type, Fun, St0) ->
St = St0#procstate{parent = self()},
@@ -218,8 +217,8 @@ start_task(Type, Fun, St0) ->
%% insulators must always immediately send an {ok, Reference, self()}
%% message to the parent as soon as it is spawned.
-%% @spec (Type, Fun::() -> term(), St::#procstate{}) -> ok
-%% Type = local | {remote, Node::atom()}
+-spec insulator_process(Type, Fun::fun ((#procstate{}) -> fun (() -> any())), St::#procstate{}) -> no_return()
+ when Type :: local | {remote, Node::atom()}.
insulator_process(Type, Fun, St0) ->
process_flag(trap_exit, true),
@@ -255,6 +254,8 @@ insulator_process(Type, Fun, St0) ->
%% currently active test or group, and is sent along with the 'end'
%% progress message when the test or group has finished.
+-spec insulator_wait(Child::pid(), Parent::pid(), Buf::list(), #procstate{}) -> no_return().
+
insulator_wait(Child, Parent, Buf, St) ->
receive
{child, Child, Id, {'begin', Type, Data}} ->
@@ -305,7 +306,7 @@ insulator_wait(Child, Parent, Buf, St) ->
kill_task(Child, St)
end.
--spec kill_task(_, _) -> no_return().
+-spec kill_task(pid(), #procstate{}) -> no_return().
kill_task(Child, St) ->
exit(Child, kill),
@@ -314,6 +315,8 @@ kill_task(Child, St) ->
%% Unlinking before exit avoids polluting the parent process with exit
%% signals from the insulator. The child process is already dead here.
+-spec terminate_insulator(#procstate{}) -> no_return().
+
terminate_insulator(St) ->
%% messaging/unlinking is ok even if the parent is already dead
Parent = St#procstate.parent,
@@ -390,7 +393,7 @@ with_timeout(Time, F, St) when is_integer(Time) ->
%% the test code is allowed to enable signal trapping as it pleases.
%% Note that I/O is redirected to the insulator process.
-%% @spec (() -> term(), #procstate{}) -> ok
+-spec child_process(fun (() -> any()), #procstate{}) -> ok.
child_process(Fun, St) ->
group_leader(St#procstate.insulator, self()),
@@ -412,8 +415,9 @@ child_test_() ->
?_assertMatch(false, process_flag(trap_exit, false))}].
-endif.
-%% @throws abortException()
-%% @type abortException() = {eunit_abort, Cause::term()}
+-type abort_exception() :: {eunit_abort, Cause::any()}.
+
+%% Throws abort_exception()
abort_task(Cause) ->
throw({eunit_abort, Cause}).
@@ -547,8 +551,8 @@ handle_test(T, St) ->
message_insulator({'end', Status, Time}, St),
ok.
-%% @spec (#test{}) -> ok | {error, eunit_lib:exception()}
-%% | {skipped, eunit_test:wrapperError()}
+-spec run_test(#test{}) -> ok | {error, eunit_lib:exception()}
+ | {skipped, eunit_test:wrapper_error()}.
run_test(#test{f = F}) ->
try eunit_test:run_testfun(F) of
diff --git a/lib/eunit/src/eunit_serial.erl b/lib/eunit/src/eunit_serial.erl
index b592e66c99..0d56e45328 100644
--- a/lib/eunit/src/eunit_serial.erl
+++ b/lib/eunit/src/eunit_serial.erl
@@ -29,10 +29,7 @@
%%
%% %CopyrightEnd%
%%
-%% @author Richard Carlsson <carlsson.richard@gmail.com>
-%% @private
-%% @see eunit
-%% @doc Event serializing and multiplexing process, to be used as the
+%% Event serializing and multiplexing process, to be used as the
%% main "supervisor" process for en EUnit test runner. See eunit_proc
%% for details about the events that will be sent to the listeners
%% (provided to this process at startup). This process guarantees that
diff --git a/lib/eunit/src/eunit_server.erl b/lib/eunit/src/eunit_server.erl
index 4251afa1ec..4893c29236 100644
--- a/lib/eunit/src/eunit_server.erl
+++ b/lib/eunit/src/eunit_server.erl
@@ -29,10 +29,7 @@
%%
%% %CopyrightEnd%
%%
-%% @author Richard Carlsson <carlsson.richard@gmail.com>
-%% @private
-%% @see eunit
-%% @doc EUnit server process
+%% EUnit server process
-module(eunit_server).
-moduledoc false.
@@ -173,7 +170,7 @@ server(St) ->
server_check_exit(St),
?MODULE:main(St).
-%% @private
+-doc false.
main(St) ->
receive
{done, auto_test, _Pid} ->
diff --git a/lib/eunit/src/eunit_striptests.erl b/lib/eunit/src/eunit_striptests.erl
index c6cdbd35aa..8ab30c739f 100644
--- a/lib/eunit/src/eunit_striptests.erl
+++ b/lib/eunit/src/eunit_striptests.erl
@@ -29,11 +29,7 @@
%%
%% %CopyrightEnd%
%%
-%% @author Richard Carlsson <carlsson.richard@gmail.com>
-%% @author Eric Merritt <ericbmerritt@gmail.com>
-%% @private
-%% @see eunit
-%% @doc Parse transform for stripping EUnit test functions.
+%% Parse transform for stripping EUnit test functions.
-module(eunit_striptests).
-moduledoc false.
diff --git a/lib/eunit/src/eunit_surefire.erl b/lib/eunit/src/eunit_surefire.erl
index 4dcb5850c3..486e854e0e 100644
--- a/lib/eunit/src/eunit_surefire.erl
+++ b/lib/eunit/src/eunit_surefire.erl
@@ -28,16 +28,6 @@
%% either the Apache License or the LGPL.
%%
%% %CopyrightEnd%
-%%
-%% @author Mickaël Rémond <mickael.remond@process-one.net>
-%% @see eunit
-%% @doc Surefire reports for EUnit (Format used by Maven and Atlassian
-%% Bamboo for example to integrate test results). Based on initial code
-%% from Paul Guyot.
-%%
-%% Example: Generate XML result file in the current directory:
-%% ```eunit:test([fib, eunit_examples],
-%% [{report,{eunit_surefire,[{dir,"."}]}}]).'''
-module(eunit_surefire).
-moduledoc """
diff --git a/lib/eunit/src/eunit_test.erl b/lib/eunit/src/eunit_test.erl
index 1b745859b2..a0bcfe140a 100644
--- a/lib/eunit/src/eunit_test.erl
+++ b/lib/eunit/src/eunit_test.erl
@@ -29,16 +29,15 @@
%%
%% %CopyrightEnd%
%%
-%% @author Richard Carlsson <carlsson.richard@gmail.com>
-%% @private
-%% @see eunit
-%% @doc Test running functionality
+%% Test running functionality
-module(eunit_test).
-moduledoc false.
-export([run_testfun/1, mf_wrapper/2, enter_context/4, multi_setup/1]).
+-export_type([wrapper_error/0]).
+
-compile(nowarn_unexported_function).
-include("eunit.hrl").
@@ -75,8 +74,9 @@ prune_trace([], Tail) ->
%% ---------------------------------------------------------------------
%% Test runner
-%% @spec ((any()) -> any()) -> {ok, Value} | {error, eunit_lib:exception()}
-%% @throws wrapperError()
+-spec run_testfun(fun (() -> any())) -> {ok, Value :: any()} | {error, eunit_lib:exception()}.
+
+%% Throws wrapper_error()
run_testfun(F) ->
try
@@ -275,10 +275,11 @@ macro_test_() ->
%% Note that the wrapper fun is usually called by run_testfun/1, and the
%% special exceptions thrown here are expected to be handled there.
%%
-%% @throws {eunit_internal, wrapperError()}
+%% Throws {eunit_internal, wrapper_error()}
%%
-%% @type wrapperError() = {no_such_function, mfa()}
-%% | {module_not_found, moduleName()}
+
+-type wrapper_error() :: {no_such_function, mfa()}
+ | {module_not_found, module()}.
mf_wrapper(M, F) ->
fun () ->
@@ -329,13 +330,15 @@ wrapper_test_exported_() ->
%% ---------------------------------------------------------------------
%% Entering a setup-context, with guaranteed cleanup.
-%% @spec (Setup, Cleanup, Instantiate, Callback) -> any()
-%% Setup = () -> any()
-%% Cleanup = (any()) -> any()
-%% Instantiate = (any()) -> tests()
-%% Callback = (tests()) -> any()
-%% @throws {context_error, Error, eunit_lib:exception()}
-%% Error = setup_failed | instantiation_failed | cleanup_failed
+-spec enter_context(Setup, Cleanup, Instantiate, Callback) -> any()
+ when
+ Setup :: fun (() -> any()),
+ Cleanup :: fun ((any()) -> any()),
+ Instantiate :: fun ((any()) -> eunit_data:tests()),
+ Callback :: fun ((eunit_data:tests()) -> any()).
+
+%% Throws {context_error, Error, eunit_lib:exception()}
+%% where Error = setup_failed | instantiation_failed | cleanup_failed
enter_context(Setup, Cleanup, Instantiate, Callback) ->
try Setup() of
diff --git a/lib/eunit/src/eunit_tests.erl b/lib/eunit/src/eunit_tests.erl
index e79b3b02f6..dc079b1453 100644
--- a/lib/eunit/src/eunit_tests.erl
+++ b/lib/eunit/src/eunit_tests.erl
@@ -29,10 +29,7 @@
%%
%% %CopyrightEnd%
%%
-%% @author Richard Carlsson <carlsson.richard@gmail.com>
-%% @private
-%% @see eunit
-%% @doc External tests for eunit.erl
+%% External tests for eunit.erl
-module(eunit_tests).
-moduledoc false.
diff --git a/lib/eunit/src/eunit_tty.erl b/lib/eunit/src/eunit_tty.erl
index 1ba726e1d4..7bdef5cd41 100644
--- a/lib/eunit/src/eunit_tty.erl
+++ b/lib/eunit/src/eunit_tty.erl
@@ -29,10 +29,7 @@
%%
%% %CopyrightEnd%
%%
-%% @author Richard Carlsson <carlsson.richard@gmail.com>
-%% @private
-%% @see eunit
-%% @doc Text-based frontend for EUnit
+%% Text-based frontend for EUnit
-module(eunit_tty).
-moduledoc false.
--
2.51.0
