README.md
1# tapered [](https://travis-ci.org/telemachus/tapered) [](https://codecov.io/gh/telemachus/tapered)
2
3## Synopsis
4
5Very minimal tap testing for Lua. Arguably too minimal.
6
7## Assertions
8
9The `message` parameter is always optional. Brief messages help make test output
10clearer to readers, but are not needed if the output goes straight to another
11program for parsing.
12
13+ `ok(expression, [message])` Tests whether `expression` returns a truthy
14 value.
15
16+ `nok(expression, [message])` Tests whether `expression` returns a falsy
17 value.
18
19+ `is(actual, expected, [message])` Tests whether `actual` is equal to
20 `expected`. The test uses `==` internally.
21
22+ `isnt(actual, expected, [message])` Tests whether `actual` is not equal to
23 `actual`. The test uses `~=` internally.
24
25+ `same(actual, expected, [message])` Tests whether `actual` is a deep copy
26 of `expected`. The test uses an `__eq` metamethod if one is found. Useful
27 for comparing tables.
28
29+ `like(string, pattern, [message])` Tests whether `string` matches the given
30 `pattern`.
31
32+ `unlike(string, pattern, [message])` Tests whether `string` does not match
33 the given `pattern`.
34
35+ `pass([message])` A test that always passes. Useful as a quasi-skip with a
36 message.
37
38+ `fail([message])` A test that always fails. Useful as a quasi-TODO with a
39 message.
40
41+ `boom(function, args, [message])` Calls `function` with `args` as
42 parameters and checks to see if an exception is raised. Passes if an
43 exception is raised; fails otherwise. (The exception is swallowed.) The
44 `args` parameter expects a table. The table can be empty but not `nil`.
45
46## Helper method
47
48A method is available to show how many tests were run. (This output
49is required for [TAP compliance][tap], which may matter in some cases.)
50
51[tap]: http://testanything.org/tap-specification.html
52
53+ `done([number])` Call this function (optionally) at the end of your test file.
54 It will print out a line in the form `1..n` where `n` is the total number
55 of tests run. This secures TAP compliance when needed. The call to `done`
56 is not otherwise required. If you don't care about TAP compliance, neither does
57 the library. If you pass the optional parameter to the method, it will check
58 whether the number of tests you expected matches the number of actual tests.
59 Thus, if can function like a traditional `plan` method. However, this method
60 should always be called *last* in your tap file, unlike `plan` methods which
61 normally start the test file.
62
63 Another reason to use `done` is if you care about the exit status of the
64 tests. Many continuous integration tools rely on tests signalling success or
65 failure via their exit status. After `done` is called, the script will exit
66 with a status of 0, indicating success, if all tests passed. If some tests
67 failed, the script will exit with a status equal to the number of failed
68 tests, indicating failure. A script will also exit with an error status if
69 there is a mismatch between the actual number of tests run and the number
70 passed to `done` as a parameter.
71
72## Varia
73
74The module provides four informational functions that return strings. They
75should be self-explanatory.
76
77+ `version() -- 2.3.0`
78
79+ `author() -- Peter Aronoff`
80
81+ `url() -- https://github.com/telemachus/tapered.git`
82
83+ `license() -- BSD 3-Clause`
84
85## Credits
86
87For the `same` method I took ideas and code from [Penlight][p], [Underscore][u],
88[luassert][l], and [cwtest][cw]. I thank all the people who worked on those.
89
90Indirect inspirations include [knock][k], [Test::More][tm], and [bats][b]—not so
91much for code as for ideas about testing and simplicity.
92
93Thanks in particular to [Pierre Chapuis][pchapuis] for help with ideas and
94getting continuous integration for tapered.
95
96An anonymous email showed me that my setup and teardown methods had a logical
97flaw. As a result, I've removed those methods. I appreciate the report.
98
99All the mistakes are mine. See [version history][c] for release details.
100
101[p]: https://github.com/stevedonovan/Penlight
102[u]: https://github.com/mirven/underscore.lua
103[l]: https://github.com/Olivine-Labs/luassert
104[cw]: https://github.com/catwell/cwtest
105[k]: https://github.com/chneukirchen/knock
106[tm]: http://search.cpan.org/perldoc?Test::More
107[b]: https://github.com/sstephenson/bats
108[c]: /CHANGES.md
109[pchapuis]: https://twitter.com/pchapuis
110
111---
112
113(c) 2012-2017 Peter Aronoff. BSD 3-Clause license; see [LICENSE.md][li] for
114details.
115
116[li]: /LICENSE.md
117
){kind=link}
){kind=link}