Module Watir::Container
In: watir/container.rb

This module contains the factory methods that are used to access most html objects

For example, to access a button on a web page that has the following html 

 <input type = button name= 'b1' value='Click Me' onClick='javascript:doSomething()'>

the following watir code could be used 

 ie.button(:name, 'b1').click

or 

 ie.button(:value, 'Click Me').to_s

there are many methods available to the Button object

Is includable for classes that have @container, document and ole_inner_elements

Methods

area   areas   button   buttons   cell   cells   checkbox   checkboxes   divs   file_field   file_fields   form   frame   hidden   hiddens   image   images   labels   link   links   lis   locate_input_element   locate_tagged_element   log   map   maps   modal_dialog   popup   pres   ps   radio   radios   row   rows   select_list   select_lists   set_container   show_all_objects   spans   table   tables   text_field   text_fields   wait  

Included Modules

Watir::Exception

Attributes

activeObjectHighLightColor  [RW]  The color we want to use for the active object. This can be any valid web-friendly color.
page_container  [RW]  The PageContainer object containing this element
type_keys  [RW] 
typingspeed  [RW]  This is used to change the typing speed when entering text on a page.

Public Instance methods

area(how, what=nil)

This is the main method for accessing area tags - msdn.microsoft.com/workshop/author/dhtml/reference/objects/area.asp?frame=true 

 *  how   - symbol - how we access the area
 *  what  - string, integer or regular expression - what we are looking for,

Valid values for ‘how’ are listed in the Watir Wiki - wiki.openqa.org/display/WTR/Methods+supported+by+Element

returns a area object

Typical Usage 

  ie.area(:id, /list/)                 # access the first area that matches list.
  ie.area(:index,2)                    # access the second area on the page
  ie.area(:title, "A Picture")         # access a area using the tooltip text. See http://msdn.microsoft.com/workshop/author/dhtml/reference/properties/title_1.asp?frame=true
areas()

this is the main method for accessing the areas iterator.

Returns a areas object

Typical usage: 

  ie.areas.each { |s| puts s.to_s }            # iterate through all the areas on the page
  ie.areas[1].to_s                             # goto the first area on the page
  ie.areas.length                              # show how many areas are on the page.
button(how, what=nil)

This is the main method for accessing a button. Often declared as an <input type = submit> tag. 

 *  how   - symbol - how we access the button, :index, :id, :name etc
 *  what  - string, integer or regular expression - what we are looking for,

Valid values for ‘how’ are listed in the Watir Wiki - wiki.openqa.org/display/WTR/Methods+supported+by+Element

Returns a Button object.

Typical usage 

   ie.button(:id,    'b_1')                             # access the button with an ID of b_1
   ie.button(:name,  'verify_data')                     # access the button with a name of verify_data
   ie.button(:value, 'Login')                           # access the button with a value (the text displayed on the button) of Login
   ie.button(:caption, 'Login')                         # same as above
   ie.button(:value, /Log/)                             # access the button that has text matching /Log/
   ie.button(:index, 2)                                 # access the second button on the page (1 based, so the first button is accessed with :index,1)
   ie.button(:class, 'my_custom_button_class')          # access the button with a class of my_custom_button_class
   ie.button(:xpath, "//input[@value='Click Me']/")     # access the button with a value of Click Me

Accessing a Button nested within another element 

   ie.div(:class, 'xyz').button(:index, 2)              # access a div of class xyz, and the 2nd button within that div

If only a single parameter is supplied, then :value is used 

   ie.button('Click Me')                                # access the button with a value of Click Me
buttons()

this is the main method for accessing the buttons iterator. It returns a Buttons object

Typical usage: 

  ie.buttons.each { |b| puts b.to_s }                   # iterate through all the buttons on the page
  ie.buttons[1].to_s                                    # goto the first button on the page
  ie.buttons.length                                     # show how many buttons are on the page.
cell(how, what=nil)

this method accesses a table cell. how - symbol - how we access the cell, valid values are 

   :id       - find the table cell with given id.
   :xpath    - find the table cell using xpath query.

returns a TableCell Object

checkbox(how, what, value=nil)

This is the main method for accessing a check box. Usually an <input type = checkbox> HTML tag. 

 *  how   - symbol - how we access the check box - :index, :id, :name etc
 *  what  - string, integer or regular expression - what we are looking for,
 *  value - string - when there are multiple objects with different value attributes, this can be used to find the correct object

