Skip to content
Gerbil: Inquisitive, friendly animals that rarely bite, TDD for the rest of us
Find file
Pull request Compare This branch is 2 commits ahead, 31 commits behind master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



n. Gerbils: Inquisitive, friendly animals that rarely bite, TDD for the rest of us

Gerbil attemps to be an uber simple and minimalistic testing framework for javascript.

Now with npm

$ npm install gerbil

You can now execute the tests with node without to depend on the browser

var scenario = require('gerbil').scenario;

scenario("Testing with node", {
  "should work in a terminal": function(g){

// Or if you want to access some global Gerbil stuff

var Gerbil = require('gerbil');
var scenario = Gerbil.scenario;

Console Errors

Console Errors


// Name the scenario you want to test and pass an object with your tests.
scenario("Some usefull stuff that needs to work", {
  // Reserved names are 'setup', 'before', 'after' and 'cleanup'. They define
  // the steps to be executed.
  // Every test gets one parameter, this is the test suite itself.
  // Modifying 'this' will affect the context in the tests, it's useful when
  // using 'setup' to initialize some state.
  'setup': function(g) {
    this.validName = 'Gerbil';
  // Within the test 'this' gets the config defined in 'setup'
  'should get the correct name': function(g) {
    g.assertEqual(this.validName, 'Gerbil');

  // Test in the feature, usefull to test future events or timers.
  'in the future': function(g) {
    this.time = new Date().getTime();

    g.setTimeout(function() {
      g.assert(new Date().getTime() > this.time);
    }, 1000);

  // Test async code.
  // Using the async function you can control the status of the test. This is
  // really usefull when you are testing callbacks.
  // But remember, it's your responsability to end() the test.
  'should be able to test asyncronous code': function(g) {
    var asyncStuff = function() {
      this.callback = null;

    asyncStuff.prototype = {
      eventually: function(fn) {
        this.callback = fn;

      exec: function() {
        setTimeout(function(c) {
        }, 500, this);

    g.async(function() {
      var async = new asyncStuff;
      async.eventually(function() {
        // end() will end the current scenario and trigger a summary



scenario("This is my scenario", {
  "setup":  function() {
    // When scenario starts
    this.someThing = new Thing;
  "before": function() {
    // Before every test
  "after":  function() {
    // After every test
  "cleanup": function() {
    // When the scenario ends
    this.someThing = false;

  "MagicThing should have a length": function(g) {
    g.assertEqual(this.someThing.length, 1);

  "MagicThing should be valid": function(g) {

Custom logger

var myCoolLogger = {
  // Summary and pending tests.
  "warn":   function(msg){},
  // When good things happend.
  "log":    function(msg){},
  // The header of the test.
  "info":   function(msg){},
  // When bad things happend
  "error":  function(msg){

scenario("Fancy scenario", {
  "somewhere over the rainbow": function(g) {
}, myCoolLogger);

// Or if you want to affect every gerbil scenario

Gerbil.logger = myCoolLogger;

What's the catch?

The results are only shown in the console, the one from console.log if you use it in a browser. Run it with an open inspector or define a custom logger if you want prettier results. And in the bottom you will find the summary

Browser tests


  1. Get a gerbil as a pet


Something went wrong with that request. Please try again.