Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bearror/oletus
Minimal ECMAScript Module test runner
https://github.com/bearror/oletus
es6-modules esm esmodules javascript node tdd test-framework test-runner testing unit-testing
Last synced: 3 months ago
JSON representation
Minimal ECMAScript Module test runner
- Host: GitHub
- URL: https://github.com/bearror/oletus
- Owner: bearror
- License: mit
- Created: 2018-04-21T17:27:16.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2023-12-10T08:41:06.000Z (about 1 year ago)
- Last Synced: 2024-09-19T18:08:41.403Z (5 months ago)
- Topics: es6-modules, esm, esmodules, javascript, node, tdd, test-framework, test-runner, testing, unit-testing
- Language: JavaScript
- Homepage:
- Size: 310 KB
- Stars: 45
- Watchers: 3
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
- License: license.md
Awesome Lists containing this project
- awesome-node-esm - oletus - minimal ECMAScript Module test runner (Packages / Testing)
README
# ▶ oletus
[](https://travis-ci.com/bearror/oletus)
A zero configuration, zero dependency test runner for ECMAScript Modules—made specifically for getting started quick. Painless migration to the bigger guns if you end up needing them.
## Features
- **Native ECMAScript Modules support**.
- **Simple**: No configuration. No test timeouts. No global scope pollution. No runner hooks. No compilation step. No source maps.
- **Super fast**: Asynchronous tests run concurrently, individual modules run concurrently using multiple CPUs, no overhead from compilation.
## Usage
### Test Syntax
```js
import test from 'oletus'
// this should look pretty familiar
test('arrays are equal', t => {
t.deepEqual([1, 2], [1, 2])
})
// you can use async functions or otherwise return Promises
test('bar', async t => {
const bar = Promise.resolve('bar')
t.equal(await bar, 'bar')
})
```
### Add oletus to your project
Install it with npm:
```bash
npm install --save-dev oletus
```
Modify the `test` script in your `package.json`:
```json
{
"test": "oletus"
}
```
### Older versions of Node
On Node 12 you need to pass [`--experimental-modules`](https://nodejs.org/dist/latest-v12.x/docs/api/esm.html#esm_enabling):
```json
{
"test": "node --experimental-modules --no-warnings -- ./node_modules/.bin/oletus"
}
```
For even older Node versions, use [esm](https://github.com/standard-things/esm#esm):
```json
{
"test": "node -r esm -- ./node_modules/.bin/oletus"
}
```
### Test locations
By default, Oletus runs all files that exist in your `/test` directory.
Alternatively, you can specify a list of files to run. Note that the glob
pattern in the example below is handled by your shell, not by Oletus.
```json
{
"test": "oletus test.js src/**/*.test.js"
}
```
## Reporters
Oletus has a *concise reporter* on local runs and a *verbose reporter* on CI environments.
## API
### `test :: (String, StrictAssertModule -> Promise?) -> Promise TestResult`
The `test` function, which is the default export from Oletus, takes the following arguments:
- `title`: A String describing the test case.
- `implementation`: A function that runs your assertions. The implementation has a single parameter (`t`, for example) that gets passed the [strict node assertion](https://nodejs.org/api/assert.html#assert_strict_mode) module. If this function returns a Promise, Oletus awaits the result to know if your test
passes. Otherwise the test is assumed to pass if it doesn't throw.
The return value from `test` function is a Promise of an object with the following shape `{ didPass, title, location, message }`. Note that for most cases, you don't actually need to do anything with the returned Promise, but for reference, this is what its resolution value looks like:
- `didPass`: A boolean to indicate whether the test has passed.
- `title`: The title of the test.
- `location`: The stack trace for the failure reason, or an empty string if `didPass` was `true`.
- `message` The failure reason, or an empty string if `didPass` was `true`.
## Examples
### Code coverage
Oletus works great together with [`c8`](https://github.com/bcoe/c8). C8 is a tool for running code coverage natively using the V8 built-in code coverage functionality. The reason this pairs well with Oletus is because with Oletus, you tend to run your ESM code natively, and no other coverage tools can deal with that. Set it up like this:
```json
{
"test": "c8 oletus test.js src/**/*.test.js"
}
```
### Using Oletus for testing CommonJS modules
Your codebase doesn't need to be written as EcmaScript 6 modules to use Oletus. The only part of your code that really needs to contain es6 modules is your tests themselves. But you're free to import CommonJS modules via [CommonJS Interoperability](https://nodejs.org/dist/latest/docs/api/esm.html#esm_interoperability_with_commonjs):
```js
import test from 'oletus'
import myCJSModule from '../src/index.js'
test ('my export', t => {
t.equals (myCJSModule.myExportedAnswer, 42)
})
```
### Running tests in sequence instead of parallely
Because the `test` function returns a Promise, all you need to do is add `await`
statements in front of your tests to run them in sequence. Note that your
runtime needs to support top-level-await. Otherwise you can wrap your tests in
an async function and call it at the end of your file.
```js
await test('foo', async t => {
const foo = Promise.resolve('foo')
t.equal(await foo, 'foo')
})
await test('bar', async t => {
const bar = Promise.resolve('bar')
t.equal(await bar, 'bar')
})
```
### Completely custom test run order
Because the `test` function returns a Promise, you can manipulate the run order
of your tests in any way you see fit. For example, you could execute your tests
in batches of 2 by `await`ing `Promise.all` calls.
```js
await Promise.all([
test('first', () => {}),
test('second', () => {}),
])
await Promise.all([
test('third', () => {}),
test('fourth', () => {}),
])
```
### Setup and teardown
Because the `test` function returns a Promise, it's quite straight-forward to
wrap a test in setup and teardown logic:
```js
const testWithDatabase = async (title, implementation) => {
const database = await setupDatabase()
await test (title, t => implementation(t, database))
await teardownDatabase()
}
testWithDatabase ('has users', async (t, database) => {
const users = await database.queryUsers()
t.equals (users, [{ name: 'bob' }])
})
```
### Programmatic use
Besides the CLI, there's also an interface for programmatic use:
```js
import run from 'oletus/runner.mjs'
import concise from 'oletus/report-concise.mjs'
const { passed, failed, crashed } = await run(['test/index.js'], concise)
console.log (
'%s tests passed, %s tests failed, and %s files crashed',
passed, failed, crashed
)
```