Module: PageObject::Accessors

Included in:
IndexedProperties::RowOfElements
Defined in:
lib/page-object/accessors.rb

Overview

Contains the class level methods that are inserted into your page objects when you include the PageObject module. These methods will generate another set of methods that provide access to the elements on the web pages.

See Also:

Instance Method Summary (collapse)

Instance Method Details

- (Object) area(name, identifier = {:index => 0}, &block)

adds three methods - one to click the area, another to return the area element, and another to check the area's existence.

Examples:

area(:message, :id => 'message')
# will generate 'message', 'message_element', and 'message?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find an area. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :text => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



1051
1052
1053
1054
1055
1056
1057
# File 'lib/page-object/accessors.rb', line 1051

def area(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'area_for', &block)
  define_method(name) do
    return platform.click_area_for identifier.clone unless block_given?
    self.send("#{name}_element").click
  end
end

- (Object) audio(name, identifier = {:index => 0}, &block)

adds two methods - one to return the audio element and another to check the audio's existence.

Examples:

audio(:acdc, :id => 'audio_id')
# will generate 'acdc_element' and 'acdc?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find an audio element. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



1101
1102
1103
# File 'lib/page-object/accessors.rb', line 1101

def audio(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'audio_for', &block)
end

- (Object) button(name, identifier = {:index => 0}, &block)

adds three methods - one to click a button, another to return the button element, and another to check the button's existence.

Examples:

button(:purchase, :id => 'purchase')
# will generate 'purchase', 'purchase_element', and 'purchase?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a button. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :text => Watir only

    • :value => Watir and Selenium

    • :xpath => Watir and Selenium

    • :src => Watir and Selenium (input type=image only)

    • :alt => Watir and Selenium (input type=image only)

  • optional

    block to be invoked when element method is called



521
522
523
524
525
526
527
# File 'lib/page-object/accessors.rb', line 521

def button(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'button_for', &block)
  define_method(name) do
    return platform.click_button_for identifier.clone unless block_given?
    self.send("#{name}_element").click
  end
end

- (Object) canvas(name, identifier = {:index => 0}, &block)

adds two methods - one to return the canvas element and another to check the canvas's existence.

Examples:

canvas(:my_canvas, :id => 'canvas_id')
# will generate 'my_canvas_element' and 'my_canvas?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a canvas. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



1078
1079
1080
# File 'lib/page-object/accessors.rb', line 1078

def canvas(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'canvas_for', &block)
end

- (Object) cell(name, identifier = {:index => 0}, &block) Also known as: td

adds three methods - one to retrieve the text from a table cell, another to return the table cell element, and another to check the cell's existence.

Examples:

cell(:total, :id => 'total_cell')
# will generate 'total', 'total_element', and 'total?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a cell. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :text => Watir and Selenium

    • :xpath => Watir and Selenium

    • :css => Selenium only

  • optional

    block to be invoked when element method is called



638
639
640
641
642
643
644
# File 'lib/page-object/accessors.rb', line 638

def cell(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'cell_for', &block)
  define_method("#{name}") do
    return platform.cell_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) checkbox(name, identifier = {:index => 0}, &block)

adds five methods - one to check, another to uncheck, another to return the state of a checkbox, another to return a PageObject::Elements::CheckBox object representing the checkbox, and a final method to check the checkbox's existence.

Examples:

checkbox(:active, :name => "is_active")
# will generate 'check_active', 'uncheck_active', 'active_checked?',
# 'active_element', and 'active?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a checkbox. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :value => Watir and Selenium

    • :xpath => Watir and Selenium

    • :label => Watir and Selenium

  • optional

    block to be invoked when element method is called



390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
# File 'lib/page-object/accessors.rb', line 390

