grid

= 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 [e-mail] -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 [e-mail] -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 [e-mail] -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.

== Copyright

Copyright (c) 2011 Tim Koopmans. See LICENSE.txt for details.