Valid values for ‘how’ are listed in the Watir Wiki - wiki.openqa.org/display/WTR/Methods+supported+by+Element

returns a CheckBox object

Typical usage 

   ie.checkbox(:id, 'send_email')                    # access the check box with an id of send_mail
   ie.checkbox(:name, 'send_copy')                   # access the check box with a name of send_copy
   ie.checkbox(:name, /n_/)                          # access the first check box whose name matches n_
   ie.checkbox(:index, 2)                            # access the second check box on the page (1 based, so the first field is accessed with :index,1)

In many instances, checkboxes on an html page have the same name, but are identified by different values. An example is shown next. 

 <input type = checkbox name = email_frequency value = 'daily' > Daily Email
 <input type = checkbox name = email_frequency value = 'Weekly'> Weekly Email
 <input type = checkbox name = email_frequency value = 'monthly'>Monthly Email

Watir can access these using the following: 

   ie.checkbox(:id, 'day_to_send', 'monday')         # access the check box with an id of day_to_send and a value of monday
   ie.checkbox(:name,'email_frequency', 'weekly')    # access the check box with a name of email_frequency and a value of 'weekly'
   ie.checkbox(:xpath, "//input[@name='email_frequency' and @value='daily']/")     # access the checkbox with a name of email_frequency and a value of 'daily'
checkboxes()

this is the method for accessing the check boxes iterator. Returns a CheckBoxes object

Typical usage: 

  ie.checkboxes.each { |c| puts c.to_s }             # iterate through all the check boxes on the page
  ie.checkboxes[1].to_s                              # goto the first check box on the page
  ie.checkboxes.length                               # show how many check boxes are on the page.
divs()

this is the main method for accessing the divs iterator. Returns a Divs collection

Typical usage: 

  ie.divs.each { |d| puts d.to_s }            # iterate through all the divs on the page
  ie.divs[1].to_s                             # goto the first div on the page
  ie.divs.length                              # show how many divs are on the page.
file_field(how, what=nil)

This is the main method for accessing a file field. Usually an <input type = file> HTML tag. 

 *  how   - symbol - how we access the field, valid values are
   :index      - find the file field using index
   :id         - find the file field using id attribute
   :name       - find the file field using name attribute
   :xpath      - find the file field using xpath query
 *  what  - string, integer, regular expression, or xpath query - what we are looking for,

returns a FileField object

Typical Usage 

   ie.file_field(:id,   'up_1')                     # access the file upload field with an ID of up_1
   ie.file_field(:name, 'upload')                   # access the file upload field with a name of upload
   ie.file_field(:index, 2)                         # access the second file upload on the page (1 based, so the first field is accessed with :index,1)
file_fields()

this is the main method for accessing the file_fields iterator. It returns a FileFields object

Typical usage: 

  ie.file_fields.each { |f| puts f.to_s }            # iterate through all the file fields on the page
  ie.file_fields[1].to_s                             # goto the first file field on the page
  ie.file_fields.length                              # show how many file fields are on the page.
form(how, what=nil)

this method is used to access a form. available ways of accessing it are, :index, :name, :id, :method, :action, :xpath 

 * how    - symbol - What mecahnism we use to find the form, one of
                the above. NOTE if what is not supplied this parameter is the NAME of the form
 * what   - String - the text associated with the symbol

Valid values for ‘how’ are listed in the Watir Wiki - wiki.openqa.org/display/WTR/Methods+supported+by+Element

returns a Form object

frame(how, what=nil)

this method is the main way of accessing a frame 

  *  how   - how the frame is accessed. This can also just be the name of the frame.
  *  what  - what we want to access.

Valid values for ‘how’ are listed in the Watir Wiki - wiki.openqa.org/display/WTR/Methods+supported+by+Element

returns a Frame object

Typical usage: 

  ie.frame(:index, 1)
  ie.frame(:name, 'main_frame')
  ie.frame('main_frame')        # in this case, just a name is supplied
hidden(how, what=nil)

This is the main method for accessing a hidden field. Usually an <input type = hidden> HTML tag 

 *  how   - symbol - how we access the hidden field, :index, :id, :name etc
 *  what  - string, integer or regular expression - what we are looking for,