def checkbox(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'checkbox_for', &block)
  define_method("check_#{name}") do
    return platform.check_checkbox(identifier.clone) unless block_given?
    self.send("#{name}_element").check
  end
  define_method("uncheck_#{name}") do
    return platform.uncheck_checkbox(identifier.clone) unless block_given?
    self.send("#{name}_element").uncheck
  end
  define_method("#{name}_checked?") do
    return platform.checkbox_checked?(identifier.clone) unless block_given?
    self.send("#{name}_element").checked?
  end
end

- (Object) div(name, identifier = {:index => 0}, &block)

adds three methods - one to retrieve the text from a div, another to return the div element, and another to check the div's existence.

Examples:

div(:message, :id => 'message')
# will generate 'message', 'message_element', and 'message?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a div. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :text => Watir and Selenium

    • :title => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



550
551
552
553
554
555
556
# File 'lib/page-object/accessors.rb', line 550

def div(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'div_for', &block)
  define_method(name) do
    return platform.div_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) element(name, tag, identifier = {:index => 0}, &block)

adds three methods - one to retrieve the text of an element, another to retrieve an element, and another to check the element's existence.

Examples:

element(:title, :header, :id => 'title')
# will generate 'title', 'title_element', and 'title?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • the (Symbol)

    name of the tag for the element

  • identifier (Hash) (defaults to: {:index => 0})

    how we find an element. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
# File 'lib/page-object/accessors.rb', line 1172

def element(name, tag, identifier={:index => 0}, &block)
  define_method("#{name}") do
    self.send("#{name}_element").text
  end
  define_method("#{name}_element") do
    return call_block(&block) if block_given?
    platform.element_for(tag, identifier.clone)
  end
  define_method("#{name}?") do
    self.send("#{name}_element").exists?
  end
end

- (Object) elements(name, tag, identifier = {:index => 0}, &block)

adds a method to return a collection of generic Element objects for a specific tag.

Examples:

elements(:title, :header, :id => 'title')
# will generate ''title_elements'

Parameters:

  • the (Symbol)

    name used for the generated methods

  • the (Symbol)

    name of the tag for the element

  • identifier (Hash) (defaults to: {:index => 0})

    how we find an element. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



1205
1206
1207
1208
1209
1210
# File 'lib/page-object/accessors.rb', line 1205

def elements(name, tag, identifier={:index => 0}, &block)
  define_method("#{name}_elements") do
    return call_block(&block) if block_given?
    platform.elements_for(tag, identifier.clone)
  end
end

- (boolean) expected_element(element_name, timeout = ::PageObject.default_element_wait)

Creates a method that provides a way to initialize a page based upon an expected element. This is useful for pages that load dynamic content.

Examples:

Specify a text box named :address expected on the page within 10 seconds

expected_element(:address, 10)
page.has_expected_element?

Parameters:

  • the (Symbol)

    name given to the element in the declaration

  • timeout (optional, Integer) (defaults to: ::PageObject.default_element_wait)

    default value is 5 seconds

Returns:

  • (boolean)


114
115
116
117
118
# File 'lib/page-object/accessors.rb', line 114

def expected_element(element_name, timeout=::PageObject.default_element_wait)
  define_method("has_expected_element?") do
    self.respond_to? "#{element_name}_element" and self.send("#{element_name}_element").when_present timeout
  end
end

- (boolean) expected_element_visible(element_name, timeout = ::PageObject.default_element_wait, check_visible = false)

Creates a method that provides a way to initialize a page based upon an expected element to become visible. This is useful for pages that load dynamic content and might have hidden elements that are not shown.

Examples:

Specify a text box named :address expected on the page within 10 seconds

expected_element_visible(:address, 10)
page.has_expected_element_visible?

Parameters:

  • the (Symbol)

    name given to the element in the declaration

  • timeout (optional, Integer) (defaults to: ::PageObject.default_element_wait)

    default value is 5 seconds

  • also (optional, boolean)

    check that element to be visible if set to true

Returns:

  • (boolean)


132
133
134
135
136
137
# File 'lib/page-object/accessors.rb', line 132

