Skip to content

Commit 46bb789

Browse files
peter-bpeter-b
committed
com.livecode.unittest: Add doc comments to test syntax.
Should help with writing LCB extension tests (even if there's no way to run them yet).
1 parent 48bc2e1 commit 46bb789

File tree

1 file changed

+221
-6
lines changed

1 file changed

+221
-6
lines changed

‎libscript/src/unittest.lcb‎

Lines changed: 221 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,18 +15,15 @@ for more details.
1515
You should have received a copy of the GNU General Public License
1616
along with LiveCode. If not see <http://www.gnu.org/licenses/>. */
1717

18-
/*
18+
/**
1919
This library provides syntax for unit testing LiveCode Builder
2020
programs. It is used by the LiveCode Builder standard library's
2121
testsuite.
2222

2323
To use this library, write your tests in a Builder source code file.
2424
Each group of tests should be a public handler with a name beginning
25-
with "Test". If possible, use one test per handler. Otherwise, add a
26-
"plan N tests" statement at the start of the handler.
27-
28-
The test results are output on standard output in TAP (Test Anything
29-
Protocol) format.
25+
with `Test`. If possible, use one test per handler. Otherwise, add a
26+
`plan N tests` statement at the start of the handler.
3027

3128
Example:
3229

@@ -49,6 +46,11 @@ Example:
4946
broken test false because "broken"
5047
broken test "Failed 4" when false because "really broken"
5148
end handler
49+
50+
The test results are output on standard output in TAP (Test Anything
51+
Protocol) format.
52+
53+
Tags: Unit tests
5254
*/
5355

5456
module com.livecode.unittest
@@ -61,12 +63,48 @@ foreign handler MCUnitOutputTest(in pCondition as Boolean, in pDescription as St
6163
-- Test syntax
6264
----------------------------------------------------------------
6365

66+
/**
67+
Summary: Announce how many test results are expected from the unit test.
68+
69+
Parameters:
70+
Count: The number of tests that are expected
71+
72+
Example:
73+
plan 3 tests
74+
75+
Description:
76+
Log the number of unit test assertions which are expected to occur in the
77+
current unit test. This may be used by the test framework to flag an error if
78+
too few test results appear in the test result. For example, this allows the
79+
test framework to detect whether a unit test failed silently.
80+
81+
Using `plan _ tests` is optional, and a unit test is valid even if its omitted.
82+
83+
Tags: Unit tests
84+
*/
6485
syntax UnitPlan is statement
6586
"plan" <Count: Expression> "tests"
6687
begin
6788
MCUnitPlan(Count)
6889
end syntax
6990

91+
/**
92+
Summary: Log unit test diagnostic message.
93+
94+
Parameters:
95+
Message: The message to log, as a String.
96+
97+
Example:
98+
test diagnostic "File access tests"
99+
100+
Description:
101+
Log a message as a test diagnostic. The <Message> may have multiple lines.
102+
You may wish to log diagnostic messages to help make the test log easier to
103+
read by adding info about what's being tested, or add information when a test
104+
fails to help understand why the failure occurred.
105+
106+
Tags: Unit tests
107+
*/
70108
syntax UnitDiagnostic is statement
71109
"test" "diagnostic" <Message: Expression>
72110
begin
@@ -75,6 +113,23 @@ end syntax
75113

76114
----------------------------------------------------------------
77115

116+
/**
117+
Summary: Make a unit test assertion
118+
119+
Parameters:
120+
Condition: An expression that evaluates to `true` if the test is successful
121+
122+
Example:
123+
test 2 > 1
124+
125+
Description:
126+
Make a basic unit test assertion, with no test description. It is usually more
127+
helpful to use <UnitTestDescription>.
128+
129+
References: UnitTestDescription(statement)
130+
131+
Tags: Unit tests
132+
*/
78133
syntax UnitTest is statement
79134
"test" <Condition: Expression>
80135
begin
@@ -85,6 +140,23 @@ public handler MCUnitTest(in pCondition as Boolean)
85140
MCUnitOutputTest(pCondition, "", "", "")
86141
end handler
87142

143+
/**
144+
Summary: Make a unit test assertion with a description
145+
146+
Parameters:
147+
Description: A short description of the test
148+
Condition: An expression that evaluates to `true` if the test is successful
149+
150+
Example:
151+
test "integer greater than" when 2 > 1
152+
153+
Description:
154+
Make a unit test assertion. The test is considered to have passed if
155+
<Condition> is true. The <Description> string is a short message that
156+
summarises what the test is checking.
157+
158+
Tags: Unit tests
159+
*/
88160
syntax UnitTestDescription is statement
89161
"test" <Description: Expression> "when" <Condition: Expression>
90162
begin
@@ -97,6 +169,17 @@ end handler
97169

98170
----------------------------------------------------------------
99171

172+
/**
173+
Summary: Record a skipped test
174+
175+
Description:
176+
Record that a test was skipped, with no description or reason. It is usually
177+
more helpful to use <UnitTestSkipDescriptionAndReason>.
178+
179+
References: UnitTestSkipDescriptionAndReason(statement)
180+
181+
Tags: Unit tests
182+
*/
100183
syntax UnitTestSkip is statement
101184
"skip" "test"
102185
begin
@@ -107,6 +190,21 @@ public handler MCUnitTestSkip()
107190
MCUnitOutputTest(true, "", "SKIP", "")
108191
end handler
109192

193+
/**
194+
Summary: Record a skipped test with a description
195+
196+
Parameters:
197+
Description: A short description of the skipped test
198+
199+
Example:
200+
skip test "open web socket"
201+
202+
Description:
203+
Record that a test was skipped. The <Description> string is a short message
204+
that summarises the test that was skipped.
205+
206+
Tags: Unit tests
207+
*/
110208
syntax UnitTestSkipDescription is statement
111209
"skip" "test" <Description: Expression>
112210
begin
@@ -117,6 +215,21 @@ public handler MCUnitTestSkipDescription(in pDescription as String)
117215
MCUnitOutputTest(true, pDescription, "SKIP", "")
118216
end handler
119217

218+
/**
219+
Summary: Record a skipped test with a reason for skipping
220+
221+
Parameters:
222+
Reason: A short explanation of why the test was skipped
223+
224+
Example:
225+
skip test because "not implemented"
226+
227+
Description:
228+
Record that a test was skipped, including a reason for skipping the test. The
229+
<Reason> is a short message that describes why the test has to be skipped.
230+
231+
Tags: Unit tests
232+
*/
120233
syntax UnitTestSkipReason is statement
121234
"skip" "test" "because" <Reason: Expression>
122235
begin
@@ -127,6 +240,24 @@ public handler MCUnitTestSkipReason(in pReason as String)
127240
MCUnitOutputTest(true, "", "SKIP", pReason)
128241
end handler
129242

243+
/**
244+
Summary: Record a skipped test with a test description and reason for skipping
245+
246+
Parameters:
247+
Description: A short description of the skipped test
248+
Reason: A brief explanation of why the test was skipped
249+
250+
Example:
251+
skip test "open web socket" because "not implemented"
252+
253+
Description:
254+
Record that a test was skipped. The <Description> is a message that summarises
255+
the test that was skipped, and the <Reason> explains why the test couldn't be
256+
done. For example, the feature being tested isn't supported by the platform
257+
that the test is running on.
258+
259+
Tags: Unit tests
260+
*/
130261
syntax UnitTestSkipDescriptionAndReason is statement
131262
"skip" "test" <Description: Expression> "because" <Reason: Expression>
132263
begin
@@ -139,6 +270,24 @@ end handler
139270

140271
----------------------------------------------------------------
141272

273+
/**
274+
Summary: Make a failing unit test assertion
275+
276+
Parameters:
277+
Condition: An expression that evaluates to `true` if the test is successful
278+
279+
Example:
280+
broken test 1 > 2
281+
282+
Description:
283+
Make a unit test assertion, in the expectation that it will fail, and without
284+
providing a description or reason. It is usually more helpful to use
285+
<UnitTestFailsDescriptionAndReason>.
286+
287+
References: UnitTestFailsDescriptionAndReason(statement)
288+
289+
Tags: Unit tests
290+
*/
142291
syntax UnitTestFails is statement
143292
"broken" "test" <Condition: Expression>
144293
begin
@@ -149,6 +298,27 @@ public handler MCUnitTestFails(in pCondition as Boolean)
149298
MCUnitOutputTest(pCondition, "", "TODO", "")
150299
end handler
151300

301+
/**
302+
Summary: Make a failing unit test assertion with a description
303+
304+
Parameters:
305+
Description: A short description of the test
306+
Condition: An expression that evaluates to `true` if the test is successful
307+
308+
Example:
309+
broken test "weird comparison" when 1 > 2
310+
311+
Description:
312+
Make a unit test assertion, in the expectation that it will fail. The test is
313+
considered to have passed if <Condition> is true. The <Description> string is
314+
a short message that summarises what the test is checking.
315+
316+
If the test fails, it will not cause a test suite failure; instead, an
317+
"expected failure" will be recorded. If the test passes, an "unexpected pass"
318+
will be recorded instead of a normal test pass.
319+
320+
Tags: Unit tests
321+
*/
152322
syntax UnitTestFailsDescription is statement
153323
"broken" "test" <Description: Expression> "when" <Condition: Expression>
154324
begin
@@ -159,6 +329,28 @@ public handler MCUnitTestFailsDescription(in pDescription as String, in pConditi
159329
MCUnitOutputTest(pCondition, pDescription, "TODO", "")
160330
end handler
161331

332+
/**
333+
Summary: Make a failing unit test assertion with a reason for brokenness
334+
335+
Parameters:
336+
Condition: An expression that evaluates to `true` if the test is successful
337+
Reason: A short explanation of why the test is broken
338+
339+
Example:
340+
broken test 1 > 2 because "bug 12345"
341+
342+
Description:
343+
Make a unit test assertion, in the expectation that it will fail. The test is
344+
considered to have passed if <Condition> is true. The <Reason> is a shor
345+
message that describes why the test is broken (usually referencing a bug
346+
report).
347+
348+
If the test fails, it will not cause a test suite failure; instead, an
349+
"expected failure" will be recorded. If the test passes, an "unexpected pass"
350+
will be recorded instead of a normal test pass.
351+
352+
Tags: Unit tests
353+
*/
162354
syntax UnitTestFailsReason is statement
163355
"broken" "test" <Condition: Expression> "because" <Reason: Expression>
164356
begin
@@ -169,6 +361,29 @@ public handler MCUnitTestFailsReason(in pCondition as Boolean, in pReason as Str
169361
MCUnitOutputTest(pCondition, "", "TODO", pReason)
170362
end handler
171363

364+
/**
365+
Summary: Make a failing unit test assertion with a reason for brokenness
366+
367+
Parameters:
368+
Description: A short description of the failing test
369+
Condition: An expression that evaluates to `true` if the test is successful
370+
Reason: A short explanation of why the test is broken
371+
372+
Example:
373+
broken test "weird comparison" when 1 > 2 because "bug 12345"
374+
375+
Description:
376+
Make a unit test assertion, in the expectation that it will fail. The test is
377+
considered to have passed if <Condition> is true. The <Description> is a
378+
message that summarises the broken test, and the <Reason> explains why the test
379+
is broken (usually referencing a bug report).
380+
381+
If the test fails, it will not cause a test suite failure; instead, an
382+
"expected failure" will be recorded. If the test passes, an "unexpected pass"
383+
will be recorded instead of a normal test pass.
384+
385+
Tags: Unit tests
386+
*/
172387
syntax UnitTestFailsDescriptionAndReason is statement
173388
"broken" "test" <Description: Expression> "when" <Condition: Expression> "because" <Reason: Expression>
174389
begin

0 commit comments

Comments
 (0)