Valid values for ‘how’ are listed in the Watir Wiki - wiki.openqa.org/display/WTR/Methods+supported+by+Element

returns a Hidden object

Typical usage 

   ie.hidden(:id, 'session_id')                 # access the hidden field with an ID of session_id
   ie.hidden(:name, 'temp_value')               # access the hidden field with a name of temp_value
   ie.hidden(:index, 2)                         # access the second hidden field on the page (1 based, so the first field is accessed with :index,1)
   ie.hidden(:xpath, "//input[@type='hidden' and @id='session_value']/")    # access the hidden field with an ID of session_id
hiddens()

this is the method for accessing the hiddens iterator. It returns a Hiddens object

Typical usage: 

  ie.hiddens.each { |t| puts t.to_s }            # iterate through all the hidden fields on the page
  ie.hiddens[1].to_s                             # goto the first hidden field on the page
  ie.hiddens.length                              # show how many hidden fields are on the page.
image(how, what=nil)

This is the main method for accessing images - normally an <img src="image.gif"> HTML tag. 

 *  how   - symbol - how we access the image, :index, :id, :name, :src, :title or :alt are supported
 *  what  - string, integer or regular expression - what we are looking for,

Valid values for ‘how’ are listed in the Watir Wiki - wiki.openqa.org/display/WTR/Methods+supported+by+Element

returns an Image object

Typical Usage 

  ie.image(:src, /myPic/)             # access the first image that matches myPic. We can use a string in place of the regular expression
                                      # but the complete path must be used, ie.image(:src, 'http://myserver.com/my_path/my_image.jpg')
  ie.image(:index,2)                  # access the second image on the page
  ie.image(:alt, "A Picture")         # access an image using the alt text
  ie.image(:xpath, "//img[@alt='A Picture']/")    # access an image using the alt text
images()

This is the main method for accessing the images collection. Returns an Images object

Typical usage: 

  ie.images.each { |i| puts i.to_s }            # iterate through all the images on the page
  ie.images[1].to_s                             # goto the first image on the page
  ie.images.length                              # show how many images are on the page.
labels()

this is the main method for accessing the labels iterator. It returns a Labels object

Returns a Labels object

Typical usage: 

  ie.labels.each { |l| puts l.to_s }            # iterate through all the labels on the page
  ie.labels[1].to_s                             # goto the first label on the page
  ie.labels.length                              # show how many labels are on the page.
link(how, what=nil)

This is the main method for accessing a link. 

 *  how   - symbol - how we access the link, :index, :id, :name, :title, :text, :url
 *  what  - string, integer or regular expression - what we are looking for,

Valid values for ‘how’ are listed in the Watir Wiki - wiki.openqa.org/display/WTR/Methods+supported+by+Element

returns a Link object

Typical Usage 

  ie.link(:url, /login/)              # access the first link whose url matches login. We can use a string in place of the regular expression
                                      # but the complete path must be used, ie.link(:url, 'http://myserver.com/my_path/login.asp')
  ie.link(:index,2)                   # access the second link on the page
  ie.link(:title, "Picture")         # access a link using the tool tip
  ie.link(:text, 'Click Me')          # access the link that has Click Me as its text
  ie.link(:xpath, "//a[contains(.,'Click Me')]/")      # access the link with Click Me as its text
links()

This is the main method for accessing the links collection. Returns a Links object

Typical usage: 

  ie.links.each { |l| puts l.to_s }            # iterate through all the links on the page
  ie.links[1].to_s                             # goto the first link on the page
  ie.links.length                              # show how many links are on the page.
lis()

this is the main method for accessing the lis iterator.

Returns a lis object

Typical usage: 

  ie.lis.each { |s| puts s.to_s }            # iterate through all the lis on the page
  ie.lis[1].to_s                             # goto the first li on the page
  ie.lis.length                              # show how many lis are on the page.
locate_input_element(how, what, types, value=nil)

Returns the specified ole object for input elements on a web page.

This method is used internally by Watir and should not be used externally. It cannot be marked as private because of the way mixins and inheritance work in watir 

  * how - symbol - the way we look for the object. Supported values are
                 - :name
                 - :id
                 - :index
                 - :value etc
  * what  - string that we are looking for, ex. the name, or id tag attribute or index of the object we are looking for.
  * types - what object types we will look at.
  * value - used for objects that have one name, but many values. ex. radio lists and checkboxes
