{%= name %} [![npm version][npmv-img]][npmv-url] ![License][license-img]

{%= description %}

Please consider following this project's author, Charlike Mike Reagent, and ⭐ the project to show your ❤️ and support.

If you have any how-to kind of questions, please read the Contributing Guide and Code of Conduct documents.
For bugs reports and feature requests, please create an issue or ping @tunnckoCore at Twitter.

[![NPM Downloads Weekly][downloads-weekly-img]][npmv-url] [![NPM Downloads Monthly][downloads-monthly-img]][npmv-url] [![NPM Downloads Total][downloads-total-img]][npmv-url]

Project is semantically & automatically released on CircleCI with [new-release][] and its New Release GitHub App.

Highlights

Runs tests in series or parallel, concurrently
Fast and future-proof design, tiny footprint
Secure environment, no implicit globals
TAP Specification compliant output reporting
Simple test syntax and enforce writing atomic tests
Clean stacktraces, when optionally shown
Works inside any CommonJS environment and the Browser
Support writing your tests in latest JavaScript syntax
Support async/await functions, Promises and Observables
Assertion agnostic, works with assert and Jest's expect
Works well with nyc for test coverage reporting
Well documented, well tested and small & quality code base

Installation requirements

This project requires Node.js {%= engines.node %} or compatible browser. Install it using yarn or npm.
We highly recommend to use Yarn when you think to contribute to this project.

$ yarn add --dev {%= name %}

CLI Usage

Eventhough we currently don't have CLI we still can control a small bits. There are two variants, through environment variables and command line flags.

Passing flags

We can pass flags directly to the node executable, because they are not conflicting whit it.

--serial

Allows running the tests in series.

node test/index.js --serial

--showStack

Shows the stack traces, because by default we don't show them in the TAP output.

node test/index.js --showStack

--reporter / -R

Currently there 2 available reporters: "tap" (default) and "mini". The name should match the name of the file in src/reporters/ folder.

node -r esm test/index.js -R mini

--relativePaths

When stack traces are shown (e.g. when --showStack) then paths will be relative to the cwd. Defaults to true.

node -r esm test/index.js --relativePaths
# disable
node -r esm test/index.js --no-relativePaths

Environment variables

Note: This works only when there is process.env in the environment!

ASIA_SHOW_STACK

If you want the stacktraces to be shown on the TAP output, then pass ASIA_SHOW_STACK=1

ASIA_SHOW_STACK=1 node test/index.js

ASIA_SERIAL

Note: This works only when there is process.env in the environment!

If you want tests to be running in series (in order), then pass ASIA_SERIAL=1

ASIA_SERIAL=1 node test/index.js

Transpilation and ES Modules

By default, tests are working in CommonJS. But if you want to write with modern and latest JavaScript features, then you may need Babel or the [esm][] loader. In this case you can pass a @babel/register or the esm hook to the Node.js or

node -r esm test/index.js
# Babel
node -r @babel/register test/index.js

Test coverage

In case you want to have test coverage, Asia works great with the [nyc][]/Istanbul.

nyc --reporter lcov --reporter text node test/index.js

When you want transpilation and still working test coverage, then you need to pass the require hooks to the nyc instead to the node binary.

nyc --require esm node test/index.js
nyc --require @babel/register node test/index.js

Incremental testing ("watch mode")

For more faster feedback loop, you may want to use [nodemon][].

The following runs tests on every file change in src/ and test/ folders

nodemon --exec 'node -r esm test/index.js' '{src,test}/**/*.js'

Testing with multiple files

Because currently we don't have CLI, easy workaround to run multiple files is to have one test/index.js which imports the other test file.

For example, if you have the following test/foo.js and test/bar.js

test/foo.js

import assert from 'assert';
import test from 'asia';

test('some foo test', () => {});

test.skip('skip tests never run', () => {
  console.log('hoho');
});

test('foo second', () => {
  assert.strictEqual(1, 2);
});

test/bar.js

import expect from 'expect';
import test from 'asia';

test('ok yeah', () => {
  expect(1).toBe(1);
});

test.todo('some todo test');

test('one two three', async () => {
  const val = await Promise.resolve({ a: 'b' });
  expect(val).toBe(1234); // throws
});

