Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree
Skip to end of metadata
Go to start of metadata


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.

Video Tutorial

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:

GitHub repo from example in Tutorial:


Install java8, git and maven

QAFramework depends on UITestFramework and Reference application distro to support Reference application distribution out of the box quality assurance.

Compile the Reference application distribution (Optional)

This is the default OpenMRS community-supported distribution, it should be pulled by default while compiling the QAFramework, but in-case this doesn’t happen, please clone and compile it separately.

git clone

git checkout 2.10.0

mvn clean install

Compile UITestFramework

This is the Reference application distribution’s user interface test framework, it uses selenium for its webdriver.

Clone and compile its bdd branch

git clone

git checkout bdd

mvn clean install

Run QAFramework

git clone

To change the default runtime settings. Please edit src/test/resources/org/openmrs/uitestframework/

Properties explanation;

webapp.url= [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] [Auto login or not on each scenario; true/false]
headless=true [Launch browser in the background without UI; true/false]

To Run UI tests

mvn clean test

In order to test within a physical web browser, you will need a webdriver to connect to your browser either firefox or chrome, the webdriver.

  1. First set  webdriver=chrome [chrome/firefox]
  2. Then disable running the tests in a headless browser headless=false
  3. Then download the corresponding webdriver version that matches your system and browser version;
  4. Move your downloaded browser webdriver into the right locations as follows
    • Chrome:  src/main/resources/chromedriver/<linux/mac>/chromedriver or src/main/resources/chromedriver/windows/chromedriver.exe
    • Firefox: Set the location for the geckodriver (should be within the test resources directory) within the properties file
      • webdriver.gecko.driver=firefoxdriver/mac/geckodriver
  5. Then Run ui tests again: mvn clean test


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 and launch 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 if configured to in 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.

Samples on automation

Simple Styles guide

Conditions feature

  • No labels