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
 = LoginPage.new(browser)
.username = 'cheezy'
.password = 'secret'
.

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.6"

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)


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

def browser
  @browser
end

#platformPageObject::WatirPageObject (readonly)


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.


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

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")

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

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

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

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.


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

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


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

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


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.


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

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