Then you just need to import all the test files one main (e.g. test/index.js or test.js) file.

import './foo';
import './bar';

Run it with node -r esm test/index.js and so, it will output (correctly), the following

TAP version 13
ok 2 - # SKIP skip tests never run
not ok 5 - # TODO some todo test
ok 1 - some foo test
not ok 3 - foo second
# FAIL!
#
# At: _659‍.r.test (./example/foo.js:11:10)
#
# Message: Input A expected to strictly equal input B:
# + expected - actual
#
# - 1
# + 2
#
ok 4 - ok yeah
not ok 6 - one two three
# FAIL!
#
# At: _42f‍.r.test (./example/bar.js:12:15)
#
# Message: expect(received).toBe(expected) // Object.is equality
#
# Expected: 1234
# Received: {"a": "b"}
#
# Difference:
#
#   Comparing two different types of values. Expected number but received object.
#
1..6
# tests 6
# pass 2
# skip 1
# todo 1
# fail 2
#

Regular use

$ yarn add --dev {%= name %}

Server Side

If you want to use it in your tests, just do the following

Using ES Modules:

import expect from 'expect'
import test from 'asia';

test('my awesome test title', () => {
  expect(typeof test).toBe('function');
});

Using inside CommonJS environment (e.g. Node.js):

const assert = require('assert');
const test = require('asia');

test('some test in commonjs', () => {
  assert.strictEqual(typeof test, 'function');
  assert.strictEqual(typeof test.skip, 'function');
  assert.strictEqual(typeof test.todo, 'function');
});

In the Browser

Using type="module"

<script type="module">
  import test from 'https://unpkg.com/asia?module';

  test('foo bar', () => {
    console.log('my browser tests');
  });
</script>

Using the UMD bundle

<script src="https://unpkg.com/asia/dist/index.js"></script>
<script type="text/javascript">
  const test = window.test;
  test('my awesome test', () => {});
</script>

Using the API

$ yarn add {%= name %}

If you want to create something on top of it, e.g. CLI for example, then you cannot use the default export import 'asia', because it exposes the test() method and runs the tests, automatically.

Server Side

Using ES Modules:

import Asia from 'asia/dist/api/es';

Using inside CommonJS environment (e.g. Node.js):

const Asia = require('asia/dist/api/umd');

In the browsers

Using type="module"

<script type="module">
  import Asia from 'https://unpkg.com/asia/dist/api/es.js';
</script>

Using the UMD bundle

<script src="https://unpkg.com/asia/dist/api/umd.js"></script>
<script type="text/javascript">
  const Asia = window.Asia;
</script>

API

Generated using docks.

src/api.js

Asia

Constructor which can be initialized with optional options object. On the .test method you can access the skip and todo methods. For example .test.skip(title, fn) and .test.todo(title).

This should be uses if you want to base something on top of the Asia API. By default, the main export e.g. just 'asia' exposes a default export function, which is the test() method.

Params

options {object} control tests concurrency or pass serial: true to run serially.

Returns

object instance with .test, .skip, .todo and .run methods

Examples

import Asia from 'asia/dist/api/es';

// or in CommonJS (Node.js)
// const Asia = require('asia/dist/api/umd');

const api = Asia({ serial: true });
console.log(api);
// => { test() {}, skip() {}, todo() {}, run() {} }

api.test('awesome test', async () => {
  await Promise.resolve(123);
});

api.test.skip('some skip test here', () => {
  console.log('this will not log');
});
api.skip('same as above', () => {
  console.log('this will not log');
});

api.test.todo('test without implementaton');
api.todo('test without implementaton');

api.run();

test

Define a regular test with title and fn. Both title and fn params are required, otherwise it will throw. Optionally you can pass settings options object, to make it a "skip" or a "todo" test. For example { skip: true }

Params

title {string}
fn {function}
settings {object}

Examples

import assert from 'assert';
import expect from 'expect';
import test from 'asia';

test('some awesome failing test', () => {
  expect(1).toBe(2);
});

test('foo passing async test', async () => {
  const res = await Promise.resolve(123);

  assert.strictEqual(res, 123);
});

test.skip

Define test with title and fn that will never run, but will be shown in the output.

Params

title {string} test title
fn {function} test function implementaton

