2018-03-31 22:45:35 +00:00
# Test.it
> A minimalistic testing library
2018-04-07 08:07:58 +00:00
**Test.it** is a small testing library for people that want to live in code, not in tests. No over engineering here. Inspired by the simplicity of libraries like [Tape ](https://github.com/substack/tape ),but the implementation ideas of things like [Expect ](https://github.com/Automattic/expect.js ) and [TinyTest ](https://github.com/joewalnes/jstinytest )
2018-12-02 09:30:08 +00:00
This is probally not a *cure-all* testing solution, if you want something more robust checkout [Jasmine ](https://jasmine.github.io/ ), [Tape ](https://github.com/substack/tape ) or [Mocha ](https://mochajs.org/ ) -- this is to...
2018-04-07 08:07:58 +00:00
**Test small things, with small things**
2018-03-31 22:45:35 +00:00
2018-04-02 08:37:02 +00:00
### Features
2020-09-08 22:37:54 +00:00
- Designed for the Browser
- Works with NodeJS
- *Under* a 100 lines
2018-04-02 08:37:02 +00:00
- Single File
2018-04-02 09:21:42 +00:00
- No Dependicies
- 2kb footprint (*before gzip*)
2018-04-07 08:07:58 +00:00
- Extend with custom reporters
2018-12-02 08:43:35 +00:00
- Has an Expect-like style BDD assertions
2018-04-02 08:37:02 +00:00
**No Bloat Here!**
2018-12-02 09:30:08 +00:00
- [Download Here ](https://raw.githubusercontent.com/n2geoff/testit/master/src/testit.js )
- [Or Minified Version Here ](https://raw.githubusercontent.com/n2geoff/testit/master/src/testit.min.js )
2018-04-02 08:37:02 +00:00
2018-03-31 22:45:35 +00:00
## Usage
By default, you can run your tests like
```js
test.it({
'my passing test': function() {
2018-04-07 08:07:58 +00:00
test.expects().to.pass();
2018-03-31 22:45:35 +00:00
},
'my failing test': function() {
2018-04-07 08:07:58 +00:00
test.expects().to.fail('just wanted to fail fast');
2018-03-31 22:45:35 +00:00
}
2018-04-02 08:37:02 +00:00
}).run();
2018-03-31 22:45:35 +00:00
```
2018-06-06 12:08:44 +00:00
> NOTE: `run()` can be called elsewhere, see [tests/](test/run.html)
2018-03-31 22:45:35 +00:00
2018-06-06 12:05:02 +00:00
by default, your test results are logged to the console
2018-03-31 22:45:35 +00:00
```
2018-12-02 08:43:35 +00:00
+OK my passing test
-ERR my failing test
---
Error: just wanted to fail fast
2018-03-31 22:45:35 +00:00
...error stack...
2018-12-02 08:43:35 +00:00
---
2018-06-06 12:05:02 +00:00
# tests 2 pass 1 fail 1
2018-03-31 22:45:35 +00:00
```
2018-12-02 09:30:08 +00:00
A `+OK` will proceed test lines that *pass* and a `-ERR` for those that *fail* , An error stack is included by default after the failing test wrapped in `---` . You can suppress outputing the error stack by passing `false` as an argument to `run()` , ie `run(false)` .
2018-06-06 12:05:02 +00:00
2019-01-13 21:47:55 +00:00
You can, also, write your own custom test runner...
2018-03-31 22:45:35 +00:00
2018-06-06 12:05:02 +00:00
### Custom Test Runners
2018-03-31 22:45:35 +00:00
2018-06-06 12:05:02 +00:00
`test.it` `.run()` method provides an optional `next` function parameter that passes the results as an `object` for you to process *however* you like.
2018-04-02 08:37:02 +00:00
For Example...
2018-03-31 22:45:35 +00:00
**For Fans of [TinyTest ](https://github.com/joewalnes/jstinytest )**
```js
test.it({
'my passing test': function() {
test.pass();
}
}, function(results) {
if (window.document & & document.body) {
document.body.style.backgroundColor = (
results.fail.length ? '#ff9999' : '#99ff99'
);
}
});
```
2018-06-06 12:05:02 +00:00
If using the optional `next` param will return results as JSON
2018-03-31 22:45:35 +00:00
```json
{
2018-04-02 09:21:42 +00:00
"pass": ["list of passed tests", "..."],
"fail": ["list of errored tests", "..."],
2018-03-31 22:45:35 +00:00
}
```
2018-04-02 08:37:02 +00:00
From this object you can easily find the number of tests ran `pass.length` , number of failed tests `fail.length` or the total test count by adding the two. Simple.
2018-03-31 22:45:35 +00:00
2018-12-02 09:30:08 +00:00
> REMEMBER: you can bypass error output too
2018-06-06 12:05:02 +00:00
A sample test runner is provided for both **HTML** and **NODE** in the `test/` directory; `run.html` and `run.js` respectfully.
2018-03-31 22:45:35 +00:00
## Methods
2018-12-02 08:43:35 +00:00
To stay minimal, `test.it` only has 3 core functions:
2018-04-07 08:07:58 +00:00
- `it` to capture your tests
- `run` to execute yours tests
2018-12-02 08:43:35 +00:00
- and `expects` to write your assertions
2018-03-31 22:45:35 +00:00
2018-04-07 08:07:58 +00:00
While you can use your own assertion library, the included `expects` provides the following methods for writing your tests:
| Methods | Description |
| --------------------------------- | --------------------------------------- |
2019-01-13 21:47:55 +00:00
| `.expects(tests).to.exist()` | truthy evalution `.exist` or `.be.ok()` |
2018-04-07 08:07:58 +00:00
| `.expects().to.pass()` | pass test |
| `.expects().to.fail(message)` | fails test with message |
| `.expects(this).to.equal(that)` | strictly equal evaluation using `===` |
| `.expects(this).to.be.like(that)` | loose evaluation using `==` |
| `.expects(123).to.be.a('number')` | check typeof value (`.a()` or `.an()` ) |
2018-03-31 22:45:35 +00:00
> NOTE: wish `eval` was not so evil, `assert(expression, message)` would be ideal
2018-04-07 08:07:58 +00:00
if you want to shorten test typing try
let expect = test.expects;
putting that above your tests will allow you to write like
```js
test.it({
"my test should work": function() {
expect().to.pass();
}
});
```
2018-06-06 12:05:02 +00:00
## TODO
- write `not` expects, ie `expects(this).to.not.equal(this)`
- provide sample test runner for CI environments
2018-04-02 08:37:02 +00:00
## Support
Please open [an issue ](https://github.com/n2geoff/testit/issues/new ) for support.
## Contributing
2018-12-02 08:43:35 +00:00
Anyone is welcome to contribute, however, if you decide to get involved, please take a moment to review the [guidelines ](CONTRIBUTING.md ), they're minimalistic;)
2018-04-02 08:37:02 +00:00
2018-03-31 22:45:35 +00:00
## License
2018-04-07 08:07:58 +00:00
[MIT ](LICENSE )