A very simple JS testing framework, for educational purposes. Live at npm at @pmoo/testy.
➡️ Documentación en español aquí 👷 Contributing guidelines
npm install --save-dev @pmoo/testy (if you use npm)
yarn add --dev @pmoo/testy (if you use yarn)
Supported Node versions: 18.x or higher (versions with active and security support listed here)
A test suite is a file ending _test.js that looks like this:
// my_test.js
import { suite, test, assert } from "@pmoo/testy";
suite("a boring test suite", () => {
test("42 is 42, not surprising", () => {
assert.that(42).isEqualTo(42);
});
});A test suite represents a grouping of tests, and it is implemented as a function call to suite passing a name and a zero-argument function, which is the suite body.
A test is implemented as a function call to test(), passing a name and the test body as a zero-argument function.
Inside the test you can call different assertions that are documented in detail later on.
You can run an individual test file using:
$ npx testy my_test.js
Or, you can run it without arguments to run all the tests (by default it looks on a tests folder located in the project root):
$ npx testy
You can also add it as the test script for npm/yarn in your package.json:
{
...
"scripts": {
"test": "npx testy"
},
...
}
And then run the tests using npm test or yarn test.
Testy will look for a .testyrc.json configuration file in the project root directory. You can use this configuration as a template (values here are the defaults):
{
"directory": "./tests", // directory including your test files
"filter": ".*_test.js$", // which convention to use to recognize test files
"language": "en", // language of the output messages. "es" and "en" supported for now
"failFast": false, // enable/disable fail fast mode (stop as soon as a failed test appears)
"randomOrder": false // enable/disable execution of tests in random order
"timeoutMs": 1000 // sets the per-test timeout in milliseconds
}
These are all the configuration parameters you can set. Feel free to change it according to your needs.
When declaring this configuration, every test suite under the tests directory (matching files ending with *test.js) will be executed.
There must be at least one assertion on the test to be valid. These are all the supported assertion types:
- Boolean assertions:
assert.that(boolean).isTrue()orassert.isTrue(boolean). It does a strict comparison againsttrue(object === true)assert.that(boolean).isFalse()orassert.isFalse(boolean). It does a strict comparison againstfalse(object === false)
- Equality assertions:
assert.that(actual).isEqualTo(expected)orassert.areEqual(actual, expected).assert.that(actual).isNotEqualTo(expected)orassert.areNotEqual(actual, expected)- Equality assertions use a deep object comparison (based on Node's
assertmodule) and fail if objects under comparison have circular references. - Equality criteria on non-primitive objects can be specified:
- Passing an extra two-arg comparator function to
isEqualTo(expected, criteria)orareEqual(actual, expected, criteria) - Passing a method name that
actualobject understands:isEqualTo(expected, 'myEqMessage')orareEqual(actual, expected, 'myEqMessage') - By default, if
actualhas anequalsmethod it will be used. - If we compare
undefinedwithundefinedusingisEqualTo(), it will make the test fail. For explicit check forundefined, use theisUndefined()/isNotUndefined()assertions documented above.
- Passing an extra two-arg comparator function to
- Identity assertions:
assert.that(actual).isIdenticalTo(expected)orassert.areIdentical(actual, expected)assert.that(actual).isNotIdenticalTo(expected)orassert.areNotIdentical(actual, expected)- Identity assertions check if two references point to the same object using the
===operator.
- Check for
undefinedpresence/absence:assert.that(aValue).isUndefined()orassert.isUndefined(aValue)assert.that(aValue).isNotUndefined()orassert.isNotUndefined(aValue)
- Check for
nullpresence/absence:assert.that(aValue).isNull()orassert.isNull(aValue)assert.that(aValue).isNotNull()orassert.isNotNull(aValue)
- Exception testing:
assert.that(() => { ... }).raises(error)or with regex.raises(/part of message/)assert.that(() => { ... }).doesNotRaise(error)assert.that(() => { ... }).doesNotRaiseAnyErrors()
- Numeric assertions:
- Comparators:
assert.that(aNumber).isGreaterThan(anotherNumber)assert.that(aNumber).isLessThan(anotherNumber)assert.that(aNumber).isGreaterThanOrEqualTo(anotherNumber)assert.that(aNumber).isLessThanOrEqualTo(anotherNumber)
- Rounding:
assert.that(aNumber).isNearTo(anotherNumber). There's a second optional argument that indicates the number of digits to be used for precision. Default is4.
- Comparators:
- String assertions:
assert.that(string).matches(regexOrString)orassert.isMatching(string, regexOrString)
- Array inclusion:
assert.that(collection).includes(object)assert.that(collection).doesNotInclude(object)assert.that(collection).includesExactly(...objects)
- Emptiness
assert.that(collection).isEmpty()orassert.isEmpty(collection)assert.that(collection).isNotEmpty()orassert.isNotEmpty(collection)- the collection under test can be an
Array, aStringor aSet
Please take a look at the tests folder, you'll find examples of each possible test you can write. Testy is self-tested.
If you don't have a NPM project you can install testy globally using npm install -g testy and then run testy <files>
-
Running code before/after every test: just like many testing frameworks have, there is a way to execute some code before or after each test in a suite using the
before()andafter()functions, respectively. You can use only one definition ofbefore()andafter()per suite, and they always receive a function as argument. Example:```javascript import { suite, test, assert, before, after } from '@pmoo/testy'; suite('using the before() and after() helpers', () => { let answer; before(() => { answer = 42; }); test('checking the answer', () => { assert.that(answer).isEqualTo(42); }); after(() => { answer = undefined; }); }); ``` -
Support for pending tests: if a test has no body, it will be reported as
[WIP]and it won't be considered a failure. -
Support for skipped tests: you can skip a test by adding
.skip()after test declaration, it will be reported as[SKIP]and it won't be executed nor considered a failure.```javascript import { suite, test, assert } from '@pmoo/testy'; suite('I am a suite with a skipped test', () => { test('I am a skipped test', async () => { assert.that(1).isEqualTo(1); }).skip(); }); ``` -
Support for asynchronous tests: if the code you are testing has
asynclogic, you canawaitinside the test definition and make assertions later. You can also use it onbefore()andafter()declarations. Example:```javascript import { suite, test, assert, before } from '@pmoo/testy'; const promiseOne = async () => Promise.resolve(42); const promiseTwo = async () => Promise.resolve(21); suite('using async & await', () => { let answerOne; before(async () => { answerOne = await promiseOne(); }); test('comparing results from promises', async () => { const answerTwo = await promiseTwo(); assert.that(answerOne).isEqualTo(42); assert.that(answerTwo).isEqualTo(21); }); }); ``` -
Fail-Fast mode: if enabled, it stops execution in the first test that fails (or has an error). Remaining tests will be marked as skipped.
-
Run tests and suites in random order: a good test suite does not depend on a particular order. Enabling this setting is a good way to ensure that.
-
Strict check for assertions: if a test does not evaluate any assertion while it is executed, the result is considered an error. Basically, a test with no assertion is considered a "bad" test.
-
Explicitly failing or marking a test as pending: there's a possibility of marking a test as failed or pending, for example:
import { suite, test, fail, pending } from "@pmoo/testy"; suite("marking tests as failed and pending", () => { test("marking as failed", () => fail.with("should not be here")); test("marking as pending", () => pending.dueTo("did not have time to finish")); });
The output includes the messages provided:
[FAIL] marking as failed => should not be here [WIP] marking as pending => did not have time to finish
Why another testing tool? The main reason is that we want to keep simplicity, something it's hard to see in the main testing tools out there.
- Zero dependencies: right now, this project does not depend on any npm package, making the tool easy to install, and fast: essential to have immediate feedback while doing TDD. This is also good for installing on places where the internet connection is not good and we don't want to download hundreds of libraries.
- Understandable object-oriented code: we want to use this tool for teaching, so eventually we'll look at the code during lessons, and students should be able to see what is going on, and even contributing at it, with no dark magic involved. Also, we try to follow good OO practices.
- Unique set of features: we are not following any specification nor trying to copy behavior from other approaches (like the "xUnit" or "xSpec" way).
"Design Principles Behind Smalltalk" is a source of inspiration for this work. We try to follow the same principles here.
Please take a look at the Contributing section.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
![allcontributors[bot] avatar](https://avatars.githubusercontent.com/in/23186?v=4 "allcontributors[bot]")
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent