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