module PageObject

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

@param [Symbol] the name used to reference the framework in subsequent calls @param [Module] a module that has the necessary methods to perform the required actions.

# File lib/page-object.rb, line 131
def self.add_framework(key, framework)
  PageObject::JavascriptFrameworkFacade.add_framework(key, framework)
end

Returns the default timeout for element level waits

# File lib/page-object.rb, line 108
def self.default_element_wait
  @element_wait ||= 5
end

Sets the default timeout for element level waits

# File lib/page-object.rb, line 101
def self.default_element_wait=(timeout)
  @element_wait = timeout
end

Returns the default timeout for page lavel waits

# File lib/page-object.rb, line 94
def self.default_page_wait
  @page_wait ||= 30
end

Set the default timeout for page level waits

# File lib/page-object.rb, line 87
def self.default_page_wait=(timeout)
  @page_wait = timeout
end

@private

# File lib/page-object.rb, line 80
def self.included(cls)
  cls.extend PageObject::Accessors
end

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

# File lib/page-object.rb, line 117
def self.javascript_framework=(framework)
  PageObject::JavascriptFrameworkFacade.framework = framework
end

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.

@param [Watir::Browser, Watir::HTMLElement or Selenium::WebDriver::Driver, Selenium::WebDriver::Element] the platform browser/element to use @param [bool] open the page if page_url is set

# 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

Override the normal alert popup so it does not occur.

@example

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

@param frame optional parameter used when alert is nested within a frame @param block a block that has the call that will cause the alert to display @return [String] the message that was contained in the alert

# File lib/page-object.rb, line 219
def alert(frame=nil, &block)
  platform.alert(frame, &block)
end

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.

@example

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

@param [Hash] either :title or :url of the other window. The url does not need to be the entire url - it can just be the page name like index.html @param block if present the block is executed and then execution is returned to the calling window

# 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

Go back to the previous page

# File lib/page-object.rb, line 378
def back
  platform.back
end

Clear the cookies from the browser

# File lib/page-object.rb, line 392
def clear_cookies
  platform.clear_cookies
end

Override the normal confirm popup so it does not occur.

@example

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

@param [bool] what response you want to return back from the confirm popup @param frame optional parameter used when the confirm is nested within a frame @param block a block that has the call that will cause the confirm to display @return [String] the message that was prompted in the confirm

# File lib/page-object.rb, line 236
def confirm(response, frame=nil, &block)
  platform.confirm(response, frame, &block)
end

get the current page url

# File lib/page-object.rb, line 138
def current_url
  platform.current_url
end

Find the element that has focus on the page

# File lib/page-object.rb, line 364
def element_with_focus
  platform.element_with_focus
end

Execute javascript on the browser

@example Get inner HTML of element

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

# 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

Go forward to the next page

# File lib/page-object.rb, line 385
def forward
  platform.forward
end

Returns the html of the current page

# File lib/page-object.rb, line 161
def html
  platform.html
end

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.

@example

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

@param [Hash] identifier how we find the frame. The valid keys are:

* :id => Watir and Selenium
* :index => Watir and Selenium
* :name => Watir and Selenium
* :class => Watir only

@param frame passed from a previous call to in_frame. Used to nest calls @param block that contains the calls to elements that exist inside the frame.

# File lib/page-object.rb, line 289
def in_frame(identifier, frame=nil, &block)
  platform.in_frame(identifier, frame, &block)
end

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.

@example

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

@param [Hash] identifier how we find the iframe. The valid keys are:

* :id => Watir and Selenium
* :index => Watir and Selenium
* :name => Watir and Selenium
* :class => Watir only

@param frame passed from a previous call to in_iframe. Used to nest calls @param block that contains the calls to elements that exist inside the iframe.

# File lib/page-object.rb, line 310
def in_iframe(identifier, frame=nil, &block)
  platform.in_iframe(identifier, frame, &block)
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.

@example

@page.modal_dialog do
  @page.action_that_spawns_the_modal
end

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

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

@param [String] the full url to navigate to

# File lib/page-object.rb, line 147
def navigate_to(url)
  platform.navigate_to(url)
end

Override the normal prompt popup so it does not occur.

@example

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

@param [string] the value returned to the caller of the prompt @param frame optional parameter used with the prompt is nested within a frame @param block a block that has the call that will cause the prompt to display @return [Hash] A has containing two keys - :message contains the prompt message and :default_value contains the default value for the prompt if provided

# File lib/page-object.rb, line 254
def prompt(answer, frame=nil, &block)
  platform.prompt(answer, frame, &block)
end

Refresh to current page

# File lib/page-object.rb, line 371
def refresh
  platform.refresh
end

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

# File lib/page-object.rb, line 400
def save_screenshot(file_name)
  platform.save_screenshot file_name
end

Returns the text of the current page

# File lib/page-object.rb, line 154
def text
  root.text
end

Returns the title of the current page

# File lib/page-object.rb, line 168
def title
  platform.title
end

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

@param [Numeric] the amount of time to wait for the block to return true. @param [String] the message to include with the error if we exceed the timeout duration.

# 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 the block returns true or times out

@example

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

@param [Numeric] the amount of time to wait for the block to return true. @param [String] the message to include with the error if we exceed the timeout duration. @param block the block to execute. It should return true when successful.

# 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