def expected_element_visible(element_name, timeout=::PageObject.default_element_wait, check_visible=false)
  define_method("has_expected_element_visible?") do
    self.respond_to? "#{element_name}_element" and self.send("#{element_name}_element").when_present timeout
    self.respond_to? "#{element_name}_element" and self.send("#{element_name}_element").when_visible timeout
  end
end

- (boolean) expected_title(expected_title)

Creates a method that compares the expected_title of a page against the actual.

Examples:

Specify 'Google' as the expected title of a page

expected_title "Google"
page.has_expected_title?

Parameters:

  • expected_title (String)

    the literal expected title for the page

  • expected_title (Regexp)

    the expected title pattern for the page

Returns:

  • (boolean)

Raises:

  • An exception if expected_title does not match actual title



94
95
96
97
98
99
100
101
# File 'lib/page-object/accessors.rb', line 94

def expected_title(expected_title)
  define_method("has_expected_title?") do
    page_title = title
    has_expected_title = (expected_title === page_title)
    raise "Expected title '#{expected_title}' instead of '#{page_title}'" unless has_expected_title
    has_expected_title
  end
end

- (Object) file_field(name, identifier = {:index => 0}, &block)

adds three methods - one to set the file for a file field, another to retrieve the file field element, and another to check it's existence.

Examples:

file_field(:the_file, :id => 'file_to_upload')
# will generate 'the_file=', 'the_file_element', and 'the_file?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a file_field. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :title => Watir and Selenium

    • :xpath => Watir and Selenium

    • :label => Watir and Selenium

  • optional

    block to be invoked when element method is called



995
996
997
998
999
1000
1001
# File 'lib/page-object/accessors.rb', line 995

def file_field(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'file_field_for', &block)
  define_method("#{name}=") do |value|
    return platform.file_field_value_set(identifier.clone, value) unless block_given?
    self.send("#{name}_element").value = value
  end
end

- (Object) form(name, identifier = {:index => 0}, &block)

adds two methods - one to retrieve the form element, and another to check the form's existence.

Examples:

form(:login, :id => 'login')
# will generate 'login_element' and 'login?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a form. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :action => Watir and Selenium

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



692
693
694
# File 'lib/page-object/accessors.rb', line 692

def form(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'form_for', &block)
end

- (Object) h1(name, identifier = {:index => 0}, &block)

adds three methods - one to retrieve the text of a h1 element, another to retrieve a h1 element, and another to check for it's existence.

Examples:

h1(:title, :id => 'title')
# will generate 'title', 'title_element', and 'title?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a H1. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



803
804
805
806
807
808
809
# File 'lib/page-object/accessors.rb', line 803

def h1(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier,'h1_for', &block)
  define_method(name) do
    return platform.h1_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) h2(name, identifier = {:index => 0}, &block)

adds three methods - one to retrieve the text of a h2 element, another to retrieve a h2 element, and another to check for it's existence.

Examples:

h2(:title, :id => 'title')
# will generate 'title', 'title_element', and 'title?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a H2. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



830
831
832
833
834
835
836
# File 'lib/page-object/accessors.rb', line 830

def h2(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'h2_for', &block)
  define_method(name) do
    return platform.h2_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) h3(name, identifier = {:index => 0}, &block)

adds three methods - one to retrieve the text of a h3 element, another to return a h3 element, and another to check for it's existence.

Examples:

h3(:title, :id => 'title')
# will generate 'title', 'title_element', and 'title?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a H3. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



857
858
859
860
861
862
863
# File 'lib/page-object/accessors.rb', line 857

def h3(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'h3_for', &block)
  define_method(name) do
    return platform.h3_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) h4(name, identifier = {:index => 0}, &block)

adds three methods - one to retrieve the text of a h4 element, another to return a h4 element, and another to check for it's existence.

Examples:

h4(:title, :id => 'title')
# will generate 'title', 'title_element', and 'title?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a H4. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



