Tutorial - Writing integration tests using PageObjects
On this page:
This tutorial shows you how to write PageObjects for your plugin's pages and use them in integration tests.
You should be already familiar with writing a JIRA plugin and unit testing it. Also you can read about the previous method of creating integration tests using FuncTestCase.
There are various definitions available for what integration testing actually means. For the purposes of this tutorial, integration testing is defined as running a set of automated tests against the web-UI of your plugin, using HTTP requests and responses to assert that the web-UI is exhibiting the correct behaviour.
Step 1. Setting up your plugin
The best way to start creating your own Page Objects is to include JIRA Page Objects as a reference and base for your objects. So you need to modify your pom.xml and add following:
Step 2. Anatomy of Page Object
Let's imagine you're writing an integration test for CSV Importer. The page has a few elements like File Input, Checkbox, Input Fields and Buttons. Here's a simple class that you could use to test and drive this page.
Let's introduce couple of elements:
PageElementis a DOM element that you want to interact with (modify, click, read or write to)
@ElementByannotation defines how to search for the element; you can search by things like id, cssSelector, name, and tag
isAtmethod is used by
AbstractJiraPageto detect if page loading was finished and the expected page was loaded; it uses the
getUrlmethod defined in
AbstractJiraPageindicates where to go to open the expected page
pageBinderobject is responsible for binding the Page Object to the DOM, next method shows how to navigate from one page to another
As you can see, you can type or click on elements. You can also get their attributes, search for page elements inside of page elements, and so on. What's great is that Page Objects are run in the real browser so you really imitate the user and their experience.
Step 3. Using Page Objects in your tests
I assume you're using JIRA Func Test Basics to create an integration test. To simplify things, let's assume you extended
TestBase (check JIRA Func Test Basics documentation for a better, suggested way of writing integration tests).
This simple test case filled in form and clicked next button, then tested if user is correctly moved to the next wizard page which is CsvProjectMappingPage.
Step 4. Writing assertions for elements
Here's how you can test whether your code does what you expect it to do. To avoid race conditions, your Page Object should always return a
TimedCondtion. Let's check whether
userEmailSuffix was correctly read from the configuration.
Your test could look as follows:
Poller.waitUntil to check the assertion. This will poll the Page Object until the assumption is met or the timeout has passed. This is great if you have elements that are dynamically created, or you use AJAX to retrieve data. It will make sure that there are no race conditions in your code.
Step 5. Writing assertions for collections
Imagine we want to check whether the page displays correct hints for the user. Here's a Page Object:
You can check if the page includes the correct hints in your test as follows:
Step 6. Running tests on CI
There's also a simple way to run integration tests in headless mode on CI, all you need to do is edit pom.xml and set the
The Atlassian Plugin SDK will automatically launch Xvfb and run your tests using it.
Step 7. Even more resources on Page Objects
There's also in-depth guide that was published on Developer Blog by Dariusz Kordonski. Check it out to learn more!