asia

Blazingly fast, magical and minimalist testing framework for Today and Tomorrow

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.

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

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

(TOC generated by verb using markdown-toc)

Installation requirements

This project requires Node.js ^8.10.0 || >=10.13.0 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 asia

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 asia

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 asia

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

See Also

Some of these projects are used here or were inspiration for this one, others are just related. So, thanks for your existance!

• @tunnckocore/create-project: Create and scaffold a new project, its GitHub repository and… more | homepage
• @tunnckocore/scripts: Universal and minimalist scripts & tasks runner. | homepage
• asia: Blazingly fast, magical and minimalist testing framework, for Today and… more | homepage
• charlike: Small, fast and streaming project scaffolder with support for hundreds… more | homepage
• docks: Extensible system for parsing and generating documentation. It just freaking… more | homepage
• git-commits-since: Get all commits since given period of time or by… more | homepage
• gitcommit: Lightweight and joyful git commit replacement. Conventional Commits compliant. | homepage
• recommended-bump: Calculates recommended bump (next semver version) based on given array… more | homepage

back to top

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 and yarnpkg.com 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

1. Any significant modifications must be subject to a pull request to get feedback from other contributors.
2. Pull requests to get feedback are encouraged for any other trivial contributions, but are not required.
3. 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 <[email protected]> & contributors.
Released under the Apache-2.0 License.