From 1565c88f40d9f795a879ad457628958d43ef6a3f Mon Sep 17 00:00:00 2001 From: Greg Meece Date: Fri, 11 Aug 2017 11:19:59 -0500 Subject: [PATCH 1/4] Changed README.rs to README.md For some reason, Github doesn't seem to honor syntax highlighting, etc. so I converted the reStructuredText to Markdown. --- README.md | 125 ++++++++++++++++++++++++++++++++++++ README.rst | 185 ----------------------------------------------------- 2 files changed, 125 insertions(+), 185 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 0000000..ebc4d55 --- /dev/null +++ b/README.md @@ -0,0 +1,125 @@ +# PageObjectLibrary + +## Overview + +PageObjectLibrary is a lightweight [robot framework] keyword library that makes it possible to use the page object pattern when testing web pages with the keyword based approach of robot framework. + +## Installing + +```bash +pip install --upgrade robotframework-pageobjectlibrary +``` + +## Source code + +The source code is hosted on github at the following url: + +* https://github.com/boakley/robotframework-pageobjectlibrary.git + +## Running the demo + +In the github repository is a small demonstration suite that includes a self-contained webserver and web site. + +For the demo to run you must have robotframework 2.9+ and Selenium2Library installed. You must also have cloned the github repository to have access to the demo files. + +To run the demo, clone the github repository, cd to the folder that contains this file, and then run the following command: : + +```bash +robot -d demo/results demo +``` +### A simple tutorial + +For a simple tutorial, see + +## How it works + +The page object library is quite simple. Page object classes are implemented as standard robot keyword libraries, and relies on robot frameworks built-in [Set library search order keyword]. + +The core concept is that when you use PageObjectLibrary keywords to go to a page or assert you are on a specific page, the keyword will automatically load the library for that page and put it at the front of the library search order, guaranteeing that the page object keywords are available to your test case. + +## Why page objects makes writing tests easier + +The purpose of the page object pattern is to encapsulate the knowledge of how a web page is constructed into an object. Your test uses the object as an interface to the application, isolating your test cases from the details of the implementation of a page. + +With page objects, developers are free to modify web pages as much as they want, and the only thing they need to do to keep existing tests from failing is to update the page object class. Because test cases aren’t directly tied to the implementation, they become more stable and more resistent to change as the website matures. + +## A typical test without page objects + +With traditional testing using Selenium, a simple login test might look something like the following: (using the pipe-separated format for clarity): + +```robotframework +*** Test Cases *** +| Login with valid credentials +| | Go to | ${ROOT}/Login.html +| | Wait for page to contain | id=id_username +| | Input text | id=id_username | ${USERNAME} +| | Input text | id=id_password | ${PASSWORD} +| | Click button | id=id_form_submit +| | Wait for page to contain | Your Dashboard +| | Location should be | ${ROOT}/dashboard.html +``` + +Notice how this test is tightly coupled to the implementation of the page. It has to know that the input field has an id of “id_username”, and the password field has an id of “id_password”. It also has to know the URL of the page being tested. + +Of course, you can put those hard-coded values into variables and import them from a resource file or environment variables, which makes it easier to update tests when locators change. However, there’s still the overhead of additional keywords that are often required to make a test robust, such as waiting for a page to be reloaded. The provided PageObject superclass handles some of those details for you. + +## The same test, using page objects + +Using page objects, the same test could be written like this: + +```robotframework +*** Test Cases *** +| Login with valid credentials +| | Go to page | LoginPage +| | Login as a normal user +| | The current page should be | DashboardPage +``` + +Notice how there are no URLs or element locators in the test whatsoever, and that we’ve been able to eliminate some keywords that typically are necessary for selenium to work but which aren’t part of the test logic *per se*. What we end up with is test case that is nearly indistinguishable from typical acceptance criteria of an agile story. + +## Writing a Page Object class + +Page objects are simple python classes that inherit from `PageObjectLibrary.PageObject`. There are only a couple of requirements for the class: + +- The class should define a variable named PAGE\_TITLE +- The class should define a variable named PAGE\_URL which is a URI relative to the site root. + +By inheriting from `PageObjectLibrary.PageObject`, methods have access to the folloing special object attributes: + +- `self.se2lib` - a reference to an instance of Selenium2Library. With this you can call any of the Selenium2Library keywords via their python method names (eg: self.se2lib.input\_text) +- `self.browser` - a reference to the webdriver object created when a browser was opened by Selenium2Library. With this you can bypass Selenium2Library and directly call all of the functions provided by the core selenium library. +- `self.locator` - a wrapper around the `_locators` dictionary of the page. This dictionary can contain all of the locators used by the page object keywords. `self.locators` adds the ability to access the locators with dot notation rather than the slightly more verbose dictionary syntax (eg: `self.locator.username` vs `self._locators["username"]`. + +## An example page object + +A page object representing a login page might look like this: + +```python +from PageObjectLibrary import PageObject + +class LoginPage(PageObject): + PAGE_TITLE = "Login - PageObjectLibrary Demo" + PAGE_URL = "/login.html" + + _locators = { + "username": "id=id_username", + "password": "id=id_password", + "submit_button": "id=id_submit", + } + + def enter_username(self, username): + """Enter the given string into the username field""" + self.se2lib.input_text(self.locator.username, username) + + def enter_password(self,password): + """Enter the given string into the password field""" + self.se2lib.input_text(self.locator.password, password) + + def click_the_submit_button(self): + """Click the submit button, and wait for the page to reload""" + with self._wait_for_page_refresh(): + self.se2lib.click_button(self.locator.submit_button) +``` + + [robot framework]: http://www.robotframework.org + [Set library search order keyword]: http://robotframework.org/robotframework/latest/libraries/BuiltIn.html#Set%20Library%20Search%20Order diff --git a/README.rst b/README.rst deleted file mode 100644 index 4703be8..0000000 --- a/README.rst +++ /dev/null @@ -1,185 +0,0 @@ -PageObjectLibrary -================= - -Overview --------- - -PageObjectLibrary is a lightweight `robot -framework `__ keyword library that makes -it possible to use the page object pattern when testing web pages with -the keyword based approach of robot framework. - -Installing ----------- - -:: - - $ pip install --upgrade robotframework-pageobjectlibrary - -Source code ------------ - -The source code is hosted on github at the following url: - -:: - - [https://github.com/boakley/robotframework-pageobjectlibrary.git] - -Running the demo ----------------- - -In the github repository is a small demonstration suite that includes a -self-contained webserver and web site. - -For the demo to run you must have robotframework 2.9+ and -Selenium2Library installed. You must also have cloned the github -repository to have access to the demo files. - -To run the demo, clone the github repository, cd to the folder that -contains this file, and then run the following command: -:: - - $ robot -d demo/results demo - -A simple tutorial ----------------- - -For a simple tutorial, see https://github.com/boakley/robotframework-pageobjectlibrary/wiki/Tutorial - -How it works ------------- - -The page object library is quite simple. Page object classes are -implemented as standard robot keyword libraries, and relies on robot -frameworks built-in `Set library search order keyword -`_. - -The core concept is that when you use PageObjectLibrary keywords to go -to a page or assert you are on a specific page, the keyword will -automatically load the library for that page and put it at the front of -the library search order, guaranteeing that the page object keywords are -available to your test case. - -Why page objects makes writing tests easier -------------------------------------------- - -The purpose of the page object pattern is to encapsulate the knowledge -of how a web page is constructed into an object. Your test uses the -object as an interface to the application, isolating your test cases -from the details of the implementation of a page. - -With page objects, developers are free to modify web pages as much as -they want, and the only thing they need to do to keep existing tests -from failing is to update the page object class. Because test cases -aren't directly tied to the implementation, they become more stable and -more resistent to change as the website matures. - -A typical test without page objects ------------------------------------ - -With traditional testing using Selenium, a simple login test might look -something like the following: (using the pipe-separated format for -clarity): - -:: - - *** Test Cases *** - | Login with valid credentials - | | Go to | ${ROOT}/Login.html - | | Wait for page to contain | id=id_username - | | Input text | id=id_username | ${USERNAME} - | | Input text | id=id_password | ${PASSWORD} - | | Click button | id=id_form_submit - | | Wait for page to contain | Your Dashboard - | | Location should be | ${ROOT}/dashboard.html - -Notice how this test is tightly coupled to the implementation of the -page. It has to know that the input field has an id of "id\_username", -and the password field has an id of "id\_password". It also has to know -the URL of the page being tested. - -Of course, you can put those hard-coded values into variables and import -them from a resource file or environment variables, which makes it -easier to update tests when locators change. However, there's still the -overhead of additional keywords that are often required to make a test -robust, such as waiting for a page to be reloaded. The provided -PageObject superclass handles some of those details for you. - -The same test, using page objects ---------------------------------- - -Using page objects, the same test could be written like this: - -:: - - *** Test Cases *** - | Login with valid credentials - | | Go to page | LoginPage - | | Login as a normal user - | | The current page should be | DashboardPage - -Notice how there are no URLs or element locators in the test whatsoever, -and that we've been able to eliminate some keywords that typically are -necessary for selenium to work but which aren't part of the test logic -*per se*. What we end up with is test case that is nearly -indistinguishable from typical acceptance criteria of an agile story. - -Writing a Page Object class -=========================== - -Page objects are simple python classes that inherit from -``PageObjectLibrary.PageObject``. There are only a couple of -requirements for the class: - -- The class should define a variable named PAGE\_TITLE -- The class should define a variable named PAGE\_URL which is a URI - relative to the site root. - -By inheriting from ``PageObjectLibrary.PageObject``, methods have access -to the folloing special object attributes: - -- ``self.se2lib`` - a reference to an instance of Selenium2Library. - With this you can call any of the Selenium2Library keywords via their - python method names (eg: self.se2lib.input\_text) -- ``self.browser`` - a reference to the webdriver object created when a - browser was opened by Selenium2Library. With this you can bypass - Selenium2Library and directly call all of the functions provided by - the core selenium library. -- ``self.locator`` - a wrapper around the ``_locators`` dictionary of - the page. This dictionary can contain all of the locators used by the - page object keywords. ``self.locators`` adds the ability to access - the locators with dot notation rather than the slightly more verbose - dictionary syntax (eg: ``self.locator.username`` vs - ``self._locators["username"]``. - -An example page object ----------------------- - -A page object representing a login page might look like this: - -:: - - from PageObjectLibrary import PageObject - - class LoginPage(PageObject): - PAGE_TITLE = "Login - PageObjectLibrary Demo" - PAGE_URL = "/login.html" - - _locators = { - "username": "id=id_username", - "password": "id=id_password", - "submit_button": "id=id_submit", - } - - def enter_username(self, username): - """Enter the given string into the username field""" - self.se2lib.input_text(self.locator.username, username) - - def enter_password(self,password): - """Enter the given string into the password field""" - self.se2lib.input_text(self.locator.password, password) - - def click_the_submit_button(self): - """Click the submit button, and wait for the page to reload""" - with self._wait_for_page_refresh(): - self.se2lib.click_button(self.locator.submit_button) From 84c9a726d348d4b9433f849d41c5cbc6fa03a851 Mon Sep 17 00:00:00 2001 From: Greg Meece Date: Fri, 11 Aug 2017 11:29:27 -0500 Subject: [PATCH 2/4] README - Title-Cased Robot Framework Respect, yo! --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ebc4d55..7fda2fe 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ## Overview -PageObjectLibrary is a lightweight [robot framework] keyword library that makes it possible to use the page object pattern when testing web pages with the keyword based approach of robot framework. +PageObjectLibrary is a lightweight [Robot Framework] keyword library that makes it possible to use the page object pattern when testing web pages with the keyword based approach of robot framework. ## Installing From 900fbca6f4fed8bb466bfce060b6b9b17f4a569a Mon Sep 17 00:00:00 2001 From: Greg Meece Date: Fri, 11 Aug 2017 11:30:28 -0500 Subject: [PATCH 3/4] Bumped version to Beta.2 'cause...changes! --- PageObjectLibrary/version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PageObjectLibrary/version.py b/PageObjectLibrary/version.py index 5bc11fc..309ac8b 100644 --- a/PageObjectLibrary/version.py +++ b/PageObjectLibrary/version.py @@ -1,2 +1,2 @@ -__version__ = "1.0.0-beta.1" +__version__ = "1.0.0-beta.2" From 152d7a7d665ef0cb64c2274385b939d686fd8f51 Mon Sep 17 00:00:00 2001 From: Greg Meece Date: Tue, 15 Aug 2017 13:09:34 -0500 Subject: [PATCH 4/4] Updating source and output documentation. Mostly formatting conventions, based on my years as a Tech Docs writer, etc. --- PageObjectLibrary/__init__.py | 61 +++++++++++------------ PageObjectLibrary/keywords.py | 28 +++++------ doc/pageobjectlibrary.html | 94 ++++++++++++++++++++++++++++++++--- 3 files changed, 131 insertions(+), 52 deletions(-) diff --git a/PageObjectLibrary/__init__.py b/PageObjectLibrary/__init__.py index 49aa90f..db5b4ef 100644 --- a/PageObjectLibrary/__init__.py +++ b/PageObjectLibrary/__init__.py @@ -14,15 +14,15 @@ class PageObjectLibrary(PageObjectLibraryKeywords): [http://robotframework.org/Selenium2Library/doc/Selenium2Library.html|Selenium2Library]. This library does not replace Selenium2Library; rather, it provides a framework around which to use Selenium2Library and the - lower-level [http://selenium-python.readthedocs.org/|python - bindings to selenium] + lower-level [http://selenium-python.readthedocs.org/|Python + bindings to Selenium] This library provides the following keywords: | =Keyword Name= | =Synopsis= | - | Go to page | goes to the given page in the browser | - | The current page should be | assert that the given page is displayed in the browser | - | Get page name | returns the name of the current page + | Go to page | Goes to the given page in the browser | + | The current page should be | Assert that the given page is displayed in the browser | + | Get page name | Returns the name of the current page | PageObjectLibrary provides a PageObject class which should be used as the base class for other page objects. By inheriting from this @@ -30,11 +30,11 @@ class your keywords have access to the following pre-defined attributes and methods: | =Attribute/method= | =Description= | - | self.se2lib | A reference to the selenium2library instance | - | self.browser | A reference to the currently open browser | - | self.locator | A wrapper around the _locators dictionary | - | self.logger | A reference to the robot.api.logger instance | - | self._wait_for_page_refresh() | a context manager for doing work that causes a page refresh | + | ``self.se2lib`` | A reference to the Selenium2Library instance | + | ``self.browser`` | A reference to the currently open browser | + | ``self.locator`` | A wrapper around the ``_locators`` dictionary | + | ``self.logger`` | A reference to the ``robot.api.logger`` instance | + | ``self._wait_for_page_refresh()`` | a context manager for doing work that causes a page refresh | = Using Selenium2Library Keywords = @@ -45,11 +45,11 @@ class your keywords have access to the following pre-defined | self.se2lib.capture_page_screenshot() - = Using Selenium methods = + = Using Selenium Methods = - The attribute ``self.browser`` is a reference to a selenium + The attribute ``self.browser`` is a reference to a Selenium webdriver object. With this reference you can call any of the - standard selenium methods provided by the selenium library. The + standard Selenium methods provided by the Selenium library. The following example shows how to find all link elements on a page: | elements = self.browser,find_elements_by_tag_name("a") @@ -60,9 +60,9 @@ class your keywords have access to the following pre-defined the class should define the following attributes: | =Attribute= | =Description= | - | PAGE_URL | The path to the current page, without the \ - hostname and port (eg: /dashboard.html) | - | PAGE_TITLE | The web page title. This is used by the \ + | ``PAGE_URL`` | The path to the current page, without the \ + hostname and port (eg: ``/dashboard.html``) | + | ``PAGE_TITLE`` | The web page title. This is used by the \ default implementation of ``_is_current_page``. | When using the keywords `Go To Page` or `The Current Page Should Be`, the @@ -71,12 +71,12 @@ class your keywords have access to the following pre-defined of the page. If you are working on a site where the page titles are not unique, you can override this method to do any type of logic you need. - = Page Objects are normal robot libraries = + = Page Objects are Normal Robot Libraries = All rules that apply to keyword libraries applies to page objects. For - example, the libraries must be on PYTHONPATH. You may also want to define + example, the libraries must be on ``PYTHONPATH``. You may also want to define ``ROBOT_LIBRARY_SCOPE``. Also, the filename and the classname must be identical (minus - the .py suffix on the file). + the ``.py`` suffix on the file). = Locators = @@ -88,9 +88,9 @@ class your keywords have access to the following pre-defined the locators via dot notation within your keywords as ``self.locator.``. The ``_locators`` dictionary may have nested dictionaries. - = Waiting for a page to be ready = + = Waiting for a Page to be Ready = - One difficulty with writing selenium tests is knowing when a page has refreshed. + One difficulty with writing Selenium tests is knowing when a page has refreshed. PageObject provides a context manager named ``_wait_for_page_refresh()`` which can be used to wrap a command that should result in a page refresh. It will get a reference to the DOM, run the body of the context manager, and then wait for the @@ -120,27 +120,26 @@ class your keywords have access to the following pre-defined | with self._wait_for_page_refresh(): | self.click_the_submit_button() - = Using the page object in a test = + = Using the Page Object in a Test = To use the above page object in a test, you must make sure that - robot can import it, just like with any other keyword + Robot can import it, just like with any other keyword library. When you use the keyword `Go to page`, the keyword will automatically load the keyword library and put it at the front of - the robot framework library search order (see - [http://robotframework.org/robotframework/latest/libraries/BuiltIn.html#Set - Library Search Order|Set library search order]) + the Robot Framework library search order (see + [http://robotframework.org/robotframework/latest/libraries/BuiltIn.html#Set%20Library%20Search%20Order|Set Library Search Order]) In the following example it is assumed there is a second page object named ``DashboardPage`` which the browser is expected to go to if login is successful. - | *** Settings *** - | Library PageObjectLibrary - | Library Selenium2Library - | Suite Setup Open browser http://www.example.com + | ``*** Settings ***`` + | Library PageObjectLibrary + | Library Selenium2Library + | Suite Setup Open browser http://www.example.com | Suite Teardown Close all browsers | - | *** Test Cases *** + | ``*** Test Cases ***`` | Log in to the application | Go to page LoginPage | Log in as a normal user diff --git a/PageObjectLibrary/keywords.py b/PageObjectLibrary/keywords.py index 9f10200..7dde18f 100644 --- a/PageObjectLibrary/keywords.py +++ b/PageObjectLibrary/keywords.py @@ -34,10 +34,10 @@ def se2lib(self): def the_current_page_should_be(self, page_name): """Fails if the name of the current page is not the given page name - page_name is the name you would use to import the page + ``page_name`` is the name you would use to import the page. This keyword will import the given page object, put it at the - front of the robot library search order, then call the method + front of the Robot library search order, then call the method ``_is_current_page`` on the library. The default implementation of this method will compare the page title to the ``PAGE_TITLE`` attribute of the page object, but this @@ -63,29 +63,29 @@ def the_current_page_should_be(self, page_name): raise Exception("Expected page to be %s but it was not" % page_name) def go_to_page(self, page_name, page_root = None): - """Go to the url for the given page object + """Go to the url for the given page object. Unless explicitly provided, the URL root will be based on the root of the current page. For example, if the current page is http://www.example.com:8080 and the page object URL is - /login, the url will be http://www.example.com:8080/login + ``/login``, the url will be http://www.example.com:8080/login - Example: + == Example == - Given a page object named `ExampleLoginPage` with the URL - `/login`, and a browser open to `http://www.example.com`, the - following statement will go to `http://www.example.com/login`, - and place `ExampleLoginPage` at the front of robot's library + Given a page object named ``ExampleLoginPage`` with the URL + ``/login``, and a browser open to ``http://www.example.com``, the + following statement will go to ``http://www.example.com/login``, + and place ``ExampleLoginPage`` at the front of Robot's library search order. - | go to page ExampleLoginPage + | Go to Page ExampleLoginPage The effect is the same as if you had called the following three - keywords + keywords: - | Selenium2Library.go to http://www.example.com/login + | Selenium2Library.Go To http://www.example.com/login | Import Library ExampleLoginPage - | Set library search order ExampleLoginPage + | Set Library Search Order ExampleLoginPage Tags: selenium, page-object @@ -98,7 +98,7 @@ def go_to_page(self, page_name, page_root = None): url = "%s://%s%s" % (scheme, netloc, page.PAGE_URL) with page._wait_for_page_refresh(): - self.logger.console("\ntrying to go to '%s'" % url) + # self.logger.console("\ntrying to go to '%s'" % url) # <-- Remove hashmark if you want this message on console self.se2lib.go_to(url) # should I be calling this keyword? Should this keyword return # true/false, or should it throw an exception? diff --git a/doc/pageobjectlibrary.html b/doc/pageobjectlibrary.html index ce23149..d688e9d 100644 --- a/doc/pageobjectlibrary.html +++ b/doc/pageobjectlibrary.html @@ -5,14 +5,15 @@ - + +