Skip to content

Commit b923eb1

Browse files
WalterBrightWalterBright
committed
revamp unittest description
1 parent 594a9be commit b923eb1

File tree

1 file changed

+85
-65
lines changed

1 file changed

+85
-65
lines changed

‎spec/unittest.dd

Lines changed: 85 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -8,87 +8,113 @@ $(GRAMMAR
88
$(GNAME UnitTest):
99
$(D unittest) $(GLINK2 statement, BlockStatement)
1010
)
11+
$(P Unit tests are a builtin framework of test cases
12+
applied to a module to determine if it is working properly.
13+
A D program can be run with unit tests enabled or disabled.
14+
)
1115

12-
$(P Unit tests are a series of test cases applied to a module to determine
13-
if it is working properly. Ideally, unit tests should be run every
14-
time a program is compiled.
15-
)
16+
$(P Unit tests are a special function defined like:)
1617

17-
$(P Unit tests are a special function defined like:)
18+
---
19+
unittest
20+
{
21+
...test code...
22+
}
23+
---
1824

19-
------
20-
unittest
21-
{
22-
...test code...
23-
}
24-
------
25+
$(P Individual tests are specified in the unit test using $(DDSUBLINK spec/expression, AssertExpression)s.
26+
Unlike $(I AssertExpression)s used elsewhere, the assert is not assumed to hold, and upon assert
27+
failure the program is still in a defined state.
28+
)
2529

2630
$(P There can be any number of unit test functions in a module,
2731
including within struct, union and class declarations.
2832
They are executed in lexical order.
29-
The order in which the modules are called to run their unit tests is
30-
implementation defined.
31-
Stylistically, a unit test for a function should appear immediately
32-
following it.
3333
)
3434

35-
$(P A compiler switch, such as $(DDSUBLINK dmd, switch-unittest, $(B -unittest))
36-
for $(B dmd), will
37-
cause the unittest test code to be compiled and incorporated into
38-
the resulting executable. The unittest code gets run after
39-
static initialization is run and before the $(D main())
40-
function is called.
35+
$(P Unit tests, when enabled, are run after all static initialization is
36+
complete and before the $(D main()) function is called.
4137
)
4238

43-
$(P $(GLINK UnitTest)s must be grammatically correct even if $(B -unittest) is not
44-
used.)
45-
4639
$(P For example, given a class $(D Sum) that is used to add two values, a unit
4740
test can be given:)
4841

49-
------
50-
class Sum
51-
{
52-
int add(int x, int y) { return x + y; }
53-
54-
unittest
42+
---
43+
class Sum
5544
{
56-
Sum sum = new Sum;
57-
assert(sum.add(3,4) == 7);
58-
assert(sum.add(-2,0) == -2);
45+
int add(int x, int y) { return x + y; }
46+
47+
unittest
48+
{
49+
Sum sum = new Sum;
50+
assert(sum.add(3,4) == 7);
51+
assert(sum.add(-2,0) == -2);
52+
}
5953
}
60-
}
61-
------
54+
---
55+
56+
$(P When unit tests are enabled, the $(DDSUBLINK spec/version, PredefinedVersions, version identifier)
57+
$(D unittest) is predefined.
58+
)
59+
6260

6361
$(H2 $(LNAME2 attributes_unittest, Attributed Unittests))
6462

65-
$(P A unittest may be attributed with any of the global function attributes.
66-
Such unittests are useful in verifying the given attribute(s) on a template
67-
function:)
63+
$(P A unittest may be attributed with any of the global function attributes.
64+
Such unittests are useful in verifying the given attribute(s) on a template
65+
function:)
6866

69-
------
70-
void myFunc(T)(T[] data)
71-
{
72-
if (data.length > 2)
73-
data[0] = data[1];
74-
}
67+
---
68+
void myFunc(T)(T[] data)
69+
{
70+
if (data.length > 2)
71+
data[0] = data[1];
72+
}
7573

76-
@safe nothrow unittest
77-
{
78-
auto arr = [1,2,3];
79-
myFunc(arr);
80-
assert(arr == [2,2,3]);
81-
}
82-
------
74+
@safe nothrow unittest
75+
{
76+
auto arr = [1,2,3];
77+
myFunc(arr);
78+
assert(arr == [2,2,3]);
79+
}
80+
---
81+
82+
$(P This unittest verifies that $(D myFunc) contains only $(D @safe),
83+
`nothrow` code. Although this can also be accomplished by attaching these
84+
attributes to $(D myFunc) itself, that would prevent $(D myFunc) from being
85+
instantiated with types $(D T) that have $(D @system) or throwing code in their
86+
$(D opAssign) method, or other methods that $(D myFunc) may call. The above
87+
idiom allows $(D myFunc) to be instantiated with such types, yet at the same
88+
time verify that the $(D @system) and throwing behavior is not introduced by
89+
the code within $(D myFunc) itself.)
90+
91+
$(IMPLEMENTATION_DEFINED
92+
$(OL
93+
$(LI If unit tests are not enabled, the implementation is not required to
94+
check the $(GLINK UnitTest) for syntactic or semantic correctness.
95+
This is to reduce the compile time impact of larger unit test sections.
96+
The tokens must still be valid, and the implementation can merely count
97+
$(D {) and $(D }) tokens to find the end of the $(GLINK UnitTest)'s $(GLINK2 statement, BlockStatement).
98+
)
99+
$(LI The presentation of unit test results to the user.)
100+
$(LI The method used to enable or disable the unit tests. Use of a compiler
101+
switch such as $(DDSUBLINK dmd, switch-unittest, $(B -unittest)) to enable
102+
them is suggested.)
103+
$(LI The order in which modules are called to run their unit tests.)
104+
$(LI Whether the program stops on the first unit test failure, or continues running the unit tests.)
105+
)
106+
)
107+
108+
$(BEST_PRACTICE
109+
$(OL
110+
$(LI Using unit tests in conjuction with coverage testing
111+
(such as $(DDSUBLINK dmd, switch-cov, $(B -cov)))
112+
is effective.)
113+
$(LI A unit test for a function should appear immediately
114+
following it.)
115+
)
116+
)
83117

84-
$(P This unittest verifies that $(D myFunc) contains only $(D @safe),
85-
`nothrow` code. Although this can also be accomplished by attaching these
86-
attributes to $(D myFunc) itself, that would prevent $(D myFunc) from being
87-
instantiated with types $(D T) that have $(D @system) or throwing code in their
88-
$(D opAssign) method, or other methods that $(D myFunc) may call. The above
89-
idiom allows $(D myFunc) to be instantiated with such types, yet at the same
90-
time verify that the $(D @system) and throwing behaviour is not introduced by
91-
the code within $(D myFunc) itself.)
92118

93119
$(H2 $(LNAME2 documented-unittests, Documented Unittests))
94120

@@ -197,12 +223,6 @@ code sample generated, even if it is empty or only includes comments
197223
</dl>
198224
)
199225

200-
$(H2 $(LNAME2 versioning, Versioning))
201-
202-
$(P The $(DDSUBLINK spec/version, PredefinedVersions, version identifier)
203-
$(D unittest) is predefined if the compilation
204-
is done with unit tests enabled.
205-
)
206226

207227
$(SPEC_SUBNAV_PREV_NEXT errors, Error Handling, garbage, Garbage Collection)
208228
)

0 commit comments

Comments
 (0)