locate_tagged_element(tag, how, what)

returns the ole object for the specified element

log(what)

Write the specified string to the log.

map(how, what=nil)

This is the main method for accessing map tags - msdn.microsoft.com/workshop/author/dhtml/reference/objects/map.asp?frame=true 

 *  how   - symbol - how we access the map,
 *  what  - string, integer or regular expression - what we are looking for,

Valid values for ‘how’ are listed in the Watir Wiki - wiki.openqa.org/display/WTR/Methods+supported+by+Element

returns a map object

Typical Usage 

  ie.map(:id, /list/)                 # access the first map that matches list.
  ie.map(:index,2)                    # access the second map on the page
  ie.map(:title, "A Picture")         # access a map using the tooltip text. See http://msdn.microsoft.com/workshop/author/dhtml/reference/properties/title_1.asp?frame=true
maps()

this is the main method for accessing the maps iterator.

Returns a maps object

Typical usage: 

  ie.maps.each { |s| puts s.to_s }            # iterate through all the maps on the page
  ie.maps[1].to_s                             # goto the first map on the page
  ie.maps.length                              # show how many maps are on the page.
modal_dialog(how=nil, what=nil)

Access a modal web dialog, which is a PageContainer, like IE or Frame. Returns a ModalDialog object.

Typical Usage 

   ie.modal_dialog                  # access the modal dialog of ie
   ie.modal_dialog(:title, 'Title') # access the modal dialog by title
   ie.modal_dialog.modal_dialog     # access a modal dialog's modal dialog XXX untested!

This method will not work when Watir/Ruby is run under a service (instead of a user). Note: unlike Watir.attach, this returns before the page is assured to have loaded.

