Selenium-Java-Allure Framework

A Maven framework in which to build Selenium tests written in Java with Allure reports of test results.

Getting Started

Copy the repo into your local machine.

Run tests locally

Right-click the feature file and select "Run" or "Debug" to start the test.

Run tests through the commandline

As this project uses Maven, we can invoke the tests using Maven goals.

To run the test, use your CI or point Maven to the project and use the goals:

clean install site

Defining the browser

By default, the project will default to ChromeLocal (running a local Chrome instance) if no browser is specified.

To express a specific browser type, at runtime or through VM options in your IDE, pass the following property:

-Dbrowser.type=FirefoxLocal

Common Parameter Values

Additional Parameter Values

Appium

When writing tests using this framework, you can easily leverage these tests to run against an Appium grid with the following settings:

You can set Appium properties using the following to create a request (for capability values information, see http://appium.io/docs/en/writing-running-appium/caps/) :

• appium.browser.name
• appium.device.name
• appium.platform.name
• appium.os.version

There is a special pre-set Appium driver for WinAppDriver that can be used for Windows desktop testing by using:

For more Appium driver capabilities information, see: http://appium.io/docs/en/writing-running-appium/caps/

Grid Test Execution

When running tests on a remote grid, you must specify a "Remote" type browser, e.g. ChromeRemote:

-Dbrowser.type=ChromeRemote

Executing tests on a Selenium Grid

To point your tests to a Selenium grid, at runtime or through VM options in your IDE, pass the following property:

-Dselenium.grid.url=http://localhost:4444/wd/hub

Executing test on Browserstack

To point your tests to Browserstack at runtime or through VM options in your IDE, pass the following properties:

-Dbrowserstack.username=TESTUSER
-Dbrowserstack.access.key=KEY123!

To override Browserstack logging levels from their default to turning all logs off, pass the following property:

-Dbrowserstack.logging=OFF

To override Browserstack logging levels from their default to turning all logs on and at error level, pass the following property:

-Dbrowserstack.logging=ON

Writing tests

To write tests, you can call any Webdriver methods by calling:

DriverManager.getDriver()

This will give access all the available methods to all Webdrivers as outlined by the W3C standard.

Site class

This is a "helper" class that takes the most common interactions and wraps them with some additional behaviour to avoid common pitfalls (e.g. waiting for element to be ready for an interaction before trying to interact with it) and/or reduce repetition of code.

The Site class has methods such as Site.click(), which has a default wait for the element to be clickable before attempting to click.

Primefaces* classes

Additionally, there is a niche set of methods for Primefaces to interact with elements with the same philosophy as Site for general webpage interactions.

Properties

Properties are retrieved by default from a file called test-automation.properties, which should be located under:

src > main > resources > test-automation.properties

The properties declared here can be overridden, however, if specified as a system property at runtime.

For example, if you declare the following property in your test-automation.properties file:

browser.type=FirefoxLocal

And you also pass the following at runtime:

-Dbrowser.type=EdgeLocal

The property browser.type will be set to EdgeLocal, as the system property overrides the properties file's values.

Database for test data

The framework provides a static database pool in the form of "Yank", which is backed by ApacheDB Utils and HikariCP.

To use, add the following to your glue (in your test runner or IDE):

uk.ac.cam.automation.seleniumframework.database

and set the following properties in your test-automation.properties file or as system properties:

automation.jdbc.username=xxx
automation.jdbc.password=xxx
automation.jdbc.url=xxx

You can then use the static methods of Yank to create database queries:

Yank.queryColumnList("select column_name from table_name where column_condition = ? ", "column_name", String.class, new Object[] {column_condition_value});

More information at: Yank

Email in tests

There is a built-in capability for retrieving emails and using the content in test execution.

To connect to an in-memory mail host (such as Greenmail), you need to set the following properties (for example in test-automation.properties):

mail.host=mailhost.internal.com
mail.retrieval.protocol=imap
mail.retrieval.port=5959
mail.timeout.seconds=60

Below is an example usage of this to read an email, close the account and delete all emails after reading and then extract the link from the email for navigation in the browser:

String latestMailFromAccount = EmailRetriever.getLatestMailFromAccount(email, true).getBody();
System.out.println(latestMailFromAccount);

Document doc = Jsoup.parse(latestMailFromAccount);
Elements links = doc.select("a");
Site.goToURL(links.attr("href"));

Logging

Logging can be easily added to tests by using the static methods from the Log class.

Available logging levels are:

Reporting

The default reporting provided by the framework is Allure. By default, screenshots are taken after each step and after a failure (if any), which will display on each step of the report. To turn this behaviour off and disable screenshots, pass the following property:

-Dscreenshot.off=TRUE

To take additional screenshots, you can call the following method at any point, and it will automatically add a screenshot to the relevant step:

ScreenshotTaker.attachScreenshot();

N.B. Although Allure is the default reporter, the TestNG/JUnit reports generated can be used with any compatible reporter in your project if you choose not to use Allure.

Releasing

In order to build and release the artifact to Maven Central, the following steps must be followed (only developer and maintainer access levels allowed):

• Check latest version from https://search.maven.org/artifact/uk.ac.cam.automation/seleniumframework - choose new release version from here (e.g. if latest == 4.0.2, the next release could be 4.0.3 for a minor release, or 4.1.0 or 5.0.0 for major releases)
• Go to https://gitlab.developers.cam.ac.uk/uis/qa/selenium-java-framework/-/pipelines
• Click "Run Pipeline"
• In the form, change the version number from 1.0.0 to the desired version and click "Run pipeline"

Built With

• Selenium - Browser automation framework
• Maven - Dependency management
• TestNG - Testing framework
• Allure - Reporting framework
• WebDriverManager - Local driver binary management
• Yank - database connection pooling

Licence

This project is licensed under the MIT License.