884
885
886
887
888
889
890
# File 'lib/page-object/accessors.rb', line 884

def h4(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'h4_for', &block)
  define_method(name) do
    return platform.h4_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) h5(name, identifier = {:index => 0}, &block)

adds three methods - one to retrieve the text of a h5 element, another to return a h5 element, and another to check for it's existence.

Examples:

h5(:title, :id => 'title')
# will generate 'title', 'title_element', and 'title?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a H5. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



911
912
913
914
915
916
917
# File 'lib/page-object/accessors.rb', line 911

def h5(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'h5_for', &block)
  define_method(name) do
    return platform.h5_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) h6(name, identifier = {:index => 0}, &block)

adds three methods - one to retrieve the text of a h6 element, another to return a h6 element, and another to check for it's existence.

Examples:

h6(:title, :id => 'title')
# will generate 'title', 'title_element', and 'title?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a H6. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



938
939
940
941
942
943
944
# File 'lib/page-object/accessors.rb', line 938

def h6(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'h6_for', &block)
  define_method(name) do
    return platform.h6_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) hidden_field(name, identifier = {:index => 0}, &block) Also known as: hidden

adds three methods to the page object - one to get the text from a hidden field, another to retrieve the hidden field element, and another to check the hidden field's existence.

Examples:

hidden_field(:user_id, :id => "user_identity")
# will generate 'user_id', 'user_id_element' and 'user_id?' methods

Parameters:

  • the (String)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a hidden field. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :text => Watir and Selenium

    • :value => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



246
247
248
249
250
251
252
# File 'lib/page-object/accessors.rb', line 246

def hidden_field(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'hidden_field_for', &block)
  define_method(name) do
    return platform.hidden_field_value_for identifier.clone unless block_given?
    self.send("#{name}_element").value
  end
end

- (Object) image(name, identifier = {:index => 0}, &block) Also known as: img

adds two methods - one to retrieve the image element, and another to check the image's existence.

Examples:

image(:logo, :id => 'logo')
# will generate 'logo_element' and 'logo?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find an image. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :alt => Watir and Selenium

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :src => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



668
669
670
# File 'lib/page-object/accessors.rb', line 668

def image(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'image_for', &block)
end

- (Object) in_frame(identifier, frame = nil, &block)

Identify an element as existing within a frame . A frame parameter is passed to the block and must be passed to the other calls to PageObject. You can nest calls to in_frame by passing the frame to the next level.

Examples:

in_frame(:id => 'frame_id') do |frame|
  text_field(:first_name, :id => 'fname', :frame => frame)
end

Parameters:

  • identifier (Hash)

    how we find the frame. The valid keys are:

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :regexp => Watir only

  • frame (defaults to: nil)

    passed from a previous call to in_frame. Used to nest calls

  • block

    that contains the calls to elements that exist inside the frame.



157
158
159
160
161
# File 'lib/page-object/accessors.rb', line 157

def in_frame(identifier, frame=nil, &block)
  frame = [] if frame.nil?
  frame << {frame: identifier}
  block.call(frame)
end

- (Object) in_iframe(identifier, frame = nil, &block)

Identify an element as existing within an iframe. A frame parameter is passed to the block and must be passed to the other calls to PageObject. You can nest calls to in_frame by passing the frame to the next level.

Examples:

in_iframe(:id => 'frame_id') do |frame|
  text_field(:first_name, :id => 'fname', :frame => frame)
end

Parameters:

  • identifier (Hash)

    how we find the frame. The valid keys are:

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :regexp => Watir only

  • frame (defaults to: nil)

    passed from a previous call to in_iframe. Used to nest calls

  • block

    that contains the calls to elements that exist inside the iframe.



181
182
183
184
185
# File 'lib/page-object/accessors.rb', line 181

def in_iframe(identifier, frame=nil, &block)
  frame = [] if frame.nil?
  frame << {iframe: identifier}
  block.call(frame)
end

