Module: PageObject

Includes:
ElementLocators, LoadsPlatform, PagePopulator
Included in:
IndexedProperties::TableOfElements
Defined in:
lib/page-object.rb,
lib/page-object/widgets.rb,
lib/page_object/version.rb,
lib/page-object/elements.rb,
lib/page-object/sections.rb,
lib/page-object/accessors.rb,
lib/page-object/platforms.rb,
lib/page-object/elements/div.rb,
lib/page-object/page_factory.rb,
lib/page-object/elements/area.rb,
lib/page-object/elements/bold.rb,
lib/page-object/elements/form.rb,
lib/page-object/elements/link.rb,
lib/page-object/elements/span.rb,
lib/page-object/elements/audio.rb,
lib/page-object/elements/image.rb,
lib/page-object/elements/label.rb,
lib/page-object/elements/media.rb,
lib/page-object/elements/table.rb,
lib/page-object/elements/video.rb,
lib/page-object/javascript/yui.rb,
lib/page-object/loads_platform.rb,
lib/page-object/page_populator.rb,
lib/page-object/elements/button.rb,
lib/page-object/elements/canvas.rb,
lib/page-object/elements/option.rb,
lib/page-object/nested_elements.rb,
lib/page-object/element_locators.rb,
lib/page-object/elements/element.rb,
lib/page-object/elements/heading.rb,
lib/page-object/javascript/jquery.rb,
lib/page-object/locator_generator.rb,
lib/page-object/elements/check_box.rb,
lib/page-object/elements/list_item.rb,
lib/page-object/elements/paragraph.rb,
lib/page-object/elements/table_row.rb,
lib/page-object/elements/text_area.rb,
lib/page-object/indexed_properties.rb,
lib/page-object/elements/file_field.rb,
lib/page-object/elements/table_cell.rb,
lib/page-object/elements/text_field.rb,
lib/page-object/elements/select_list.rb,
lib/page-object/javascript/angularjs.rb,
lib/page-object/javascript/prototype.rb,
lib/page-object/elements/hidden_field.rb,
lib/page-object/elements/ordered_list.rb,
lib/page-object/elements/radio_button.rb,
lib/page-object/elements/unordered_list.rb,
lib/page-object/platforms/watir_webdriver.rb,
lib/page-object/javascript_framework_facade.rb,
lib/page-object/platforms/selenium_webdriver.rb,
lib/page-object/platforms/watir_webdriver/form.rb,
lib/page-object/platforms/watir_webdriver/link.rb,
lib/page-object/platforms/watir_webdriver/image.rb,
lib/page-object/platforms/watir_webdriver/table.rb,
lib/page-object/platforms/selenium_webdriver/form.rb,
lib/page-object/platforms/selenium_webdriver/link.rb,
lib/page-object/platforms/watir_webdriver/element.rb,
lib/page-object/platforms/selenium_webdriver/image.rb,
lib/page-object/platforms/selenium_webdriver/table.rb,
lib/page-object/platforms/selenium_webdriver/button.rb,
lib/page-object/platforms/watir_webdriver/check_box.rb,
lib/page-object/platforms/watir_webdriver/table_row.rb,
lib/page-object/platforms/watir_webdriver/text_area.rb,
lib/page-object/platforms/selenium_webdriver/element.rb,
lib/page-object/platforms/watir_webdriver/file_field.rb,
lib/page-object/platforms/watir_webdriver/text_field.rb,
lib/page-object/platforms/watir_webdriver/page_object.rb,
lib/page-object/platforms/watir_webdriver/select_list.rb,
lib/page-object/platforms/selenium_webdriver/check_box.rb,
lib/page-object/platforms/selenium_webdriver/table_row.rb,
lib/page-object/platforms/selenium_webdriver/text_area.rb,
lib/page-object/platforms/watir_webdriver/ordered_list.rb,
lib/page-object/platforms/watir_webdriver/radio_button.rb,
lib/page-object/platforms/selenium_webdriver/file_field.rb,
lib/page-object/platforms/selenium_webdriver/text_field.rb,
lib/page-object/platforms/selenium_webdriver/page_object.rb,
lib/page-object/platforms/selenium_webdriver/select_list.rb,
lib/page-object/platforms/watir_webdriver/unordered_list.rb,
lib/page-object/platforms/selenium_webdriver/ordered_list.rb,
lib/page-object/platforms/selenium_webdriver/radio_button.rb,
lib/page-object/platforms/selenium_webdriver/unordered_list.rb,
lib/page-object/platforms/selenium_webdriver/surrogate_selenium_element.rb

