Helpers for unit testing

Unit.js provide several helpers methods. Helpers do not make assertions.

See also API doc (helpers).

Expressions

case()

See also case() in the API doc.

case() is useful for wrapping a test case.

If one (or several) function is passed, it is called.

test
  .case('A description of your test case', function(){

    // your test case
  })

  .case('A description of your test case')
    .string('Hello world')
      .startsWith('Hello')
      .endsWith('world')

  .case(function(){

    // your test case
  })
;

given()

See also given() in the API doc.

The precondition or setup for a test or set of tests.

The given part describes the state of the world before you begin the behavior you're specifying in this scenario. You can think of it as the pre-conditions to the test.

Technically given() is an alias of case().

If one (or several) function is passed, it is called.

var name;

test
  .given(name = 'foo')
    .string(name)
      .isEqualTo('foo')

  .given(name = 'bar')
    .string(name)
      .isEqualTo('bar')
;

when()

See also when() in the API doc.

Events whose effect you’re testing/specifying.

The when section is that behavior that you're specifying.

Technically when() is an alias of case().

If one (or several) function is passed, it is called.

test
  .when(function(){
    test.string('foo').match(/oo/);
  })

  .when('Test the famous 42', function(){
    test.number(42).isBetween(41, 43);
  })
;

then()

See also then() in the API doc.

The then section describes the changes you expect due to the specified behavior. This is where the test determines if the result of the Given and When sections meets what was expected in the test.

Also you can use to make a sequel.

Technically given() is an alias of case().

If one (or several) function is passed, it is called.

test
  .then('A description')
    .number(42)
      .isBetween(41, 43)

  // or another structuration
  .then('A description', function(){
    test.number(42).isBetween(41, 43);
  })
;

if()

See also if() in the API doc.

if() does nothing, is just pass-through method for an expressive and fluent chain. Does not execute the functions that are passed as a parameter.

var name;

test
  .if(name = 'foo')
    .string(name)
      .isEqualTo('foo')

  .if(name = 'bar')
    .string(name)
      .isEqualTo('bar')
;

and()

See also and() in the API doc.

and() does nothing, is just pass-through method for an expressive and fluent chain. Does not execute the functions that are passed as a parameter.

Technically and() is an alias of if().

var num;
var multiply;

test
  .if(num = 1)
  .and(multiply = 2)
  .and(num = (num * multiply))
    .number(num)
      .is(2)

  .if(num = 5)
  .and(multiply = 3)

  .when(num = (num * multiply))

  .then(function(){
    test.number(num).is(15);
  })
;

Utilities

wait()

See also wait() in the API doc.

Execute the given function after a specified number of milliseconds.

test
  .string('any assertion')

  .wait(100, function() {
    // ...
  })
  .then(/* continue... */)
;

dump()

See also dump() in the API doc.

Dump the arguments and display in the console.

If no argument is passed, the actual tested value is dumped.

test
  .string('foo')

  // dump the actual value tested ('foo')
  .dump()

  // dump an argument
  .dump({myKey: 'my value'})

  // dump several arguments
  .dump({myKey: 'my value'}, 'foo', new Date())
;

fail()

See also fail() in the API doc.

Fails a test.

Quickly, with a default message:

test.fail();

With message:

test.fail('An error message');

With message and expected value:

test.fail('An error message', 'expected value');

With message, expected value and actual tested value:

test.fail('An error message', 'expected value', 'actual value');

With message, expected value, actual tested value and one or more value to dump():

test.fail('An error message', 'expected value', 'actual value', error);

With actual tested value (without custom message):

test.value('actual value').fail();

With actual tested value and a custom message:

test.value('actual value').fail('An error message');

With message, expected value and actual tested value:

test.value('actual value').fail('An error message', 'expected value');

stats

See also stats in the API doc.

Stats of assertions.

All stats:

console.log(test.stats);

PROTIP: It's more readable with test.dump():

test.dump(test.stats);

All assertions:

test.dump(test.stats.assertions);

Specific assertion:

test.dump(
  test.stats.assertions.isObject,
  test.stats.assertions.isString,
);

Total number of assertions:

test.dump(test.stats.total.assertions);