- (Object) indexed_property(name, identifier_list)

adds a method that will return an indexed property. The property will respond to the [] method with an object that has a set of normal page_object properties that correspond to the definitions included in the identifier_list parameter, with the “what” of the “how and what” substituted based on the index provided to the [] method.

Examples:

indexed_property(:title, [
  [:text_field,  :field_1,   :id => 'table[%s].field_1'],
  [:button,      :button_1,  :id => 'table[%s].button_1'],
  [:text_field,  :field_2,   :name => 'table[%s].field_2']
])
# will generate a title method that responds to [].  title['foo'] will return an object
# that responds to the normal methods expected for two text_fields and a button with the
# given names, using the given how and what with 'foo' substituted for the %s.  title[123]
# will do the same, using the integer 123 instead.

Parameters:

  • the (Symbol)

    name used for the generated method

  • definitions (Array)

    an array of definitions to define on the indexed property. Each entry in the array should contain two symbols and a hash, corresponding to one of the standard page_object properties with a single substitution marker in each value in the hash, e.g. [:text_field, :field_1, :id => 'table.field_1']



1280
1281
1282
1283
1284
# File 'lib/page-object/accessors.rb', line 1280

def indexed_property (name, identifier_list)
  define_method("#{name}") do
    IndexedProperties::TableOfElements.new(@browser, identifier_list)
  end
end

- (Object) label(name, identifier = {:index => 0}, &block)

adds three methods - one to retrieve the text from a label, another to return the label element, and another to check the label's existence.

Examples:

label(:message, :id => 'message')
# will generate 'message', 'message_element', and 'message?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a label. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :text => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



1023
1024
1025
1026
1027
1028
1029
# File 'lib/page-object/accessors.rb', line 1023

def label(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'label_for', &block)
  define_method(name) do
    return platform.label_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

adds three methods - one to select a link, another to return a PageObject::Elements::Link object representing the link, and another that checks the link's existence.

Examples:

link(:add_to_cart, :text => "Add to Cart")
# will generate 'add_to_cart', 'add_to_cart_element', and 'add_to_cart?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a link. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :href => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :link => Watir and Selenium

    • :link_text => Watir and Selenium

    • :name => Watir and Selenium

    • :text => Watir and Selenium

    • :title => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



357
358
359
360
361
362
363
# File 'lib/page-object/accessors.rb', line 357

def link(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'link_for', &block)
  define_method(name) do
    return platform.click_link_for identifier.clone unless block_given?
    self.send("#{name}_element").click
  end
end

- (Object) list_item(name, identifier = {:index => 0}, &block) Also known as: li

adds three methods - one to retrieve the text from a list item, another to return the list item element, and another to check the list item's existence.

Examples:

list_item(:item_one, :id => 'one')
# will generate 'item_one', 'item_one_element', and 'item_one?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a list item. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :text => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



717
718
719
720
721
722
723
# File 'lib/page-object/accessors.rb', line 717

def list_item(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'list_item_for', &block)
  define_method(name) do
    return platform.list_item_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) ordered_list(name, identifier = {:index => 0}, &block) Also known as: ol

adds three methods - one to return the text withing the ordered list, one to retrieve the ordered list element, and another to test it's existence.

Examples:

ordered_list(:top_five, :id => 'top')
# will generate 'top_five', 'top_five_element' and 'top_five?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find an ordered list. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



775
776
777
778
779
780
781
# File 'lib/page-object/accessors.rb', line 775

def ordered_list(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'ordered_list_for', &block)
  define_method(name) do
    return platform.ordered_list_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) page_url(url) Also known as: direct_url

Specify the url for the page. A call to this method will generate a 'goto' method to take you to the page.

Parameters:

  • the (String)

    url for the page.

  • a (Symbol)

    method name to call to get the url



40
41
42
43
44
45
46
47
48
49
50
51
52
# File 'lib/page-object/accessors.rb', line 40

