Grid

This is a utility gem for use with Gridinit.com.

About

Gridinit.com is a RESTful API for distributed testing. It currently supports Watir test cases with plans to also support Selenium in the near future. Gridinit allows for the simple command and control of grid resources. You can control the grid using the included RESTful API, or you can use this gem which is another abstraction of the API from the command line.

A Grid consists of loosely coupled, distributed “nodes”. Nodes are an alias for remote browsers. Nodes can be grouped into “intranodes”, which is a collection of similar nodes defined by their browser type, quantity and location.

One Grid can have many Intranodes, with each Intranode consisting of many Nodes!

Getting Started

To install Grid:

gem install grid

You will need an account on Gridinit.com before you proceed. You can also purchase credits on Gridinit, which are necessary to consume resources on the cloud. After you have created an account and purchased credits (note: first 50 credits are free) you can run the following from any command line / terminal.

The Grid Command Line

Usage: grid [options] command

Commands:
 list - List all grids
 show - Show specified grids
 create - Create a new grid
 add - Add intranode to specified grid ID
 delete - Delete intranode from specified grid ID
 start - Start specified grid ID
 stop - Stop specified grid ID
 restart - Restart specified grid ID
 status - Update status of specified grid ID

Options:
  -g, --grid ID                    Specify the Grid ID to use
  -t, --token TOKEN                Specify the token to authenticate with
  -e, --email EMAIL                Specify the email to authenticate with, if not using token
  -p, --password PASSWORD          Specify the password to authenticate with, if not using token
  -u, --uri URI                    Optional URI of the Gridinit API, default http://gridin.it/api/v0
  -h, --help                       Show this message

Step 1. Create a new Grid

Create a new grid with the create command. Following is an example using your email address and password as parameters. You will then be prompted for the name, description, number, type and location of nodes which are the remote providers (browsers).

grid -e [email protected] -p yourpassword create

