Overview

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

A demo for Workflow Based Testing using BDD framework: https://www.youtube.com/watch?v=Wl_KHd11Hyo

GitHub repo from example in Tutorial: https://github.com/openmrs/openmrs-contrib-qaframework/pull/9

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

Setup

Install java8, git and maven

QAFramework should be followed when building qaframework

1. Run QAFramework

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.  

   • Chrome

   • Firefox

   • Others

3. Move your downloaded browser webdriver into the right locations as follows

4.  

   • 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

5. Edit src/test/resources/org/openmrs/uitestframework/test.properties

   • 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

     • webdriver.chrome.webdriver=chromedriver/mac/chromedriver

Properties explanation:

Tracked projects status

https://github.com/openmrs/openmrs-contrib-qaframework#project-status

How to test different projects

https://github.com/openmrs/openmrs-contrib-qaframework#openmrs-contrib-qaframework

How to run locally tests for  2.x Reference Application

How to run locally tests for  3.x Reference Application

How to run locally tests for  Dictionary Manager

Infrastructure

Open

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

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.

Page

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

• feature file

• page

• steps definition

Vitals and Triaging feature

• feature file

• page

• steps definition

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 https://github.com/openmrs/openmrs-distro-referenceapplication/tree/master/ui-tests/src/test/java/org/openmrs/reference

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 https://github.com/openmrs/openmrs-distro-referenceapplication/tree/master/ui-tests/src/test/java/org/openmrs/reference/page

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:

https://issues.openmrs.org/secure/RapidBoard.jspa?rapidView=240&useStoredSettings=true 

Troubleshooting

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.