QA Framework: Technical documentation (Cucumber-Selenium & Cucumber-Cypress Set up)


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.

Training Videos

10-Min Overview of Our QA Framework

Video: Detailed 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:

A demo on how automated tests are carried out can be accessed at 

A demo for Workflow Based Testing using BDD framework:

GitHub repo from example in Tutorial:

10-Min Overview for Technical Steps When Developing a  Test in BDD Framework  


Install java8, git and maven

QAFramework should be followed when building qaframework

1. Run QAFramework

git clone

Install project dependencies

 cd openmrs-contrib-qaframework

  • mvn clean install -DskipTests=true  

In order to test within a real desktop browser, you will need a webdriver to connect to your browser (either firefox or chrome).

  1. Download the webdriver version that matches your system and browser version.
  2. Move your downloaded browser webdriver into the right locations as follows
    • Chrome:  src/test/resources/chromedriver/<linux/mac>/chromedriver or src/test/resources/chromedriver/windows/chromedriver
    • Firefox: src/test/resources/firefoxdriver/<linux/mac>/geckodriver or src/test/resources/firefoxdriver/windows/geckodriver
  3. Edit src/test/resources/org/openmrs/uitestframework/
    • 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

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]

Tracked projects status

How to test different projects

How to run locally tests for  2.x Reference Application

For  BDD workflow tests

 i.  Ensure to have done step one in Setup wizard above 

  cd openmrs-contrib-qaframework

 ii. Navigate into qaframework-bdd-tests module.

     cd qaframework-bdd-tests

 iii. See the list of test workflows  present in the module by running the command:

     npm run

 iv.Trigger any test workflow by running the command:

     npm run workflowName

     For example a workflow whose name is refapp2ClinicalVisit can be triggered by running the command:

     npm run refapp2ClinicalVisit

     Note: If you want to watch the test via UI then set headless property value within file to false.

For selenium legacy tests

i. Ensure to have done step one in Setup wizard above 

  cd openmrs-contrib-qaframework

ii. Navigate into qaframework-legacy-tests module

  cd qaframework-legacy-tests

iii. Trigger the selenium legacy tests by running the command:   

    mvn clean install -DskipTests=false

   Note: Running the tests using the default online instance takes more time compared with spinning from a local

   instance. So you can change the webUrl property value within file to point to your local server url.

How to run locally tests for  3.x Reference Application

 i. Ensure to have done step one in Setup wizard above 

    cd openmrs-contrib-qaframework

ii.  Navigate into qaframework-bdd-tests module

  cd qaframework-bdd-tests

iii. Install the dependencies required to run the tests by running the command:

    npm install

iv.Trigger 3.x tests by running the command:

    npm cypress open

    Note: See a list of registered commands that can trigger specific test workflow by running the command:

    npm run

    Example npm run refapp3Login triggers the login workflow

How to Update Node version

Check the current version you have:

 npm -v

Clear npm cache

  sudo npm cache clean -f

Install or upgrade npm globally specifying syntax n , n means the version number of npm
  sudo npm install -g n

or you can simply use 

  sudo n stable : 
To install the stable version of npm

How to run locally tests for  Dictionary Manager

i.  git clone

    cd openmrs-ocl-client

ii. Install the dependencies required to run the tests by running the command:

    npm install

iii.Trigger ocl tests by running this command:

   CYPRESS_USERNAME=openmrs CYPRESS_PASSWORD=Openmrs123 CYPRESS_API_URL= npx cypress open


No results were found for groups : CTGCHG

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.

Getting started writing code

Below is a sample tutorial to help ease understanding the structure of feature files, page and step definitions

feature file

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

Step definition

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

Code Samples

Simple Styles guide
Vitals and Triaging feature

Guidelines of Writing/Extending  Each Test classes

  1. Each test class should extend ReferenceApplicationTestBase  For only and only those classes that donot have parent super classes
  2. Tests should be added under
  3. 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.
  4. 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.
  5. The test method should not visit more than 10 pages and should have 3-15 steps.
  6. You must not access Driver in a test. It is only allowed to perform actions calling methods in classes extending Page.
  7. Each test class should start from homePage and extend ReferenceApplicationTestBase.
  8. 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();
  9. Each page should have a corresponding class, which extends Page and it should be added under
  10. The page class should be named after page's title and end with Page.
  11. 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.