Provide method for waiting for an in-page or cross-page condition to occur.

[dtognazzini]

With the addition of window.change_to and browser.find_document the standard pattern for command methods is like so:

def save!
  node.click_button('Submit')
  window.change_to(ResultantPage)
end

The above pattern says that the high level operation of "saving" the page is composed of clicking a Submit button and expecting that the browser window will change to a new page represented by the ResultantPage page object class.

There are times when performing this operation fails and results in a different page for displaying the errors. The code below encompasses the pattern for handling these cases:

def save!
  node.click_button('Submit')
  window.change_to(ResultantPage, self.class)
end

In the above code, the second argument to window.change_to() specifies that the high level save operation could result in a page represented by the the same class of the current page object. This is typical for Rails applications where submitting a form results in form errors and the resultant page is rendered from the same template.

In this case, just like the first case, a full page reload has occurred. Any references held to elements on the previous page are invalid.

This pattern works well with full page reloads. It would be nice to extend this pattern/convention to "AJAX pages" whereby form submissions are done via ajax and there is no full-page reload.