Examples

import test from 'asia';

test.skip('should be skipped, but printed', () => {
  throw Error('test function never run');
});

test.skip('should throw, because expect test implementation');

test.todo

Define a test with title that will be marked as "todo" test. Such tests do not have test implementaton function, if fn is given than it will throw an error.

Params

title {string} title of the "todo" test
fn {function} do not pass test implementaton function

Examples

import assert from 'assert';
import test from 'asia';

test.todo('should be printed and okey');

test.todo('should throw, because does not expect test fn', () => {
  assert.ok(true);
});

.run

Run all tests, with optional settings options, merged with those passed from the constructor. Currently the supported options are serial and concurrency.

Params

settings {object} for example, pass serial: true to run the tests serially

Returns

Promise

Examples

import delay from 'delay';
import Asia from 'asia/dist/api/es';

const api = Asia({ serial: true });

api.test('first test', async () => {
  await delay(1000);
  console.log('one');
});

api.test('second test', () => {
  console.log('two');
});

api.run({ concurrency: 10 });

back to top

{% if (verb.related && verb.related.list && verb.related.list.length) { %}

Contributing

Follow the Guidelines

Please read the Contributing Guide and Code of Conduct documents for advices.
For bugs reports and feature requests, please create an issue or ping @tunnckoCore at Twitter.

Support the project

Become a Partner or Sponsor? 💵 Check the Partner, Sponsor or Omega-level tiers! 🎉 You can get your company logo, link & name on this file. It's also rendered on package page in [npmjs.com][npmv-url] and [yarnpkg.com](https://yarnpkg.com/en/package/{%= name %}) sites too! 🚀

Not financial support? Okey! Pull requests, stars and all kind of contributions are always welcome. ✨

OPEN Open Source

This project is following OPEN Open Source model

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is built on collective efforts and it's not strongly guarded by its founders.

There are a few basic ground-rules for its contributors

Any significant modifications must be subject to a pull request to get feedback from other contributors.
Pull requests to get feedback are encouraged for any other trivial contributions, but are not required.
Contributors should attempt to adhere to the prevailing code-style and development workflow.

Wonderful Contributors

Thanks to the hard work of these wonderful people this project is alive! It follows the all-contributors specification.
Don't hesitate to add yourself to that list if you have made any contribution! ;) See how, here.

_{Charlike Mike Reagent} 💻 📖 💬 👀 🔍

Consider showing your support to them. 💖

License

Copyright (c) 2016-present, Charlike Mike Reagent <mameto2011@gmail.com> & contributors.
Released under the Apache-2.0 License.

[npmv-url]: https://www.npmjs.com/package/{%= name %} [npmv-img]: https://badgen.net/npm/v/{%= name %}?icon=npm

[license-img]: https://badgen.net/npm/license/{%= name %}

[downloads-weekly-img]: https://badgen.net/npm/dw/{%= name %} [downloads-monthly-img]: https://badgen.net/npm/dm/{%= name %} [downloads-total-img]: https://badgen.net/npm/dt/{%= name %}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

.verb.md

.verb.md

{%= name %} [![npm version][npmv-img]][npmv-url] ![License][license-img]

Highlights

Table of Contents

Installation requirements

CLI Usage

Passing flags

Environment variables

Transpilation and ES Modules

Test coverage

Incremental testing ("watch mode")

Testing with multiple files

Regular use

Server Side

In the Browser

Using the API

Server Side

In the browsers

API

src/api.js

Asia

test

test.skip

test.todo

.run

See Also

Contributing

Follow the Guidelines

Support the project

OPEN Open Source

Wonderful Contributors

License

Files

.verb.md

Latest commit

History

.verb.md

File metadata and controls

{%= name %} [![npm version][npmv-img]][npmv-url] ![License][license-img]

Highlights

Table of Contents

Installation requirements

CLI Usage

Passing flags

Environment variables

Transpilation and ES Modules

Test coverage

Incremental testing ("watch mode")

Testing with multiple files

Regular use

Server Side

In the Browser

Using the API

Server Side

In the browsers

API

src/api.js

Asia

test

test.skip

test.todo

.run

See Also

Contributing

Follow the Guidelines

Support the project

OPEN Open Source

Wonderful Contributors

License