def page_url(url)
  define_method("goto") do
    platform.navigate_to self.page_url_value
  end

  define_method('page_url_value') do
    lookup = url.kind_of?(Symbol) ? self.send(url) : url
    erb = ERB.new(%Q{#{lookup}})
    merged_params = self.class.instance_variable_get("@merged_params")
    params = merged_params ? merged_params : self.class.params
    erb.result(binding)
  end
end

- (Object) paragraph(name, identifier = {:index => 0}, &block) Also known as: p

adds three methods - one to retrieve the text of a paragraph, another to retrieve a paragraph element, and another to check the paragraph's existence.

Examples:

paragraph(:title, :id => 'title')
# will generate 'title', 'title_element', and 'title?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a paragraph. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



965
966
967
968
969
970
971
# File 'lib/page-object/accessors.rb', line 965

def paragraph(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'paragraph_for', &block)
  define_method(name) do
    return platform.paragraph_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) params

Return the params that exist on this page class



29
30
31
# File 'lib/page-object/accessors.rb', line 29

def params
  @params ||= {}
end

- (Object) params=(the_params)

Set some values that can be used withing the class. This is typically used to provide values that help build dynamic urls in the page_url method

Parameters:

  • the (Hash)

    value to set the params



22
23
24
# File 'lib/page-object/accessors.rb', line 22

def params=(the_params)
  @params = the_params
end

- (Object) radio_button(name, identifier = {:index => 0}, &block) Also known as: radio

adds five methods - one to select, another to clear, another to return if a radio button is selected, another method to return a PageObject::Elements::RadioButton object representing the radio button element, and another to check the radio button's existence.

Examples:

radio_button(:north, :id => "north")
# will generate 'select_north', 'clear_north', 'north_selected?',
# 'north_element', and 'north?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a radio button. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :value => Watir and Selenium

    • :xpath => Watir and Selenium

    • :label => Watir and Selenium

  • optional

    block to be invoked when element method is called



431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
# File 'lib/page-object/accessors.rb', line 431

def radio_button(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'radio_button_for', &block)
  define_method("select_#{name}") do
    return platform.select_radio(identifier.clone) unless block_given?
    self.send("#{name}_element").select
  end
  define_method("clear_#{name}") do
    return platform.clear_radio(identifier.clone) unless block_given?
    self.send("#{name}_element").clear
  end
  define_method("#{name}_selected?") do
    return platform.radio_selected?(identifier.clone) unless block_given?
    self.send("#{name}_element").selected?
  end
end

- (Object) radio_button_group(name, identifier) Also known as: radio_group

adds five methods to help interact with a radio button group - a method to select a radio button in the group by given value/text, a method to return the values of all radio buttins in the group, a method to return if a radio button in the group is selected (will return the text of the selected radio button, if true), a method to return an array of PageObject::Elements::RadioButton objects representing the radio button group, and finally a method to check the existence of the radio button group.

radio_button_group(:color, :name => “preferred_color”) will generate 'select_color', 'color_values', 'color_selected?', 'color_elements', and 'color?' methods

The valid keys are:

  • :name => Watir and Selenium

Parameters:

  • the (Symbol)

    name used for the generated methods

  • shared (Hash)

    identifier for the radio button group. Typically, a 'name' attribute.



468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
# File 'lib/page-object/accessors.rb', line 468

def radio_button_group(name, identifier)
  define_method("select_#{name}") do |value|
    platform.radio_buttons_for(identifier.clone).each do |radio_elem|
      if radio_elem.value == value
        return radio_elem.select
      end
    end
  end
  define_method("#{name}_values") do
    result = []
    platform.radio_buttons_for(identifier.clone).each do |radio_elem|
      result << radio_elem.value
    end
    return result
  end
  define_method("#{name}_selected?") do
    platform.radio_buttons_for(identifier.clone).each do |radio_elem|
      return radio_elem.value if radio_elem.selected?
    end
    return false
  end
  define_method("#{name}_elements") do
    return platform.radio_buttons_for(identifier.clone)
  end
  define_method("#{name}?") do
    return platform.radio_buttons_for(identifier.clone).any?
  end
end

- (Object) select_list(name, identifier = {:index => 0}, &block) Also known as: select

adds five methods - one to select an item in a drop-down, another to fetch the currently selected item text, another to retrieve the select list element, another to check the drop down's existence and another to get all the available options to select from.

Examples:

select_list(:state, :id => "state")
# will generate 'state', 'state=', 'state_element', 'state?', "state_options" methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a select list. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :text => Watir only

    • :value => Watir only

    • :xpath => Watir and Selenium

    • :label => Watir and Selenium

  • optional

    block to be invoked when element method is called



315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
# File 'lib/page-object/accessors.rb', line 315

def select_list(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'select_list_for', &block)
  define_method(name) do
    return platform.select_list_value_for identifier.clone unless block_given?
    self.send("#{name}_element").value
  end
  define_method("#{name}=") do |value|
    return platform.select_list_value_set(identifier.clone, value) unless block_given?
    self.send("#{name}_element").select(value)
  end
  define_method("#{name}_options") do
    element = self.send("#{name}_element")
    (element && element.options) ? element.options.collect(&:text) : []
  end
end

- (Object) span(name, identifier = {:index => 0}, &block)

adds three methods - one to retrieve the text from a span, another to return the span element, and another to check the span's existence.

Examples:

span(:alert, :id => 'alert')
# will generate 'alert', 'alert_element', and 'alert?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a span. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :text => Watir and Selenium

    • :title => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



579
580
581
582
583
584
585
# File 'lib/page-object/accessors.rb', line 579

def span(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'span_for', &block)
  define_method(name) do
    return platform.span_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) standard_methods(name, identifier, method, &block)



