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/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.2.5"

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
# File 'lib/page-object.rb', line 48

def method_missing(method, *args, &block)
  @root_element.send(method, *args, &block)
end

Instance Attribute Details

#browserObject (readonly)

Returns the platform browser passed to the constructor

Returns:

  • the platform browser passed to the constructor


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

def browser
  @browser
end

#platformPageObject::WatirPageObject (readonly)

Returns the platform page object

Returns:

  • (PageObject::WatirPageObject)

    the platform page object


59
60
61
# File 'lib/page-object.rb', line 59

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


134
135
136
# File 'lib/page-object.rb', line 134

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

.default_element_waitObject

Returns the default timeout for element level waits


111
112
113
# File 'lib/page-object.rb', line 111

def self.default_element_wait
  @element_wait ||= 5
end

.default_element_wait=(timeout) ⇒ Object

Sets the default timeout for element level waits


104
105
106
# File 'lib/page-object.rb', line 104

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

.default_page_waitObject

Returns the default timeout for page lavel waits


97
98
99
# File 'lib/page-object.rb', line 97

def self.default_page_wait
  @page_wait ||= 30
end

.default_page_wait=(timeout) ⇒ Object

Set the default timeout for page level waits


90
91
92
# File 'lib/page-object.rb', line 90

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

.included(cls) ⇒ Object


83
84
85
# File 'lib/page-object.rb', line 83

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


120
121
122
# File 'lib/page-object.rb', line 120

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

.register_widget(widget_tag, widget_class, base_element_tag) ⇒ Object


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

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


222
223
224
# File 'lib/page-object.rb', line 222

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


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

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

#backObject

Go back to the previous page


381
382
383
# File 'lib/page-object.rb', line 381

def back
  platform.back
end

#clear_cookiesObject

Clear the cookies from the browser


395
396
397
# File 'lib/page-object.rb', line 395

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


239
240
241
# File 'lib/page-object.rb', line 239

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

#current_urlObject

get the current page url


141
142
143
# File 'lib/page-object.rb', line 141

def current_url
  platform.current_url
end

#element_with_focusObject

Find the element that has focus on the page


367
368
369
# File 'lib/page-object.rb', line 367

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"

269
270
271
272
# File 'lib/page-object.rb', line 269

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

#forwardObject

Go forward to the next page


388
389
390
# File 'lib/page-object.rb', line 388

def forward
  platform.forward
end

#htmlObject

Returns the html of the current page


164
165
166
# File 'lib/page-object.rb', line 164

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.


292
293
294
# File 'lib/page-object.rb', line 292

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.


313
314
315
# File 'lib/page-object.rb', line 313

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


69
70
71
72
73
74
# File 'lib/page-object.rb', line 69

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


76
77
78
79
80
# File 'lib/page-object.rb', line 76

def initialize_browser(root)
  @root_element = PageObject::Platforms::Watir.root_element_for root
  @browser = root 
  @platform = PageObject::Platforms::Watir.create_page_object @browser
end

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.


329
330
331
332
333
334
335
336
337
338
339
340
# File 'lib/page-object.rb', line 329

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 the provided url

Parameters:

  • the (String)

    full url to navigate to


150
151
152
# File 'lib/page-object.rb', line 150

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


257
258
259
# File 'lib/page-object.rb', line 257

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

#refreshObject

Refresh to current page


374
375
376
# File 'lib/page-object.rb', line 374

def refresh
  platform.refresh
end

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

Returns:

  • (Boolean)

52
53
54
# File 'lib/page-object.rb', line 52

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.


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

def save_screenshot(file_name)
  platform.save_screenshot file_name
end

#textObject

Returns the text of the current page


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

def text
  platform.text
end

#titleObject

Returns the title of the current page


171
172
173
# File 'lib/page-object.rb', line 171

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


200
201
202
203
204
205
206
207
208
# File 'lib/page-object.rb', line 200

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.


187
188
189
# File 'lib/page-object.rb', line 187

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