Overview

See Also:

Defined Under Namespace

Modules: Accessors, ElementLocators, Elements, IndexedProperties, Javascript, JavascriptFrameworkFacade, LoadsPlatform, LocatorGenerator, NestedElements, PageFactory, PagePopulator, Platforms, Widgets Classes: SectionCollection

Constant Summary collapse

VERSION = 
'1.1.3'
DATE = 
'2015-06-20'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from PagePopulator

#populate_page_with

Methods included from ElementLocators

#element

Methods included from LoadsPlatform

#adapter_for, #browser_for, #browser_root_for, #load_platform, #root_element_for

Instance Attribute Details

#browser ⇒ Watir::Browser or Selenium::WebDriver::Driver (readonly)

Returns the platform browser passed to the constructor.

Returns:

  • (Watir::Browser or Selenium::WebDriver::Driver) —

    the platform browser passed to the constructor



54
55
56
 
# File 'lib/page-object.rb', line 54

def browser
  @browser
end

#platform ⇒ PageObject::WatirPageObject or PageObject::SeleniumPageObject (readonly)

Returns the platform page object.

Returns:

  • (PageObject::WatirPageObject or PageObject::SeleniumPageObject) —

    the platform page object



56
57
58
 
# File 'lib/page-object.rb', line 56

def platform
  @platform
end

Class Method Details

.add_framework(key, framework) ⇒ Object

Add a new javascript framework to page-object. The module passed in must adhere to the same prototype as the JQuery and Prototype modules.

subsequent calls the required actions.

Parameters:

  • the (Symbol) —

    name used to reference the framework in

  • a (Module) —

    module that has the necessary methods to perform



131
132
133
 
# File 'lib/page-object.rb', line 131

def self.add_framework(key, framework)
  PageObject::JavascriptFrameworkFacade.add_framework(key, framework)
end

.default_element_wait ⇒ Object

Returns the default timeout for element level waits



108
109
110
 
# File 'lib/page-object.rb', line 108

def self.default_element_wait
  @element_wait ||= 5
end

.default_element_wait=(timeout) ⇒ Object

Sets the default timeout for element level waits



101
102
103
 
# File 'lib/page-object.rb', line 101

def self.default_element_wait=(timeout)
  @element_wait = timeout
end

.default_page_wait ⇒ Object

Returns the default timeout for page lavel waits



94
95
96
 
# File 'lib/page-object.rb', line 94

def self.default_page_wait
  @page_wait ||= 30
end

.default_page_wait=(timeout) ⇒ Object

Set the default timeout for page level waits



87
88
89
 
# File 'lib/page-object.rb', line 87

def self.default_page_wait=(timeout)
  @page_wait = timeout
end

.included(cls) ⇒ Object 



80
81
82
 
# File 'lib/page-object.rb', line 80

def self.included(cls)
  cls.extend PageObject::Accessors
end

.javascript_framework=(framework) ⇒ Object

Set the javascript framework to use when determining number of ajax requests. Valid frameworks are :jquery, :prototype, :yui, and :angularjs



117
118
119
 
# File 'lib/page-object.rb', line 117

def self.javascript_framework=(framework)
  PageObject::JavascriptFrameworkFacade.framework = framework
end

.register_widget(widget_tag, widget_class, base_element_tag) ⇒ Object 



404
405
406
 
# File 'lib/page-object.rb', line 404

def self.register_widget(widget_tag, widget_class, base_element_tag)
  Widgets.register_widget(widget_tag, widget_class, base_element_tag)
end

Instance Method Details

#alert(frame = nil, &block) ⇒ String

Override the normal alert popup so it does not occur.

Examples:

message = @page.alert do
  @page.button_that_causes_alert
end

Parameters:

  • frame (defaults to: nil) —

    optional parameter used when alert is nested within a frame

  • block —

    a block that has the call that will cause the alert to display

Returns:

  • (String) —

    the message that was contained in the alert



219
220
221
 
# File 'lib/page-object.rb', line 219

def alert(frame=nil, &block)
  platform.alert(frame, &block)
