npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

oletus

v4.0.0

Published

Minimal ECMAScript Module test runner

Downloads

136

Readme

▶ oletus

Build Status

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

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:

npm install --save-dev oletus

Modify the test script in your package.json:

{
  "test": "oletus"
}

Older versions of Node

On Node 12 you need to pass --experimental-modules:

{
  "test": "node --experimental-modules --no-warnings -- ./node_modules/.bin/oletus"
}

For even older Node versions, use esm:

{
  "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.

{
  "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 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. 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:

{
  "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:

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.

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 awaiting Promise.all calls.

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:

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:

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
)