← Back to branch summary

~statik/ubuntu/maverick/erlang/erlang-merge-testing

« back to all changes in this revision

Viewing changes to lib/eunit/doc/overview.edoc

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-05-01 10:14:38 UTC
  • mfrom: (3.1.4 sid)
  • Revision ID: james.westby@ubuntu.com-20090501101438-6qlr6rsdxgyzrg2z
Tags: 1:13.b-dfsg-2
* Cleaned up patches: removed unneeded patch which helped to support
  different SCTP library versions, made sure that changes for m68k
  architecture applied only when building on this architecture.
* Removed duplicated information from binary packages descriptions.
* Don't require libsctp-dev build-dependency on solaris-i386 architecture
  which allows to build Erlang on Nexenta (thanks to Tim Spriggs for
  the suggestion).

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/eunit/doc/overview.edoc
16
16
and flexible, is easy to use, and has small syntactical overhead.
17
17
 
18
18
<ul>
19
 
<li>{@section Unit Testing}</li>
 
19
<li>{@section Unit testing}</li>
20
20
<li>{@section Terminology}</li>
21
21
<li>{@section Getting started}</li>
22
22
<li>{@section EUnit macros}</li>
36
36
the exported functions of a module can always be placed in a completely
37
37
separate module, avoiding any conflicts entirely.
38
38
 
39
 
== Unit Testing ==
 
39
== Unit testing ==
40
40
 
41
41
Unit Testing is testing of individual program "units" in relative
42
42
isolation. There is no particular size requirement: a unit can be a
234
234
 
235
235
If you want to use Boolean operators for your tests, the `assert'
236
236
macro comes in handy (see {@section EUnit macros} for details):
237
 
```length_test() -> ?assert(length([1,2,3]) == 3).'''
 
237
```length_test() -> ?assert(length([1,2,3]) =:= 3).'''
238
238
The `?assert(Expression)' macro will evaluate `Expression', and if that
239
239
does not evaluate to `true', it will throw an exception; otherwise it
240
240
just returns `ok'. In the above example, the test will thus fail if the
276
276
errors occur. To bypass EUnit and print text directly to the console
277
277
while testing, you can write to the `user' output stream, as in
278
278
`io:format(user, "~w", [Term])'. The recommended way of doing this is to
279
 
use the EUnit {@section Debugging Macros}, which make it much simpler.
 
279
use the EUnit {@section Debugging macros}, which make it much simpler.
280
280
 
281
281
=== Writing test generating functions ===
282
282
 
295
295
The most basic representation of a test is a single fun-expression that
296
296
takes no arguments. For example, the following test generator:
297
297
```basic_test_() ->
298
 
       fun () -> ?assert(1 + 1 == 2) end.'''
 
298
       fun () -> ?assert(1 + 1 =:= 2) end.'''
299
299
will have the same effect as the following simple test:
300
300
```simple_test() ->
301
 
       ?assert(1 + 1 == 2).'''
 
301
       ?assert(1 + 1 =:= 2).'''
302
302
(in fact, EUnit will handle all simple tests just like it handles
303
303
fun-expressions: it will put them in a list, and run them one by one).
304
304
 
310
310
use the `_test' macro (note the initial underscore character), like
311
311
this:
312
312
```basic_test_() ->
313
 
       ?_test(?assert(1 + 1 == 2)).'''
 
313
       ?_test(?assert(1 + 1 =:= 2)).'''
314
314
The `_test' macro takes any expression (the "body") as argument, and
315
315
places it within a fun-expression (along with some extra information).
316
316
The body can be any kind of test expression, just like the body of a
323
323
underscore character, which automatically adds a `?_test(...)' wrapper.
324
324
The above example can then simply be written:
325
325
```basic_test_() ->
326
 
       ?_assert(1 + 1 == 2).'''
 
326
       ?_assert(1 + 1 =:= 2).'''
327
327
which has exactly the same meaning (note the `_assert' instead of
328
328
`assert'). You can think of the initial underscore as signalling
329
329
<em>test object</em>.
341
341
   fib(N) when N > 1 -> fib(N-1) + fib(N-2).
342
342
 
343
343
   fib_test_() ->
344
 
       [?_assert(fib(0) == 1),
345
 
        ?_assert(fib(1) == 1),
346
 
        ?_assert(fib(2) == 2),
347
 
        ?_assert(fib(3) == 3),
348
 
        ?_assert(fib(4) == 5),
349
 
        ?_assert(fib(5) == 8),
 
344
       [?_assert(fib(0) =:= 1),
 
345
        ?_assert(fib(1) =:= 1),
 
346
        ?_assert(fib(2) =:= 2),
 
347
        ?_assert(fib(3) =:= 3),
 
348
        ?_assert(fib(4) =:= 5),
 
349
        ?_assert(fib(5) =:= 8),
350
350
        ?_assertException(error, function_clause, fib(-1)),
351
 
        ?_assert(fib(31) == 2178309)
 
351
        ?_assert(fib(31) =:= 2178309)
352
352
       ].'''
353
353
 
354
354
(Author's note: When I first wrote this example, I happened to write a
417
417
<li>{@section Utility macros}</li>
418
418
<li>{@section Assert macros}</li>
419
419
<li>{@section Macros for running external commands}</li>
420
 
<li>{@section Debugging Macros}</li>
 
420
<li>{@section Debugging macros}</li>
421
421
</ul>
422
422
 
423
423
=== Basic macros ===
445
445
EUnit header file, when testing is disabled. See also the macros `TEST'
446
446
and `NOTEST'.
447
447
</dd>
 
448
 
 
449
<dt>`EUNIT_NOAUTO'</dt>
 