popup(

This is the main method for accessing JavaScript popups. returns a PopUp object

pres()

this is the main method for accessing the ps iterator.

Returns a Pres object

Typical usage: 

  ie.pres.each { |pre| puts pre.to_s }        # iterate through all the pre tags on the page
  ie.pres[1].to_s                             # goto the first pre tag on the page
  ie.pres.length                              # show how many pre tags are on the page.
ps()

this is the main method for accessing the ps iterator.

Returns a Ps object

Typical usage: 

  ie.ps.each { |p| puts p.to_s }            # iterate through all the p tags on the page
  ie.ps[1].to_s                             # goto the first p tag on the page
  ie.ps.length                              # show how many p tags are on the page.
radio(how, what, value=nil)

This is the main method for accessing a radio button. Usually an <input type = radio> HTML tag. 

 *  how   - symbol - how we access the radio button, :index, :id, :name etc
 *  what  - string, integer or regular expression - what we are looking for,
 *  value - string - when  there are multiple objects with different value attributes, this can be used to find the correct object

Valid values for ‘how’ are listed in the Watir Wiki - wiki.openqa.org/display/WTR/Methods+supported+by+Element

returns a Radio object

Typical usage 

   ie.radio(:id, 'send_email')                   # access the radio button with an id of currency
   ie.radio(:name, 'send_copy')                  # access the radio button with a name of country
   ie.radio(:name, /n_/)                        # access the first radio button whose name matches n_
   ie.radio(:index, 2)                           # access the second radio button on the page (1 based, so the first field is accessed with :index,1)

In many instances, radio buttons on an html page have the same name, but are identified by different values. An example is shown next. 

 <input type="radio" name="email_frequency" value="daily">Daily Email</input>
 <input type="radio" name="email_frequency" value="weekly">Weekly Email</input>
 <input type="radio" name="email_frequency" value="monthly">Monthly Email</input>

Watir can access these using the following: 

   ie.radio(:id, 'day_to_send', 'monday')         # access the radio button with an id of day_to_send and a value of monday
   ie.radio(:name,'email_frequency', 'weekly')     # access the radio button with a name of email_frequency and a value of 'weekly'
   ie.radio(:xpath, "//input[@name='email_frequency' and @value='daily']/")     # access the radio button with a name of email_frequency and a value of 'daily'
radios()

This is the method for accessing the radio buttons iterator. Returns a Radios object

Typical usage: 

  ie.radios.each { |r| puts r.to_s }            # iterate through all the radio buttons on the page
  ie.radios[1].to_s                             # goto the first radio button on the page
  ie.radios.length                              # show how many radio buttons are on the page.
row(how, what=nil)

this method accesses a table row. how - symbol - how we access the row, valid values are 

   :id       - find the table row with given id.
   :xpath    - find the table row using xpath query.

returns a TableRow object

select_list(how, what)

This is the main method for accessing a selection list. Usually a <select> HTML tag. 

 *  how   - symbol - how we access the selection list, :index, :id, :name etc
 *  what  - string, integer or regular expression - what we are looking for,

Valid values for ‘how’ are listed in the Watir Wiki - wiki.openqa.org/display/WTR/Methods+supported+by+Element

returns a SelectList object

Typical usage 

   ie.select_list(:id, 'currency')                   # access the select box with an id of currency
   ie.select_list(:name, 'country')                  # access the select box with a name of country
   ie.select_list(:name, /n_/)                       # access the first select box whose name matches n_
   ie.select_list(:index, 2)                         # access the second select box on the page (1 based, so the first field is accessed with :index,1)
   ie.select(:xpath, "//select[@id='currency']/")    # access the select box with an id of currency
select_lists()

this is the method for accessing the select lists iterator. Returns a SelectLists object

Typical usage: 

  ie.select_lists.each { |s| puts s.to_s }            # iterate through all the select boxes on the page
  ie.select_lists[1].to_s                             # goto the first select boxes on the page
  ie.select_lists.length                              # show how many select boxes are on the page.
show_all_objects()

This method shows the available objects on the current page. This is usually only used for debugging or writing new test scripts. This is a nice feature to help find out what HTML objects are on a page when developing a test case using Watir.

spans()

this is the main method for accessing the spans iterator.

Returns a Spans object

Typical usage: 

  ie.spans.each { |s| puts s.to_s }            # iterate through all the spans on the page
  ie.spans[1].to_s                             # goto the first span on the page
  ie.spans.length                              # show how many spans are on the page.
table(how, what=nil)

This method is used to get a table from the page. :index (1 based counting) and :id are supported. 

 NOTE :name is not supported, as the table tag does not have a name attribute. It is not part of the DOM.

:index can be used when there are multiple tables on a page. :xpath can be used to select table using XPath query. The first form can be accessed with :index 1, the second :index 2, etc. 

  * how   - symbol - how we access the table, :index, :id, :xpath etc
  * what  - string the thing we are looking for, ex. id, index or xpath query, of the object we are looking for

Valid values for ‘how’ are listed in the Watir Wiki - wiki.openqa.org/display/WTR/Methods+supported+by+Element

returns a Table object

tables()

this is the main method for accessing the tables iterator. It returns a Tables object

Typical usage: 

  ie.tables.each { |t| puts t.to_s }            # iterate through all the tables on the page
  ie.tables[1].to_s                             # goto the first table on the page
  ie.tables.length                              # show how many tables are on the page. Tables that are nested will be included in this
text_field(how, what=nil)

This is the main method for accessing a text field. Usually an <input type = text> HTML tag. or a text area - a <textarea> tag 

 *  how   - symbol - how we access the field, :index, :id, :name etc
 *  what  - string, integer or regular expression - what we are looking for,

Valid values for ‘how’ are listed in the Watir Wiki - wiki.openqa.org/display/WTR/Methods+supported+by+Element

returns a TextField object

Typical Usage 

   ie.text_field(:id,   'user_name')                 # access the text field with an ID of user_name
   ie.text_field(:name, 'address')                   # access the text field with a name of address
   ie.text_field(:index, 2)                          # access the second text field on the page (1 based, so the first field is accessed with :index,1)
   ie.text_field(:xpath, "//textarea[@id='user_name']/")    # access the text field with an ID of user_name
text_fields()

this is the method for accessing the text_fields iterator. It returns a Text_Fields object

Typical usage: 

  ie.text_fields.each { |t| puts t.to_s }            # iterate through all the text fields on the page
  ie.text_fields[1].to_s                             # goto the first text field on the page
  ie.text_fields.length                              # show how many text field are on the page.
wait(no_sleep=false)

Wait until Internet Explorer has finished loading the page.

[Validate]