= Common Examples

== Starting a Controller
A controller has the following startup options:
  controller --help
  Usage: controller [options]
  Specific options:
      -H, --drb-server-host HOST       Specify DRb Server interface to host on
      -d, --drb-server-port PORT       Specify DRb Server port to listen on
      -h, --ring-server-host HOST      Specify Ring Server interface to host on
      -r, --ring-server-port PORT      Specify Ring Server port to listen on
      -a, --access-control-list ACLS   Specify a comma separated Access Control List
      -l, --log-level LEVEL            Specify log level {DEBUG|INFO|ERROR}
          --help                       Show this message

=== Default
To start a controller with default settings:
  $ controller

This will bind the controller to your external facing interface and register the ring server to listen on port 12358
e.g.
  DRb server started on : druby://143.238.105.61:11235
  Ring server started on: druby://143.238.105.61:12358
  
=== Start on specific interface or ports
To start a controller on specific interfaces or ports:
  $  controller -H 127.0.0.1 -h 127.0.0.1 -d 12345 -r 54321

This will bind the controller to the localhost (127.0.0.1) with the DRb server listening on port 12345 and the ring server listening on port 54321
e.g.
  DRb server started on : druby://127.0.0.1:12345
  Ring server started on: druby://127.0.0.1:54321
  

=== Start with access control list
To start a controller with an access control list:
  $  controller -a deny,all,allow,127.0.0.1 -H 127.0.0.1 -h 127.0.0.1

This will bind the controller to the localhost (127.0.0.1) and deny all access to the controller by default, whilst allowing access from localhost only. The ACL constructor takes an array of strings. The first string of a pair is always “allow” or “deny”, and it’s followed by the address or addresses to allow or deny access.

== Starting a Provider
A provider has similar startup options:
  provider --help
  # Usage: provider [options]
  # Specific options:
  #     -H, --drb-server-host HOST       Specify DRb Server interface to host on
  #     -d, --drb-server-port PORT       Specify DRb Server port to listen on
  #     -h, --ring-server-host HOST      Specify Ring Server host to connect to
  #     -r, --ring-server-port PORT      Specify Ring Server port to broadcast on
  #     -b, --browser-type TYPE          Specify browser type to register {ie|firefox|safari}
  #     -a, --access-control-list ACLS   Specify a comma separated Access Control List
  #     -l, --log-level LEVEL            Specify log level {DEBUG|INFO|ERROR}
  #         --help                       Show this message

=== Default
To start a controller with default settings:
  $ provider

This will bind the provider to your external facing interface attempt to find the ring server on the default port of 12358
e.g.
  DRb server started on : druby://143.238.105.61:11236
  Ring server found on  : druby://143.238.105.61:12358
  New tuple registered  : druby://143.238.105.61:12358

=== Start on specific interface or ports
To start a provider on specific interfaces or ports:
  $  provider -r 12358 -h 143.238.105.61

This will attempt to find the ring server on the port and hostname specifed
e.g.
  DRb server started on : druby://143.238.105.61:11236
  Ring server found on  : druby://143.238.105.61:12358
  New tuple registered  : druby://143.238.105.61:12358

=== Start with access control list
To start a controller with an access control list:
  $  provider -a deny,all,allow,127.0.0.1

This will deny all access by default and allow access to this provider on localhost only.

=== Start with a specific browser supported
By default, the provider will try to instantiate a browser object based on availability with your operating system e.g. Internet Explorer, Firefox or Safari. You can force provision of a set browser type as follows:
  $  provider -b safari
  
This will provide a Safari browser object. Other options are:
  $  provider -b ie
  $  provider -b firefox

== Consuming Browser Objects on the Grid
Watir has been extended with a Grid class that can be used as follows:
  require 'rubygems'
  require 'watirgrid'

  grid = Watir::Grid.new(:ring_server_port => 12358)
  grid.start(:quantity => 1, :read_all => true, :browser_type => 'ie')
  threads = []
  grid.browsers.each do |browser|
    threads << Thread.new do 
      b = browser[:object].new_browser
      b.goto("http://www.google.com")
      b.text_field(:name, 'q').set("watirgrid")
      b.button(:name, "btnI").click
    end
  end
  threads.each {|thread| thread.join}

Stepping through this example we first instantiate a browsers object, specifying which ring server port to broadcast on when looking for available providers:
  grid = Watir::Grid.new(:ring_server_port => 12358)

You may also need to tell the code which host the ring server is on:
  grid = Watir::Grid.new(:ring_server_port => 12358, :ring_server_host => 143.238.105.61)

Next we start up the grid, specifying the number of browsers we wish to use, and the method of accessing the tuple space:
  grid.start(:quantity => 1, :read_all => true)
  
There are two methods for accessing the tuple space. 
  :read_all => true
  :take_all => true
*Read* *All* will read all browsers in the tuple space provided by the providers. This leaves the tuple open to other clients. 

*Take* *All* will take all browsers in the tuple space in a destructive manner. That is, once a tuple has been taken, no other clients will be able to re-use that tuple. This is useful if you do not want concurrent access to the same host, for example, multiple browsers running on the one machine.

The quantity attribute will determine how many browsers are accessed.
  :quantity => 10
Will attempt to access 10 tuples if they are available.

Other attributes include:
  :hostnames => { "localhost" => "127.0.0.1"}
Will determine which providers identified by a hash of hostnames that should be accessed. Useful if trying to limit the test to run from specific hostnames or IP addresses.

  :browser_type => 'firefox'
Will determine which providers identified by a browser type should be accessed. Useful if trying to to test with specific browser types.