actuator v0.0.2

Actuator

Actuator is a tiny wrapper around a mock hubot adapter that makes it easier to write unit tests for Hubot scripts.

Note: This project is in early development, and versioning is a little different. Read this for more details.

Installation

$ npm install actuator --save-dev

Usage example:

{expect} = require 'chai'

hubot = require 'actuator'

beforeEach (done) ->
  hubot.initiate(script: './lib/hubot_script.coffee', done)

afterEach ->
  hubot.terminate()

describe 'test hubot script', ->

  it 'should have 3 help commands', (done) ->
    expect(hubot.robot.helpCommands()).to.have.length(3)
    done()

  it 'should parse help', (done) ->
    hubot.on('hubot help')
      .spread (response) ->
        expect(response).to.equal """
        hubot actuator - actuator is awesome.
        hubot help - Displays all of the help commands that hubot knows about.
        hubot help <query> - Displays all help commands that match <query>.
        """
      .done(done.bind(@, null), done)

  it 'should respond to messages', (done) ->
    hubot.on('hubot actuator')
      .spread (response) ->
        expect(response).to.equal 'actuator is awesome'
      .done(done.bind(@, null), done)

API Usage

actuator.initiate(settings, done)

This starts up a Hubot instance to run all your tests against. It is required for this module to work, and belongs in your test runner's beforeEach hook. It is asynchronous, and requires done to be passed to it from beforeEach. settings is a JavaScript object with only one property at the moment: script. settings.script is essentially just the path to the script that you want to test.

e.g.

beforeEach (done) ->
  actuator.initiate(script: './lib/your_hubot_script.coffee', done)

actuator.terminate()

This shuts down the Hubot instance and it's webserver. Calling this in your test runner's afterEach hook is necessary in order to prevent any weird errors (like the ports Hubot runs on being regarded as in use).

e.g.

afterEach ->
  actuator.terminate()

actuator.robot

This is a direct reference to the Hubot instance itself. Any properties you might need to reference from Hubot can be found here.

e.g.

it 'should have 3 help commands', (done) ->
  expect(actuator.robot.helpCommands()).to.have.length(3)
  done()

actuator.on(command)

This is where the magic happens. This method is used to listen for Hubot commands and assert their response. command is a string for the command Hubot should be listening for.

This method is asynchronous and returns a promise for Hubot's response to the command. The responses thenable is an array of all the msg.send calls in Hubot's handler for that command.

For example, if your Hubot script listens for "hubot greet me twice", like so:

module.exports = (robot) ->
  robot.respond /greet me twice/i, (msg) ->
    msg.send("Hi there.")
    msg.send("Wassup!?")

...then this is what your test would look like:

it 'responds with two greetings', (done) ->
  actuator.on('hubot greet me twice')
    .then (responses) ->
      expect(responses[0]).to.equal "Hi there."
      expect(responses[1]).to.equal "Wassup!?"
    .then -> done()
    .catch done

Since this returns a when.js promise (which has some excellent documentation), we can actually make the above test simpler like so:

it 'responds with two greetings', (done) ->
  actuator.on('hubot greet me twice')
    .spread (first_greeting, second_greeting) ->
      expect(first_greeting).to.equal "Hi there."
      expect(second_greeting).to.equal "Wassup!?"
    .done(done.bind(@, null), done)