Creating custom Pages

Custom pages allow you to do two things:

• Create references to your pages, making it easier to update your tests in the future;
• Create aliases for your page elements.

Consider this simple test scenario:

Scenario 1 - Searching for Hello World
Given
    I go to "http://www.google.com"
When
    I fill "q" textbox with "Hello World"
    And I click "btnG" button and wait
Then
    I see "Hello World - Google Search" title

Custom pages allow you to write the very same scenario in a much more readable way:

Scenario 1 - Searching for Hello World
Given
    I go to Search Page
When
    I fill "query" textbox with "Hello World"
    And I click "Google Search" button and wait
Then
    I see "Hello World - Google Search" title

Notice that we have changed the test to go to “Search Page”, and the textbox and button elements are now being called “query” and “Google Search” respectively.

Pyccuracy by default looks for elements that have id or name equal to the text informed. In the first example, the “Google Search” button was being called “btnG”, but we should use the real button label to make it easier to read and write the tests.

To do that, you will need to:

1) Implement a class that inherits from Page

from pyccuracy.page import Page

class SearchPage(Page):
    pass

2) Define the URL for the page

from pyccuracy.page import Page

class SearchPage(Page):
    url = '/'

This is what tells Pyccuracy the address it should go to when you go to a page in your tests. The name of the page you will go to is deducted from the Python class name.

For instance, if your class is called ShoppingCartPage, then you will say in your tests:

I go to Shopping Cart Page

3) Implement the method “register” and define aliases for the page elements

from pyccuracy.page import Page

class SearchPage(Page):
    url = '/'
    
    def register(self):
        self.register_element("query", "//input[@id='q']")
        self.register_element("Google Search", "//input[@id='btnG']")
        self.quick_register("My Div", "div.myclass")

You can create as many aliases as you want, just be careful with name conflicts (if you create two aliases with the same name, only the last one will be considered).

Notice that there are two ways of registering your elements:

3.1) register_element (XPath selector)

The register_element method lets you register elements using its XPath. Just choose an alias to call on your tests and the XPath of the element.

You should try really hard to use flexible XPath codes, for instance:

//div[contains(@class,'write')]

instead of

/html/body/div/div[2]/div[3]/div

This prevents your tests from breaking on every small HTML change, and besides that, are much more comprehensive and easy to maintain.

If you are not used to XPath, here is a good reference and you will also find useful to use Firebug and XPather Firefox plugins.

3.2) quick_register (CSS3 selector)

If you’d rather use CSS 3 to match your elements you can use quick_register. Pyccuracy will convert the CSS 3 selector to an XPath for you. This is the preferred way of selecting elements due to being a lot easier to read and maintain.

4) Using the custom Pages

Just put the custom Page code in a .py file (in this case I would create a “search_page.py” file) and put the file in the same directory your tests are. When you execute your tests, Pyccuracy will look for custom Pages in the tests directory before executing them.

For organization sake, you may want to put your Pages in a separate dir. If you want to do that, when you call pyccuracy_console inform the -P parameter, that is the directory where the custom Pages are:

$ pyccuracy_console -P tests/acceptance/pages