D, [2011-04-17 11:49:06 #43304] DEBUG -- : Current token: yKan0JEfPSEbwsgeSRIYSg
Grid name: |Grid|
Grid description: |Grid created Sun Apr 17 11:49:07 +1000 2011| 
Number of nodes: |5|
Location of nodes: |us-east|
Node type: |webdriver|
D, [2011-04-17 11:49:10 #43304] DEBUG -- : Creating grid ...
D, [2011-04-17 11:49:10 #43304] DEBUG -- : Creating intranode ...
D, [2011-04-17 11:49:10 #43304] DEBUG -- : Listing grid ...
{
  "grid" => {
              "name" => "Grid",
        "created_at" => "2011-04-17T11:49:10+10:00",
        "updated_at" => "2011-04-17T11:49:10+10:00",
                "id" => 1,
           "user_id" => 1,
      "credits_used" => 0,
             "nodes" => 5,
       "description" => "Grid created Sun Apr 17 11:49:07 +1000 2011",
        "intranodes" => [
          [0] {
              "intranode" => {
                         "grid_id" => 1,
                      "created_at" => "2011-04-17T11:49:10+10:00",
                        "location" => "us-east",
                      "updated_at" => "2011-04-17T11:49:10+10:00",
                              "id" => 1,
                    "credits_used" => 0,
                         "user_id" => 1,
                           "nodes" => 5,
                  "controller_uri" => nil,
                          "status" => "stopped",
                          "active" => true,
                    "browser_type" => "webdriver"
              }
          }
      ],
            "active" => true
  }
}

Step 2. Start the Grid

Once you have created a grid, you can use the start command to start up the remote browsers.

grid -e [email protected] -p yourpassword start

D, [2011-04-17 11:49:21 #43313] DEBUG -- : Current token: dm3uw4yKY6jqknCvzGKBHQ
Grid ID: 1
D, [2011-04-17 11:49:22 #43313] DEBUG -- : Starting grid ...
D, [2011-04-17 11:49:31 #43313] DEBUG -- : Listing grid ...
{
  "grid" => {
              "name" => "Grid",
        "created_at" => "2011-04-17T11:49:10+10:00",
        "updated_at" => "2011-04-17T11:49:10+10:00",
                "id" => 1,
           "user_id" => 1,
      "credits_used" => 0,
             "nodes" => 5,
       "description" => "Grid created Sun Apr 17 11:49:07 +1000 2011",
        "intranodes" => [
          [0] {
              "intranode" => {
                         "grid_id" => 1,
                      "created_at" => "2011-04-17T11:49:10+10:00",
                        "location" => "us-east",
                      "updated_at" => "2011-04-17T11:49:31+10:00",
                              "id" => 1,
                    "credits_used" => 0,
                         "user_id" => 1,
                           "nodes" => 5,
                  "controller_uri" => nil,
                          "status" => "starting",
                          "active" => true,
                    "browser_type" => "webdriver"
              }
          }
      ],
            "active" => true
  }
}

Step 3. Refresh the status of the Grid

After starting the grid, you can refresh its status to confirm all grid => intranodes have a “running” status. Typically it takes between 30 - 60s to start up all the remote browsers on the grid. You can refresh the status with the status command.

grid -e [email protected] -p yourpassword start

D, [2011-04-17 11:49:44 #43339] DEBUG -- : Current token: xTbnoM6LVSjjLjQSB4GLtA
Grid ID: 1
D, [2011-04-17 11:49:45 #43339] DEBUG -- : Updating status of grid ...
D, [2011-04-17 11:49:49 #43339] DEBUG -- : Listing grid ...
{
  "grid" => {
              "name" => "Grid",
        "created_at" => "2011-04-17T11:49:10+10:00",
        "updated_at" => "2011-04-17T11:49:47+10:00",
                "id" => 1,
           "user_id" => 1,
      "credits_used" => 5,
             "nodes" => 5,
       "description" => "Grid created Sun Apr 17 11:49:07 +1000 2011",
        "intranodes" => [
          [0] {
              "intranode" => {
                         "grid_id" => 1,
                      "created_at" => "2011-04-17T11:49:10+10:00",
                        "location" => "us-east",
                      "updated_at" => "2011-04-17T11:49:49+10:00",
                              "id" => 1,
                    "credits_used" => 5,
                         "user_id" => 1,
                           "nodes" => 5,
                  "controller_uri" => "druby://ec2-50-17-120-217.compute-1.amazonaws.com:11235",
                          "status" => "{\"running\":5}",
                          "active" => true,
                    "browser_type" => "webdriver"
              }
          }
      ],
            "active" => true
  }
}

Take note of the intranode status which in this examples indicates that there are 5 nodes “running” on the first intranode in your grid. Also take note of the controller_uri as this will be what you connect to when you distribute your tests. In this example the controller_uri is “druby://ec2-50-17-120-217.compute-1.amazonaws.com:11235”

Step 4. Distribute your tests on the Grid

Very little modification is needed to your existing test scripts. Essentially you will “top and tail” your test scripts with a Grid.control method as follows

*Old Code*

require 'watir-webdriver'
browser = Watir::Browser.new :firefox
browser.goto("http://www.google.com")
browser.text_field(:name, 'q').set("gridinit")
browser.button(:name => "btnG").click
browser.close

*New Code*

require 'grid'
Grid.control(
:controller_uri => 'druby://ec2-50-17-172-40.compute-1.amazonaws.com:11235') do |browser, id|
  puts "My remote browser id is #{id}"
  browser.goto("http://www.google.com")
  browser.text_field(:name, 'q').set("watirgrid")
  browser.button(:name => "btnG").click
  browser.close
end

In this example, we required the ‘grid’ gem and controlled a Grid object with the “control” method. This method requires the :controller_uri parameter obtained from step 3 and is passed a block of your existing watir code. The same method will yield an individual browser object (same as a Watir browser object) as well as a thread ID which you can use to help identify which node your code is executed on.

Contributing to the Grid

Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.