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 122
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 100
def self.default_element_wait
  @element_wait ||= 5
end

Sets the default timeout for element level waits

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

Returns the default timeout for page lavel waits

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

Set the default timeout for page level waits

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

@private

# File lib/page-object.rb, line 72
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 and :prototype

# File lib/page-object.rb, line 108
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 or Selenium::WebDriver::Driver] the platform browser to use @param [bool] open the page if page_url is set

# File lib/page-object.rb, line 59
def initialize(browser, visit=false)
  initialize_accessors if respond_to?(:initialize_accessors)
  initialize_browser(browser)
  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 210
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 343
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 369
def back
  platform.back
end

Clear the cookies from the browser

# File lib/page-object.rb, line 383
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 227
def confirm(response, frame=nil, &block)
  platform.confirm(response, frame, &block)
end

get the current page url

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

Find the element that has focus on the page

# File lib/page-object.rb, line 355
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 257
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 376
def forward
  platform.forward
end

Returns the html of the current page

# File lib/page-object.rb, line 152
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 280
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 301
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 317
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 138
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 245
def prompt(answer, frame=nil, &block)
  platform.prompt(answer, frame, &block)
end

Refresh to current page

# File lib/page-object.rb, line 362
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 391
def save_screenshot(file_name)
  platform.save_screenshot file_name
end

Returns the text of the current page

# File lib/page-object.rb, line 145
def text
  platform.text
end

Returns the title of the current page

# File lib/page-object.rb, line 159
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 188
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 175
def wait_until(timeout = PageObject.default_page_wait, message = nil, &block)
  platform.wait_until(timeout, message, &block)
end