1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
# File 'lib/page-object/accessors.rb', line 1245

def standard_methods(name, identifier, method, &block)
  define_method("#{name}_element") do
    return call_block(&block) if block_given?
    platform.send(method, identifier.clone)
  end
  define_method("#{name}?") do
    return call_block(&block).exists? if block_given?
    platform.send(method, identifier.clone).exists?
  end
end

- (Object) svg(name, identifier = {:index => 0}, &block)

adds two methods - one to retrieve a svg, and another to check the svg's existence.

Examples:

svg(:circle, :id => 'circle')
# will generate 'circle_element', and 'circle?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a svg. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



1147
1148
1149
# File 'lib/page-object/accessors.rb', line 1147

def svg(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'svg_for', &block)
end

- (Object) table(name, identifier = {:index => 0}, &block)

adds three methods - one to return the text for the table, one to retrieve the table element, and another to check the table's existence. The existence method does not work on Selenium so it should not be called.

Examples:

table(:cart, :id => 'shopping_cart')
# will generate a 'cart', 'cart_element' and 'cart?' method

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a table. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



608
609
610
611
612
613
614
# File 'lib/page-object/accessors.rb', line 608

def table(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'table_for', &block)
  define_method(name) do
    return platform.table_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) text_area(name, identifier = {:index => 0}, &block) Also known as: textarea

adds four methods to the page object - one to set text in a text area, another to retrieve text from a text area, another to return the text area element, and another to check the text area's existence.

Examples:

text_area(:address, :id => "address")
# will generate 'address', 'address=', 'address_element',
# 'address?' methods

Parameters:

  • the (String)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a text area. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

    • :label => Watir and Selenium

  • optional

    block to be invoked when element method is called



277
278
279
280
281
282
283
284
285
286
287
# File 'lib/page-object/accessors.rb', line 277

def text_area(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'text_area_for', &block)
  define_method(name) do
    return platform.text_area_value_for identifier.clone unless block_given?
    self.send("#{name}_element").value
  end
  define_method("#{name}=") do |value|
    return platform.text_area_value_set(identifier.clone, value) unless block_given?
    self.send("#{name}_element").value = value
  end
