Remove faith's readme
This commit is contained in:
XeroOl
parent
1f44c99ef1
commit
7469a8854c
@ -1,121 +0,0 @@
|
|||||||
# Faith
|
|
||||||
|
|
||||||
> It's been a long road...
|
|
||||||
> Getting from there to here.
|
|
||||||
|
|
||||||
The Fennel Advanced Interactive Test Helper.
|
|
||||||
|
|
||||||
To use Faith, create a test runner file which calls the `run` function with
|
|
||||||
a list of module names. The modules should export functions whose
|
|
||||||
names start with `test-` and which call the assertion functions in the
|
|
||||||
`faith` module.
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
Your test runner file `test/init.fnl` can be very short:
|
|
||||||
|
|
||||||
```fennel
|
|
||||||
(local t (require :faith))
|
|
||||||
|
|
||||||
(local default-modules [:test.one-thing :test.other :test.third])
|
|
||||||
|
|
||||||
(t.run (if (= 0 (length arg)) default-modules arg))
|
|
||||||
```
|
|
||||||
|
|
||||||
You can run the `t.run` function from the REPL as well after reloading
|
|
||||||
your test modules.
|
|
||||||
|
|
||||||
Tests are just functions in test modules which call assertion functions.
|
|
||||||
|
|
||||||
```fennel
|
|
||||||
(local t (require :faith))
|
|
||||||
|
|
||||||
;; A setup-all function can load files from disk; connect to a server, etc
|
|
||||||
(fn setup-all []
|
|
||||||
(with-open [f (io.open "test/data.txt")]
|
|
||||||
(let [contents (f:read :*all)]
|
|
||||||
;; whatever the setup-all function returns will be passed as
|
|
||||||
;; an argument to every test function.
|
|
||||||
{: contents :length (length contents) :status "initialized"})))
|
|
||||||
|
|
||||||
(fn test-add [_data]
|
|
||||||
(t.= 2 (+ 1 1))
|
|
||||||
;; assert= tests for deep equality, not just table identity
|
|
||||||
(t.= [1 99] [1 (+ 45 44)]))
|
|
||||||
|
|
||||||
(fn test-check [data]
|
|
||||||
(t.= 0 (- 2 2)))
|
|
||||||
|
|
||||||
{: setup-all
|
|
||||||
: test-add
|
|
||||||
: test-check}
|
|
||||||
```
|
|
||||||
|
|
||||||
You can provide `setup` and `teardown` functions to run before and after
|
|
||||||
each test, as well as, `setup-all` and `teardown-all` to run before and
|
|
||||||
after each test module. Whatever values `setup-all` returns are passed
|
|
||||||
into each of the test functions and also the `teardown-all` function.
|
|
||||||
|
|
||||||
Note that in a language like Fennel that has tail-call optimization,
|
|
||||||
it's possible for an assertion on the last line of a function to fail
|
|
||||||
in a way that obscures the line number of the failure. If this is a
|
|
||||||
concern, you can put a `nil` or `(values)` on the last line of each
|
|
||||||
test function.
|
|
||||||
|
|
||||||
This is an issue for any test framework; it is not specific to Faith.
|
|
||||||
|
|
||||||
Faith supports PUC Lua 5.1 to 5.4 as well as LuaJIT.
|
|
||||||
|
|
||||||
If the `luasocket` or `luaposix` libraries are installed, Faith will
|
|
||||||
use them to calculate the total runtime of the test run. Without these
|
|
||||||
libraries, Lua is unable to track elapsed time with granularity of
|
|
||||||
under a second, so approximate times will be displayed instead.
|
|
||||||
|
|
||||||
## Assertions
|
|
||||||
|
|
||||||
All assertions take an optional message string as their last argument.
|
|
||||||
|
|
||||||
* `is`: checks truthiness (anything other than `false` or `nil`)
|
|
||||||
* `error`: checks that the given function errors out
|
|
||||||
|
|
||||||
All these assertions take the expected value first, then the actual.
|
|
||||||
|
|
||||||
* `=`: deep equality checks on tables, regular equality otherwise
|
|
||||||
* `not=`: checks the opposite of `=`
|
|
||||||
* `<`: checks that the arguments are in increasing order
|
|
||||||
* `<=`: checks that the arguments are in increasing or equal order
|
|
||||||
* `almost=`: is the actual value within a tolerance of expected?
|
|
||||||
* `identical`: regular `=` equality; checks tables for identity
|
|
||||||
* `match`: checks that the actual string matches an expected pattern
|
|
||||||
* `not-match`: checks the opposite
|
|
||||||
* `error-match`: checks that a function errors out and the error matches an
|
|
||||||
expected pattern
|
|
||||||
|
|
||||||
You can call `skip` in a test to indicate that the test is incomplete
|
|
||||||
without triggering a failure.
|
|
||||||
|
|
||||||
## Developing Faith
|
|
||||||
|
|
||||||
Run `make testall` to run the full suite against all supported Lua
|
|
||||||
versions. Currently the `Makefile` assumes that there is a checkout of
|
|
||||||
Fennel itself in the same directory as your checkout of Faith, but you
|
|
||||||
can override this with, e.g., `make test FENNEL=/usr/local/bin/fennel`.
|
|
||||||
|
|
||||||
Discussion happens on [the Fennel mailing
|
|
||||||
list](https://lists.sr.ht/%7Etechnomancy/fennel) and on the `#fennel`
|
|
||||||
channel on Libera chat and matrix.org.
|
|
||||||
|
|
||||||
## TODO
|
|
||||||
|
|
||||||
* [ ] document hooks
|
|
||||||
* [ ] detailed/colored diffs for failed equality assertions?
|
|
||||||
|
|
||||||
## License
|
|
||||||
|
|
||||||
Faith was based on [lunatest](https://github.com/silentbicycle/lunatest)
|
|
||||||
originally but has evolved significantly since its beginning.
|
|
||||||
|
|
||||||
© 2009-2013 Scott Vokes and contributors
|
|
||||||
© 2023 Phil Hagelberg and contributors
|
|
||||||
|
|
||||||
Released under the [MIT License](LICENSE).
|
|
||||||
Loading…
Reference in New Issue
Block a user