Purobu

Black-box integration test framework for components on the Heroku platform.

Installation

Install the gem

$ gem install purobu

Usage

Tests go through four phases:

  • Setup the context for the test by creating test fixtures that are required for the System Under Test (SUT) to expose the desired behavior.
  • Exercise the SUT
  • Verify the result to determine if the intended behavior was met.
  • Teardown the state of the system by removing all fixtures and test artifacts so that there are no state spills or interdependencies across tests.

Purobu recognizes and embraces this by defining these phases in implicit blocks within your tests.

For example:

# test_can_create_crane_database.rb
test 'can create crane database' do
  setup do
    heroku "apps:create --name some-app"
  end

  exercise do
    heroku "addons:add heroku-postgresql:crane some-app"
  end

  verify do
    addons = heroku "addons --app some-app"
    addons.include?("heroku-postgresql:crane") #return true or false
  end

  teardown do
    heroku "apps:remove some-app"
  end
end

Then run it with 4 concurrent jobs:

$ purobu -j 4

Purobu will load any files that match /test_.*\.rb/ recursively. An alternative is to specify files to run:

$ purobu -j 4 -f test_one.rb,test_two.rb

For more command line switches, try purobu -h

Global setup

It can be useful to have global setups, for example, to create an app to run a bunch of tests against.

You can create a ruby file called purobu_config.rb to set up a global context. The global context will run once before the entire suite. Be sure to create a global teardown as well:

# purobu_config.rb
Purobu::Configuration.run do |config|
  config.global_setup do
    heroku "apps:create harolds-test-app"
  end
  config.global_teardown do
    heroku "apps:destroy harolds-test-app --confirm harolds-test-app"
  end
end

Interacting with heroku

Access to heroku is facilitated in two ways:

  1. The heroku helper is a wrapper around the latest version of the heroku CLI. You give it a string, and it shells out to execute the given command. For example:
heroku "addons:add heroku-postgresql:dev"
  1. The heroku_api helper exposes the heroku api client for more convenient retreival of information on heroku such as an app's config vars.

Note: To use it, set the HEROKU_API_KEY environment variable or set it in a Purobu::Configuration.run

For example:

heroku_api.get_config_vars('some-app').body
  # {"HEROKU_POSTGRESQL_PURPLE_URL"=>"postgres://user:pass@host:5732/database"}
heroku_api.get_addons('some-app').body
  # [{"slug"=>"crane", "selective"=>false,
      "configured"=>true,
      "url"=>nil,
      "state"=>"public",
      "group_description"=>"Heroku Postgresql",
      "consumes_dyno_hours"=>false,
      "price"=>{"cents"=>0, "unit"=>"month"},
      "attachment_name"=>"HEROKU_POSTGRESQL_TEAL",
      "plan_description"=>"Crane",
      "name"=>"heroku-postgresql:crane",
      "beta"=>false,
      "attachable"=>false,
      "description"=>"Heroku Postgres Crane",
      "terms_of_service"=>false}]

Meta

purobu was written by Harold Giménez and is Copyright 2012 Heroku