Module: PageObject

Includes:
ElementLocators, PagePopulator
Included in:
IndexedProperties::TableOfElements
Defined in:
lib/page-object.rb,
lib/page-object/version.rb,
lib/page-object/widgets.rb,
lib/page-object/elements.rb,
lib/page-object/accessors.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/page_populator.rb,
lib/page-object/elements/button.rb,
lib/page-object/elements/canvas.rb,
lib/page-object/elements/italic.rb,
lib/page-object/elements/option.rb,
lib/page-object/nested_elements.rb,
lib/page-object/platforms/watir.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/section_collection.rb,
lib/page-object/elements/date_field.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/javascript_framework_facade.rb,
lib/page-object/platforms/watir/page_object.rb

Overview

Module that when included adds functionality to a page object. This module will add numerous class and instance methods that you use to define and interact with web pages.

If we have a login page with a username and password textfield and a login button we might define our page like the one below. We can then interact with the object using the generated methods.

Examples:

Login page example

class LoginPage
  include PageObject

  text_field(:username, :id => 'user')
  text_field(:password, :id => 'pass')
  button(:login, :value => 'Login')
end

...

browser = Watir::Browser.new :firefox
login_page = LoginPage.new(browser)
login_page.username = 'cheezy'
login_page.password = 'secret'
login_page.login

See Also:

Defined Under Namespace

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

Constant Summary collapse

VERSION = 
'2.3.1'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from PagePopulator

#populate_page_with

Methods included from ElementLocators

#element

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args, &block) ⇒ Object 



48
49
50
51
52
53
54
 
# File 'lib/page-object.rb', line 48

def method_missing(method, *args, &block)
  if @root_element.respond_to?(method)
    @root_element.send(method, *args, &block)
  else
    super
  end
end

Instance Attribute Details

#browser ⇒ Object (readonly)

Returns the platform browser passed to the constructor.

Returns:

  • the platform browser passed to the constructor



61
62
63
 
# File 'lib/page-object.rb', line 61

def browser
  @browser
end

#platform ⇒ PageObject::WatirPageObject (readonly)

Returns the platform page object.

Returns:

  • (PageObject::WatirPageObject) —

    the platform page object



63
64
65
 
# File 'lib/page-object.rb', line 63

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



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

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



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

def self.default_element_wait
  @element_wait ||= 5
end

.default_element_wait=(timeout) ⇒ Object

Sets the default timeout for element level waits



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

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

.default_page_wait ⇒ Object

Returns the default timeout for page lavel waits



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

def self.default_page_wait
  @page_wait ||= 30
end

.default_page_wait=(timeout) ⇒ Object

Set the default timeout for page level waits



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

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

.included(cls) ⇒ Object 



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

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



124
125
126
 
# File 'lib/page-object.rb', line 124

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

.register_widget(widget_tag, widget_class, base_element_tag) ⇒ Object 



418
419
420
 
# File 'lib/page-object.rb', line 418

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



226
227
228
 
# File 'lib/page-object.rb', line 226

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



359
360
361
362
363
364
365
366
 
# File 'lib/page-object.rb', line 359

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



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

def back
  platform.back
end

#clear_cookies ⇒ Object

Clear the cookies from the browser



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

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



243
244
245
 
# File 'lib/page-object.rb', line 243

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

#current_url ⇒ Object

get the current page url



145
146
147
 
# File 'lib/page-object.rb', line 145

def current_url
  platform.current_url
end

#element_with_focus ⇒ Object

Find the element that has focus on the page



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

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"


273
274
275
276
 
# File 'lib/page-object.rb', line 273

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



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

def forward
  platform.forward
end

#html ⇒ Object

Returns the html of the current page



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

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

    • :index

    • :name

    • :class

  • 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.



296
297
298
 
# File 'lib/page-object.rb', line 296

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

    • :index

    • :name

    • :class

  • 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.



317
318
319
 
# File 'lib/page-object.rb', line 317

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



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

def initialize(root, visit=false)
  initialize_accessors if respond_to?(:initialize_accessors)
  initialize_browser(root)
  goto if visit && self.class.instance_methods(false).include?(:goto)
  initialize_page if respond_to?(:initialize_page)
end

#initialize_browser(root) ⇒ Object 



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

def initialize_browser(root)
  @root_element = PageObject::Platforms::Watir.root_element_for root
  @browser = root 
  @platform = PageObject::Platforms::Watir.create_page_object @browser
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.



333
334
335
336
337
338
339
340
341
342
343
344
 
# File 'lib/page-object.rb', line 333

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



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

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

#present? ⇒ Boolean

Check if root element exists and is visible

Returns:

  • (Boolean) 


414
415
416
 
# File 'lib/page-object.rb', line 414

def present?
  root.present?
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



261
262
263
 
# File 'lib/page-object.rb', line 261

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

#refresh ⇒ Object

Refresh to current page



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

def refresh
  platform.refresh
end

#respond_to_missing?(method, include_all = false) ⇒ Boolean

Returns:

  • (Boolean) 


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

def respond_to_missing?(method, include_all = false)
  @root_element && @root_element.respond_to?(method) || super
end

#save_screenshot(file_name) ⇒ Object

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



407
408
409
 
# File 'lib/page-object.rb', line 407

def save_screenshot(file_name)
  platform.save_screenshot file_name
end

#text ⇒ Object

Returns the text of the current page



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

def text
  platform.text
end

#title ⇒ Object

Returns the title of the current page



175
176
177
 
# File 'lib/page-object.rb', line 175

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



204
205
206
207
208
209
210
211
212
 
# File 'lib/page-object.rb', line 204

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.



191
192
193
 
# File 'lib/page-object.rb', line 191

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