450
<dd>If this macro is defined, the automatic exporting or stripping of
 
451
test functions will be disabled.
 
452
</dd>
 
453
 
448
454
<dt>`TEST'</dt>
449
455
<dd>This macro is always defined (to `true', unless previously defined
450
456
by the user to have another value) whenever EUnit is enabled at compile
461
467
included (even if `NOTEST' is also defined), then the code will be
462
468
compiled with EUnit enabled.
463
469
</dd>
 
470
 
464
471
<dt>`NOTEST'</dt>
465
472
<dd>This macro is always defined (to `true', unless previously defined
466
473
by the user to have another value) whenever EUnit is <em>disabled</em>
473
480
disabled. See also {@section Disabling testing}.
474
481
</dd>
475
482
 
476
 
<dt>`EUNIT_NOAUTO'</dt>
477
 
<dd>If this macro is defined, the automatic exporting or stripping of
478
 
test functions will be disabled.
 
483
<dt>`NOASSERT'</dt>
 
484
<dd>If this macro is defined, the assert macros will have no effect,
 
485
when testing is also disabled. See {@section Assert macros}. When
 
486
testing is enabled, the assert macros are always enabled automatically
 
487
and cannot be disabled.
 
488
</dd>
 
489
 
 
490
<dt>`ASSERT'</dt>
 
491
<dd>If this macro is defined, it overrides the NOASSERT macro, forcing
 
492
the assert macros to always be enabled regardless of other settings.
 
493
</dd>
 
494
 
 
495
<dt>`NODEBUG'</dt>
 
496
<dd>If this macro is defined, the debugging macros will have no effect.
 
497
See {@section Debugging macros}. `NODEBUG' also implies `NOASSERT',
 
498
unless testing is enabled.
 
499
</dd>
 
500
 
 
501
<dt>`DEBUG'</dt>
 
502
<dd>If this macro is defined, it overrides the NODEBUG macro, forcing
 
503
the debugging macros to be enabled.
479
504
</dd>
480
505
</dl>
481
506
 
505
530
a "test object" instead of performing the test immediately. This is
506
531
equivalent to writing `?_test(assert(BoolExpr))', etc.)
507
532
 
 
533
If the macro `NOASSERT' is defined before the EUnit header file is
 
534
included, these macros have no effect when testing is also disabled; see
 
535
{@section Compilation control macros} for details.
 
536
 
508
537
<dl>
509
538
<dt>`assert(BoolExpr)'</dt>
510
539
<dd>Evaluates the expression `BoolExpr', if testing is enabled. Unless
515
544
`BoolExpr' will not be evaluated.
516
545
 
517
546
Typical usage:
518
 
```?assert(f(X, Y) == [])'''
 
547
```?assert(f(X, Y) =:= [])'''
519
548
 
520
549
The `assert' macro can be used anywhere in a program, not just in unit
521
550
tests, to check pre/postconditions and invariants. For example:
629
658
</dd>
630
659
</dl>
631
660
 
632
 
=== Debugging Macros ===
 
661
=== Debugging macros ===
633
662
 
634
663
To help with debugging, EUnit defines several useful macros for printing
635
664
messages directly to the console (rather than to the standard output).
640
669
line in the code.
641
670
 
642
671
If the macro `NODEBUG' is defined before the EUnit header file is
643
 
included, these macros have no effect.
 
672
included, these macros have no effect; see
 
673
{@section Compilation control macros} for details.
644
674
 
645
675
<dl>
646
676
<dt>`debugHere'</dt>