end

#attach_to_window(identifier, &block) ⇒ Object

Attach to a running window. You can locate the window using either the window’s title or url. If it fails to connect to a window it will pause for 1 second and try again.

be the entire url - it can just be the page name like index.html calling window

Examples:

page.attach_to_window(:title => "other window's title")

Parameters:

  • either (Hash) —

    :title or :url of the other window. The url does not need to

  • block —

    if present the block is executed and then execution is returned to the



352
353
354
355
356
357
358
359
 
# File 'lib/page-object.rb', line 352

def attach_to_window(identifier, &block)
  begin
    platform.attach_to_window(identifier, &block)
  rescue
    sleep 1
    platform.attach_to_window(identifier, &block)
  end
end

#back ⇒ Object

Go back to the previous page



378
379
380
 
# File 'lib/page-object.rb', line 378

def back
  platform.back
end

#clear_cookies ⇒ Object

Clear the cookies from the browser



392
393
394
 
# File 'lib/page-object.rb', line 392

def clear_cookies
  platform.clear_cookies
end

#confirm(response, frame = nil, &block) ⇒ String

Override the normal confirm popup so it does not occur.

Examples:

message = @popup.confirm(true) do
  @page.button_that_causes_confirm
end

Parameters:

  • what (bool) —

    response you want to return back from the confirm popup

  • frame (defaults to: nil) —

    optional parameter used when the confirm is nested within a frame

  • block —

    a block that has the call that will cause the confirm to display

Returns:

  • (String) —

    the message that was prompted in the confirm



236
237
238
 
# File 'lib/page-object.rb', line 236

def confirm(response, frame=nil, &block)
  platform.confirm(response, frame, &block)
end

#current_url ⇒ Object

get the current page url



138
139
140
 
# File 'lib/page-object.rb', line 138

def current_url
  platform.current_url
end

#element_with_focus ⇒ Object

Find the element that has focus on the page



364
365
366
 
# File 'lib/page-object.rb', line 364

def element_with_focus
  platform.element_with_focus
end

#execute_script(script, *args) ⇒ Object

Execute javascript on the browser

Examples:

Get inner HTML of element

span = @page.span_element
@page.execute_script "return arguments[0].innerHTML", span
#=> "Span innerHTML"


266
267
268
269
 
# File 'lib/page-object.rb', line 266

def execute_script(script, *args)
  args.map! { |e| e.kind_of?(PageObject::Elements::Element) ? e.element : e }
  platform.execute_script(script, *args)    
end

#forward ⇒ Object

Go forward to the next page



385
386
387
 
# File 'lib/page-object.rb', line 385

def forward
  platform.forward
end

#html ⇒ Object

Returns the html of the current page



161
162
163
 
# File 'lib/page-object.rb', line 161

def html
  platform.html
end

