✅ pico-check

An incredibly tiny javascript testing library. Heavily inspired by the wonderful ava and tape.

Features

• Supports sync and async tests
• Provides utils for arming/disarming tests and timeouts for async tests
• Test cases structured as simple objects and functions
• Easily flag a test or group to skip, run-only, or always-run
• Can be used as a CLI tool, a library, or even client-side
• Cleans up error stack traces and populates the Error.cause with useful info
• No dependencies!
• ~150 lines!

Test Syntax

// Tests are just functions or objects of functions. If the test passes,
// the function returns nothing, if the test fails the function should throw an error.

const check = require('pico-check');

//Test Cases are just nested objects of test functions
const testCases = {
  'testing addition' : function(){
    this.eq(3 + 4, 7);
  },
  'async tests' : {
    'promise check' : (t)=>{
      return request(api_url)
        .then((result)=>{
          t.eq(result, {code : 200, body : { ok : true }});
        });
    },
    'async/await' :  async (t)=>{
      const bar = Promise.resolve('bar');
      t.eq(await bar, 'bar');
    }
  },
  '_skipped test' : (t)=>t.fail()
};

const {results, skipped, passed, failed, time} = await check(testCases);

console.log(results);

/* Returns the exact same object structure but true if pass, error if fail, and null if skipped
{
  'testing addition': true,
  'async tests': {
    'promise check': AssertionError [ERR_ASSERTION]: Expected values to be loosely deep-equal:
      { code: 404 } should loosely deep-equal { code: 200, body : { ok : true }},
    'async/await': true
  },
  '_skipped test': null
}
*/

Usage

install

$ npm install --save-dev pico-check

Or just copy and paste picocheck.js into your project or webpage.

Library Usage

const check = require('pico-check');

const testCases = {
  init$ : (t)=>{
    //This test always runs, even with the only flag
    // Great for setup and tear-down tasks
  },
  this_is_a_group : {
    addition_test : (t)=>t.eq(3+4, 7),
    $only_test : (t)=>{
      //this test is flagged with a $, so pico-check will skip every other test not marked with '$'
    },
    _skipped_group : {
      sad_test : (t)=>{}
    }
  },
  _skipped_test : (t)=>{
    // this test is flagged with '_' so it will always be skipped
    t.fail('I would have failed!')
  },
  also_skipped : (t)=>{
    t.skip(); //You can also manually skip within a test, just in case
  }
}


check(testCases)
  .then(({failed, skipped, results})=>{
    console.log(results);
    process.exit(failed === 0 ? 0 : 1);
  })

Nested Tests

You can nest test suites in two ways:

1. You can compose the test objects together and call picocheck once
2. Create a test function that runs another picocheck test suite within it

const check = require('pico-check');

const other_tests = { testB : ()=>{} }

check({
  testA:()=>{},
  ...other_tests
});


check({
  nested_suite : async (t)=>{

    const {failed, results} = await check({
      testN : ()=>{}
    });
    t.ok(failed==0, 'Nested Test Suite Failed', results);
  }
})

Flags

You can flag tests and groups with _ and $ in the test name to change the test runner behaviour.

Skip Flag - _test_name

If a test or group name starts with a _ the test/group will be skipped

Only Flag - $test_name

If a test or group name starts with a $ the test runner will be set into "only mode", and will only run tests/groups with the Only Flag or the Always Flag.

Always Flag - test_name$

If a test or group ends with a $ then this test will always run unless the test or group has been explicitly set to skip. This is useful for test cases that set up or clean up needed processes for other test cases (such as database connections or setting environment variables).

Assertion

Each test function will be provided an assertion object as it's first parameter.

t.pass() / t.fail([msg], [cause]) / t.skip()

Passes/fails/skips a test case with an optional message

(t)=>{
  (complexCondition ? t.pass() : t.fail('The complex condition failed'))
};

t.eq(expected, actual, [msg]) / t.not(expected, actual, [msg])

Will do a deep comparison between the actual and the expected. Will populate the Error.cause with an object mapping the differences between the two values.

(t)=>{
  t.not(3 + 4, 8);
  t.eq({a : 6, b : [1,2,3]}, {a:6, b:[1,2,3]});
};

t.ok(value, [msg], [cause]) / t.no(value, [msg], [cause])

Checks if value is truthy or falsey

(t)=>{
  t.ok(3 + 4 == 7, 'Math is broken');
  t.no(3 + 4 == 8, 'Math is broken');
};

t.type(type, value, [msg], [cause])

Compares the type of the value to the given type. Handles arrays as type 'array' and errors as type 'error';

(t)=>{
  t.type('number', 3);
  t.type('object', {a:true});
  t.type('array', [1,2,3]);
  t.type('error', new Error('oops'));
};

t.flop = [anything]

If t.flop is not false-y when the test finishes, then it will fail as t.flop as the Error message. This is used to set the test into a "fail mode", and the test needs a condition to be met to set t.flop = false in order to pass.

(t)=>{
  t.flop = 'Never Received Ping from DB';
  db.on('pong', ()=>t.flop=false);
  db.ping();
  return t.wait(); //returning t.wait() tells pico-check that let's pico-check know
};

t.wait(time=[t.timeout+10])

async function that waits time milliseconds then resolves. Defaults to wait just slightly longer than the timeout.

async (t)=>{
  const val = threadedUpdate(); /* some threaded process */
  await t.wait(500); //Wait to give some time
  t.ok(val);
};

t.timeout = 2000

Modify the default timeout on a test-by-test basis.

async (t)=>{
  t.timeout = 8000; //8 seconds
  await a_longer_process();
  t.pass();
};