end

- (Object) text_field(name, identifier = {:index => 0}, &block)

adds four methods to the page object - one to set text in a text field, another to retrieve text from a text field, another to return the text field element, another to check the text field's existence.

Examples:

text_field(:first_name, :id => "first_name")
# will generate 'first_name', 'first_name=', 'first_name_element',
# 'first_name?' methods

Parameters:

  • the (String)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a text field. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :label => Watir and Selenium

    • :name => Watir and Selenium

    • :text => Watir and Selenium

    • :title => Watir and Selenium

    • :value => Watir only

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



212
213
214
215
216
217
218
219
220
221
222
# File 'lib/page-object/accessors.rb', line 212

def text_field(name, identifier={:index => 0}, &block) 
  standard_methods(name, identifier, 'text_field_for', &block)
  define_method(name) do
    return platform.text_field_value_for identifier.clone unless block_given?
    self.send("#{name}_element").value
  end
  define_method("#{name}=") do |value|
    return platform.text_field_value_set(identifier.clone, value) unless block_given?
    self.send("#{name}_element").value = value
  end
end

- (Object) unordered_list(name, identifier = {:index => 0}, &block) Also known as: ul

adds three methods - one to return the text within the unorderd list, one to retrieve the unordered list element, and another to check it's existence.

Examples:

unordered_list(:menu, :id => 'main_menu')
# will generate 'menu', 'menu_element' and 'menu?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find an unordered list. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Selenium only

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



746
747
748
749
750
751
752
# File 'lib/page-object/accessors.rb', line 746

def unordered_list(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'unordered_list_for', &block)
  define_method(name) do
    return platform.unordered_list_text_for identifier.clone unless block_given?
    self.send("#{name}_element").text
  end
end

- (Object) video(name, identifier = {:index => 0}, &block)

adds two methods - one to return the video element and another to check the video's existence.

Examples:

video(:movie, :id => 'video_id')
# will generate 'movie_element' and 'movie?' methods

Parameters:

  • the (Symbol)

    name used for the generated methods

  • identifier (Hash) (defaults to: {:index => 0})

    how we find a video element. You can use a multiple paramaters by combining of any of the following except xpath. The valid keys are:

    • :class => Watir and Selenium

    • :css => Watir and Selenium

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :xpath => Watir and Selenium

  • optional

    block to be invoked when element method is called



1124
1125
1126
# File 'lib/page-object/accessors.rb', line 1124

def video(name, identifier={:index => 0}, &block)
  standard_methods(name, identifier, 'video_for', &block)
end

- (boolean) wait_for_expected_title(expected_title, timeout = ::PageObject.default_element_wait)

Creates a method that waits the expected_title of a page to match the actual.

Examples:

Specify 'Google' as the expected title of a page

expected_title "Google"
page.has_expected_title?

Parameters:

  • expected_title (String)

    the literal expected title for the page

  • expected_title (Regexp)

    the expected title pattern for the page

  • timeout (optional, Integer) (defaults to: ::PageObject.default_element_wait)

    default value is nil - do not wait

Returns:

  • (boolean)

Raises:

  • An exception if expected_title does not match actual title



67
68
69
70
71
72
73
74
75
76
77
78
79
80
# File 'lib/page-object/accessors.rb', line 67

def wait_for_expected_title(expected_title, timeout=::PageObject.default_element_wait)
  define_method("wait_for_expected_title?") do
    page_title = title
    has_expected_title = (expected_title === page_title)
    if not has_expected_title and not timeout.nil?
      wait_until(timeout, "Expected title '#{expected_title}' instead of '#{page_title}'") do 
        has_expected_title = (expected_title === page_title)
        has_expected_title
      end
    end
    raise "Expected title '#{expected_title}' instead of '#{page_title}'" unless has_expected_title
    has_expected_title
  end
end