{"id":13728009,"url":"https://github.com/bearror/oletus","last_synced_at":"2026-01-12T02:38:02.188Z","repository":{"id":31885489,"uuid":"130496615","full_name":"bearror/oletus","owner":"bearror","description":"Minimal ECMAScript Module test runner","archived":false,"fork":false,"pushed_at":"2023-12-10T08:41:06.000Z","size":317,"stargazers_count":45,"open_issues_count":1,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-09-19T18:08:41.403Z","etag":null,"topics":["es6-modules","esm","esmodules","javascript","node","tdd","test-framework","test-runner","testing","unit-testing"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bearror.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-21T17:27:16.000Z","updated_at":"2024-02-05T11:01:02.000Z","dependencies_parsed_at":"2024-06-18T21:26:09.390Z","dependency_job_id":"5099aeef-c0a7-4007-bae9-f6e5b90e67f1","html_url":"https://github.com/bearror/oletus","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bearror%2Foletus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bearror%2Foletus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bearror%2Foletus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bearror%2Foletus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bearror","download_url":"https://codeload.github.com/bearror/oletus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224679802,"owners_count":17351871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["es6-modules","esm","esmodules","javascript","node","tdd","test-framework","test-runner","testing","unit-testing"],"created_at":"2024-08-03T02:00:36.134Z","updated_at":"2026-01-12T02:38:02.159Z","avatar_url":"https://github.com/bearror.png","language":"JavaScript","readme":"# ▶ oletus\n\n[![Build Status](https://travis-ci.com/bearror/oletus.svg?branch=master)](https://travis-ci.com/bearror/oletus)\n\nA 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.\n\n## Features\n\n- **Native ECMAScript Modules support**.\n- **Simple**: No configuration. No test timeouts. No global scope pollution. No runner hooks. No compilation step. No source maps.\n- **Super fast**: Asynchronous tests run concurrently, individual modules run concurrently using multiple CPUs, no overhead from compilation.\n\n## Usage\n\n### Test Syntax\n\n```js\nimport test from 'oletus'\n\n// this should look pretty familiar\ntest('arrays are equal', t =\u003e {\n  t.deepEqual([1, 2], [1, 2])\n})\n\n// you can use async functions or otherwise return Promises\ntest('bar', async t =\u003e {\n  const bar = Promise.resolve('bar')\n  t.equal(await bar, 'bar')\n})\n```\n\n### Add oletus to your project\n\nInstall it with npm:\n\n```bash\nnpm install --save-dev oletus\n```\n\nModify the `test` script in your `package.json`:\n\n```json\n{\n  \"test\": \"oletus\"\n}\n```\n\n### Older versions of Node\n\nOn Node 12 you need to pass [`--experimental-modules`](https://nodejs.org/dist/latest-v12.x/docs/api/esm.html#esm_enabling):\n\n```json\n{\n  \"test\": \"node --experimental-modules --no-warnings -- ./node_modules/.bin/oletus\"\n}\n```\n\nFor even older Node versions, use [esm](https://github.com/standard-things/esm#esm):\n\n```json\n{\n  \"test\": \"node -r esm -- ./node_modules/.bin/oletus\"\n}\n```\n\n### Test locations\n\nBy default, Oletus runs all files that exist in your `/test` directory.\nAlternatively, you can specify a list of files to run. Note that the glob\npattern in the example below is handled by your shell, not by Oletus.\n\n```json\n{\n  \"test\": \"oletus test.js src/**/*.test.js\"\n}\n```\n\n## Reporters\n\nOletus has a *concise reporter* on local runs and a *verbose reporter* on CI environments.\n\n\u003cimg src=\"./oletus-reporters.png\"\u003e\n\n## API\n\n### `test :: (String, StrictAssertModule -\u003e Promise?) -\u003e Promise TestResult`\n\nThe `test` function, which is the default export from Oletus, takes the following arguments:\n\n- `title`: A String describing the test case.\n- `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\npasses. Otherwise the test is assumed to pass if it doesn't throw.\n\nThe 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:\n\n- `didPass`: A boolean to indicate whether the test has passed.\n- `title`: The title of the test.\n- `location`: The stack trace for the failure reason, or an empty string if `didPass` was `true`.\n- `message` The failure reason, or an empty string if `didPass` was `true`.\n\n## Examples\n\n### Code coverage\n\nOletus 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:\n\n```json\n{\n  \"test\": \"c8 oletus test.js src/**/*.test.js\"\n}\n```\n\n### Using Oletus for testing CommonJS modules\n\nYour 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):\n\n```js\nimport test from 'oletus'\nimport myCJSModule from '../src/index.js'\n\ntest ('my export', t =\u003e {\n  t.equals (myCJSModule.myExportedAnswer, 42)\n})\n```\n\n### Running tests in sequence instead of parallely\n\nBecause the `test` function returns a Promise, all you need to do is add `await`\nstatements in front of your tests to run them in sequence. Note that your\nruntime needs to support top-level-await. Otherwise you can wrap your tests in\nan async function and call it at the end of your file.\n\n```js\nawait test('foo', async t =\u003e {\n  const foo = Promise.resolve('foo')\n  t.equal(await foo, 'foo')\n})\n\nawait test('bar', async t =\u003e {\n  const bar = Promise.resolve('bar')\n  t.equal(await bar, 'bar')\n})\n```\n\n### Completely custom test run order\n\nBecause the `test` function returns a Promise, you can manipulate the run order\nof your tests in any way you see fit. For example, you could execute your tests\nin batches of 2 by `await`ing `Promise.all` calls.\n\n```js\nawait Promise.all([\n  test('first', () =\u003e {}),\n  test('second', () =\u003e {}),\n])\n\nawait Promise.all([\n  test('third', () =\u003e {}),\n  test('fourth', () =\u003e {}),\n])\n```\n\n### Setup and teardown\n\nBecause the `test` function returns a Promise, it's quite straight-forward to\nwrap a test in setup and teardown logic:\n\n```js\nconst testWithDatabase = async (title, implementation) =\u003e {\n  const database = await setupDatabase()\n  await test (title, t =\u003e implementation(t, database))\n  await teardownDatabase()\n}\n\ntestWithDatabase ('has users', async (t, database) =\u003e {\n  const users = await database.queryUsers()\n  t.equals (users, [{ name: 'bob' }])\n})\n```\n\n### Programmatic use\n\nBesides the CLI, there's also an interface for programmatic use:\n\n```js\nimport run from 'oletus/runner.mjs'\nimport concise from 'oletus/report-concise.mjs'\n\nconst { passed, failed, crashed } = await run(['test/index.js'], concise)\n\nconsole.log (\n  '%s tests passed, %s tests failed, and %s files crashed',\n  passed, failed, crashed\n)\n```\n","funding_links":[],"categories":["Packages"],"sub_categories":["Testing"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbearror%2Foletus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbearror%2Foletus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbearror%2Foletus/lists"}