QAFramework is an OpenMRS’ behaviour driven development (BDD) quality assurance framework.
BDD brings technical(developers, QA) together with business(non-technical, Business analysts) people to foster collaboration and ease problem-solving.
QAFramework uses cucumber for its BDD test case descriptions;
BDD largely uses a simple domain-specific natural language (DSL) to represent the test cases cucumber specifically uses Gherkin for this.
In addition to the clear guidance below, you can see this recording for a tutorial we hosted on setting up Selenium tests for the Reference Application: https://iu.mediaspace.kaltura.com/media/Design+Meeting/1_dh12nkr0?st=321
A demo on how automated tests are carried out can be accessed at https://www.youtube.com/watch?v=XzBAXMj1UN0
GitHub repo from example in Tutorial: https://github.com/openmrs/openmrs-contrib-qaframework/pull/9
Install java8, git and maven
QAFramework depends on Reference application distro and UITestFramework to support Reference application distribution out of the box quality assurance, the following ordered steps should be followed when building qaframework.
1. Compile UITestFramework
git clone firstname.lastname@example.org:openmrs/openmrs-contrib-uitestframework.git
mvn clean install
2. Compile the Reference application distribution
git clone email@example.com:openmrs/openmrs-distro-referenceapplication.git
mvn clean install
3. Run QAFramework
git clone firstname.lastname@example.org:openmrs/openmrs-contrib-qaframework.git
mvn clean install to Install dependencies
In order to test within a real desktop browser, you will need a webdriver to connect to your browser (either firefox or chrome).
- Download the webdriver version that matches your system and browser version.
- Chrome: src/test/resources/chromedriver/<linux/mac>/chromedriver or src/test/resources/chromedriver/windows/chromedriver.exe
- Firefox: src/test/resources/firefoxdriver/<linux/mac>/geckodriver or src/test/resources/firefoxdriver/windows/geckodriver.exe
- Set webdriver=chrome or webdriver=firefox
- Set headless=false to allow the web browser UI to appear during the test
- Set the location of your webdriver within src/test/resources, for example
- webdriver.gecko.driver=firefoxdriver/windows/geckodriver or
webapp.url=https://qa-refapp.openmrs.org/openmrs [openmrs instance URL]
login.username=admin [Above OpenMRS instance username]
login.password=Admin123 [Above OpenMRS instance password]
login.location=Pharmacy [Above OpenMRS instance login location]
webdriver=chrome [Browser instance; chrome/firefox]
login.auto=false [Auto login or not on each scenario; true/false]
headless=true [Launch browser in the background without UI; true/false]
Tracked projects status
How to test different projects
Collaboratively, business analysts translate requirements into test cases and define from them features, scenarios, steps written in a Behavior Driven Development (BDD) approach through a human readable language; Gherkin, this is made easier graphically through cucumber studio.
Exporting the project from cucumber studio for automation avails a feature file with the human readable test case which file can be written from any texteditor and which is imported into the automation library (qaframework) and an automation layer (with step descriptions) is written by a test engineer or developer through a preferred automation framework such as selenium (for the reference application), cypress (OCL) etc.
Running the QA framework locally or in Bamboo CI runs the automated test suite;
- this will read test.properties and launch RunTest.java(junit with cucumber runner) with the loaded configurations which reads all feature files tagged @run and locates each respective step description from mapped (glued) automation package,
- automation steps launch the automation framework (e.g selenium/cypress) by scenario and each scenarios by step order, steps load pages (some are from uitestframework/distribution/qaframework) and return results to the build through its web driver
- the build posts test results to reports.cucumber.io if configured to in cucumber.properties which happens by default within bamboo CI
- Bamboo CI is also configured to post results back into cucumber studio and a result green/red label (build status) is displayed on qaframework basing on CI build result.
Getting started writing code
Below is a sample tutorial to help ease understanding the structure of feature files, page and step definitions
A feature file is written in a human readable gherkin BDD language, cucumber runs the feature files in their naming alphabetical order.
A simple feature file consists of the following keywords/parts −
Feature − Name of the feature under test.
Description (optional) − Description about feature under test.
- Background (optional) - Steps (A user or system action) to be run before each scenario
Scenario − A test case, each action within a scenario is called a Step and each step is preceded with Given/When/Then/And keywords.
Given − Defines the initial action or/and known system state, it is a prerequisite before the test steps get executed.
When − Specific condition which should match in order to execute the next step.
Then − A verification of the condition above through evaluation of the system response.
- And - Used to define more than one step along side Given, When and Then
- @Tag - Used to group scenarios, you can use "@Selenium" before a scenario to for-example run a group of scenarios tagged "Selenium" as we do here.
An html page structure containing references to DOM elements as well as expected user actions such as clicking, navigation, typing etc
An implementation of the actual functionality of each step within the feature file consuming the page to emulate a complete user system workflow. Each Step class contains all the scenario steps for the respective feature file
Simple Styles guide
Guidelines of Writing/Extending Each Test classes
- Each test class should extend ReferenceApplicationTestBase For only and only those classes that donot have parent super classes
- Tests should be added under https://github.com/openmrs/openmrs-distro-referenceapplication/tree/master/ui-tests/src/test/java/org/openmrs/reference
- Each test class should be named starting with a verb, which best describes an action that is being tested, e.g. SearchActiveVisitsTest. By convention all test class names must end with Test.
- In general each class should contain one test method (annotated with @Test) and the test method should start with a verb and can provide a more detailed description of what is being tested than the class, e.g. searchActiveVisitsByPatientNameOrIdOrLastSeenTest.
- The test method should not visit more than 10 pages and should have 3-15 steps.
- You must not access Driver in a test. It is only allowed to perform actions calling methods in classes extending Page.
- Each test class should start from homePage and extend ReferenceApplicationTestBase.
- It is not allowed to instantiate classes extending Page in test classes. They must be returned from Page's actions e.g. ActiveVisitsPage activeVisitsPage = homePage.goToActiveVisitsSearch();
- Each page should have a corresponding class, which extends Page and it should be added under https://github.com/openmrs/openmrs-distro-referenceapplication/tree/master/ui-tests/src/test/java/org/openmrs/reference/page
- The page class should be named after page's title and end with Page.
- It is not allowed to call Driver's methods in a page. You should be calling methods provided by the Page superclass.
Find some work on the QA board at:
Sometimes your added web driver may not be executable if you are running the IDE vs maven which auto makes that so when building. ensure you always manually make it executable to avoid the server quitting before launching.