#in_frame(identifier, frame = nil, &block) ⇒ Object

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_element(: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

    • :class => 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.



289
290
291
 
# File 'lib/page-object.rb', line 289

def in_frame(identifier, frame=nil, &block)
  platform.in_frame(identifier, frame, &block)
end

#in_iframe(identifier, frame = nil, &block) ⇒ Object

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_iframe by passing the frame to the next level.

Examples:

in_iframe(:id => 'iframe_id') do |iframe|
  text_field_element(:id => 'ifname', :frame => iframe)
end

Parameters:

  • identifier (Hash) —

    how we find the iframe. The valid keys are:

    • :id => Watir and Selenium

    • :index => Watir and Selenium

    • :name => Watir and Selenium

    • :class => 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.



310
311
312
 
# File 'lib/page-object.rb', line 310

def in_iframe(identifier, frame=nil, &block)
  platform.in_iframe(identifier, frame, &block)
end

#initialize(root, visit = false) ⇒ Object

Construct a new page object. Prior to browser initialization it will call a method named initialize_accessors if it exists. Upon initialization of the page it will call a method named initialize_page if it exists.

Parameters:

  • the (Watir::Browser, Watir::HTMLElement or Selenium::WebDriver::Driver, Selenium::WebDriver::Element) —

    platform browser/element to use

  • open (bool) —

    the page if page_url is set



66
67
68
69
70
71
 
# File 'lib/page-object.rb', line 66

def initialize(root, visit=false)
  initialize_accessors if respond_to?(:initialize_accessors)
  initialize_browser(root)
  goto if visit && respond_to?(:goto)
  initialize_page if respond_to?(:initialize_page)
end

#initialize_browser(root) ⇒ Object 



73
74
75
76
77
 
# File 'lib/page-object.rb', line 73

def initialize_browser(root)
  @root_element = root_element_for root, PageObject::Platforms.get
  @browser = browser_for root, PageObject::Platforms.get
  include_platform_driver(root)
end

#modal_dialog(&block) ⇒ Object

Override the normal showModalDialog call is it opens a window instead of a dialog. You will need to attach to the new window in order to continue.

Examples:

@page.modal_dialog do
  @page.action_that_spawns_the_modal
end

Parameters:

  • block —

    a block that contains the call that will cause the modal dialog.



326
327
328
329
330
331
332
333
334
335
336
337
 
# File 'lib/page-object.rb', line 326

def modal_dialog(&block)
  script =
      %Q{
    window.showModalDialog = function(sURL, vArguments, sFeatures) {
      window.dialogArguments = vArguments;
      modalWin = window.open(sURL, 'modal', sFeatures);
      return modalWin;
    }
  }
  browser.execute_script script
  yield if block_given?
end

#navigate_to(url) ⇒ Object

navigate to the provided url

Parameters:

  • the (String) —

    full url to navigate to



147
148
149
 
# File 'lib/page-object.rb', line 147

def navigate_to(url)
  platform.navigate_to(url)
end

#prompt(answer, frame = nil, &block) ⇒ Hash

Override the normal prompt popup so it does not occur.

:default_value contains the default value for the prompt if provided

Examples:

message = @popup.prompt("Some Value") do
  @page.button_that_causes_prompt
end

Parameters:

  • the (string) —

    value returned to the caller of the prompt

  • frame (defaults to: nil) —

    optional parameter used with the prompt is nested within a frame

  • block —

    a block that has the call that will cause the prompt to display

Returns:

  • (Hash) —

    A has containing two keys - :message contains the prompt message and



254
255
256
 
# File 'lib/page-object.rb', line 254

def prompt(answer, frame=nil, &block)
  platform.prompt(answer, frame, &block)
end

#refresh ⇒ Object

Refresh to current page



371
372
373
 
# File 'lib/page-object.rb', line 371

def refresh
  platform.refresh
end

#save_screenshot(file_name) ⇒ Object

Save the current screenshot to the provided url. File is saved as a png file.



400
401
402
 
# File 'lib/page-object.rb', line 400

def save_screenshot(file_name)
  platform.save_screenshot file_name
end

#text ⇒ Object

Returns the text of the current page



154
155
156
 
# File 'lib/page-object.rb', line 154

def text
  root.text
end

#title ⇒ Object

Returns the title of the current page



168
169
170
 
# File 'lib/page-object.rb', line 168

def title
  platform.title
end

#wait_for_ajax(timeout = 30, message = nil) ⇒ Object

Wait until there are no pending ajax requests. This requires you to set the javascript framework in advance.

the timeout duration.

Parameters:

  • the (Numeric) —

    amount of time to wait for the block to return true.

  • the (String) —

    message to include with the error if we exceed



197
198
199
200
201
202
203
204
205
 
# File 'lib/page-object.rb', line 197

def wait_for_ajax(timeout = 30, message = nil)
  end_time = ::Time.now + timeout
  until ::Time.now > end_time
    return if browser.execute_script(::PageObject::JavascriptFrameworkFacade.pending_requests) == 0
    sleep 0.5
  end
  message = "Timed out waiting for ajax requests to complete" unless message
  raise message
end

#wait_until(timeout = PageObject.default_page_wait, message = nil, &block) ⇒ Object

Wait until the block returns true or times out

Examples:

@page.wait_until(5, 'Success not found on page') do
  @page.text.include? 'Success'
end

Parameters:

  • the (Numeric) —

    amount of time to wait for the block to return true.

  • the (String) —

    message to include with the error if we exceed the timeout duration.

  • block —

    the block to execute. It should return true when successful.



184
185
186
 
# File 'lib/page-object.rb', line 184

def wait_until(timeout = PageObject.default_page_wait, message = nil, &block)
  platform.wait_until(timeout, message, &block)
end