summaryrefslogtreecommitdiffstats
path: root/tests/config/tapered/README.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--tests/config/tapered/README.md116
1 files changed, 116 insertions, 0 deletions
diff --git a/tests/config/tapered/README.md b/tests/config/tapered/README.md
new file mode 100644
index 0000000..bafb2e7
--- /dev/null
+++ b/tests/config/tapered/README.md
@@ -0,0 +1,116 @@
+# tapered [![Build Status](https://travis-ci.org/telemachus/tapered.svg?branch=master)](https://travis-ci.org/telemachus/tapered) [![Coverage](https://codecov.io/gh/telemachus/tapered/branch/master/graph/badge.svg)](https://codecov.io/gh/telemachus/tapered)
+
+## Synopsis
+
+Very minimal tap testing for Lua. Arguably too minimal.
+
+## Assertions
+
+The `message` parameter is always optional. Brief messages help make test output
+clearer to readers, but are not needed if the output goes straight to another
+program for parsing.
+
++ `ok(expression, [message])` Tests whether `expression` returns a truthy
+ value.
+
++ `nok(expression, [message])` Tests whether `expression` returns a falsy
+ value.
+
++ `is(actual, expected, [message])` Tests whether `actual` is equal to
+ `expected`. The test uses `==` internally.
+
++ `isnt(actual, expected, [message])` Tests whether `actual` is not equal to
+ `actual`. The test uses `~=` internally.
+
++ `same(actual, expected, [message])` Tests whether `actual` is a deep copy
+ of `expected`. The test uses an `__eq` metamethod if one is found. Useful
+ for comparing tables.
+
++ `like(string, pattern, [message])` Tests whether `string` matches the given
+ `pattern`.
+
++ `unlike(string, pattern, [message])` Tests whether `string` does not match
+ the given `pattern`.
+
++ `pass([message])` A test that always passes. Useful as a quasi-skip with a
+ message.
+
++ `fail([message])` A test that always fails. Useful as a quasi-TODO with a
+ message.
+
++ `boom(function, args, [message])` Calls `function` with `args` as
+ parameters and checks to see if an exception is raised. Passes if an
+ exception is raised; fails otherwise. (The exception is swallowed.) The
+ `args` parameter expects a table. The table can be empty but not `nil`.
+
+## Helper method
+
+A method is available to show how many tests were run. (This output
+is required for [TAP compliance][tap], which may matter in some cases.)
+
+[tap]: http://testanything.org/tap-specification.html
+
++ `done([number])` Call this function (optionally) at the end of your test file.
+ It will print out a line in the form `1..n` where `n` is the total number
+ of tests run. This secures TAP compliance when needed. The call to `done`
+ is not otherwise required. If you don't care about TAP compliance, neither does
+ the library. If you pass the optional parameter to the method, it will check
+ whether the number of tests you expected matches the number of actual tests.
+ Thus, if can function like a traditional `plan` method. However, this method
+ should always be called *last* in your tap file, unlike `plan` methods which
+ normally start the test file.
+
+ Another reason to use `done` is if you care about the exit status of the
+ tests. Many continuous integration tools rely on tests signalling success or
+ failure via their exit status. After `done` is called, the script will exit
+ with a status of 0, indicating success, if all tests passed. If some tests
+ failed, the script will exit with a status equal to the number of failed
+ tests, indicating failure. A script will also exit with an error status if
+ there is a mismatch between the actual number of tests run and the number
+ passed to `done` as a parameter.
+
+## Varia
+
+The module provides four informational functions that return strings. They
+should be self-explanatory.
+
++ `version() -- 2.3.0`
+
++ `author() -- Peter Aronoff`
+
++ `url() -- https://github.com/telemachus/tapered.git`
+
++ `license() -- BSD 3-Clause`
+
+## Credits
+
+For the `same` method I took ideas and code from [Penlight][p], [Underscore][u],
+[luassert][l], and [cwtest][cw]. I thank all the people who worked on those.
+
+Indirect inspirations include [knock][k], [Test::More][tm], and [bats][b]—not so
+much for code as for ideas about testing and simplicity.
+
+Thanks in particular to [Pierre Chapuis][pchapuis] for help with ideas and
+getting continuous integration for tapered.
+
+An anonymous email showed me that my setup and teardown methods had a logical
+flaw. As a result, I've removed those methods. I appreciate the report.
+
+All the mistakes are mine. See [version history][c] for release details.
+
+[p]: https://github.com/stevedonovan/Penlight
+[u]: https://github.com/mirven/underscore.lua
+[l]: https://github.com/Olivine-Labs/luassert
+[cw]: https://github.com/catwell/cwtest
+[k]: https://github.com/chneukirchen/knock
+[tm]: http://search.cpan.org/perldoc?Test::More
+[b]: https://github.com/sstephenson/bats
+[c]: /CHANGES.md
+[pchapuis]: https://twitter.com/pchapuis
+
+---
+
+(c) 2012-2017 Peter Aronoff. BSD 3-Clause license; see [LICENSE.md][li] for
+details.
+
+[li]: /LICENSE.md