GSoC 2021: E2E Automated Tests for the OpenMRS 3.0 RefApp

Abstract

The Microfrontends Squad has been building a new Reference Application that will lead us into the future of OpenMRS. Our previous version was called the "2.x RefApp", so we are calling this new and improved one the "3.0 RefApp". OpenMRS 3.0 uses the new Microfrontend architecture. Students who are successful in the E2E tests in this project may also be asked to work on frontend widget/features needed for 3.0, since the E2E test writing will help the student become familiar with the 3.0 codebase - and there is no shortage of feature development needed for the 3.0 RefApp.

We don't currently have any E2E tests running for our 3.0 RefApp, but we want to set these up (see our dev/qa environment here: https://openmrs-spa.org/openmrs/spa/login  u: admin p:Admin123).

The idea is that someone would set up tests using Cypress and our new Cucumber test engine framework. They will set up tests that will automatically run against the UI, based on user workflows.

Multiple students may be able to work on this together, depending on the applicants. 

Project Champions

• In addition to the mentors above: Grace Potma, Jonathan Dick, Brandon Istenes

Skills Needed

• Some familiarity with frontend web development - React experience is an especial asset  
• Some experience with Cypress (just be able to show you can write 1-2 simple test cases with Cypress; the rest you can learn during the project)

Application Requirements

Because this is a late-addition project, all we are asking from applicants is that you have done both of these:

1. Either already contributed to OpenMRS significantly in the past, or recently worked on several PRs related to OMRS Microfrontends; AND,
2. Set up 1-2 example tests using Cypress. Show these in your GSOC application. These can be very simple, e.g. just a login test. This just helps demonstrate your interest and ability to pick up Cypress.

Objectives

Overall Goal: Set up tests that automate realistic User Workflows and show the squad the results, ideally with a warning indicator on a shared Repo ReadMe so that no one misses failing tests.

Example User Workflows to automate:

- Registration Clerk creates a patient
- Clerk searches for a patient, updates demographics, and starts a visit for a patient
- Nurse records Vital Signs, reviews patient chart (sees abnormal VS highlighted), and adds an allergy
- Clinician views HIV summary, test results page, and completes a form

Tasks you will have to do in order to set up these tests with both Cypress and the Cucumber engine we're using across OpenMRS: 

1. Create Feature File in a specific repo location (to be set up with assistance from the mentor)  
   1. Write Test Steps in Gherkin BDD language and add these to the Feature File (Guidance here: https://cucumber.io/docs/gherkin/reference/) (steps in the feature file should be in the Gherkin BDD language, using "Given" "When") (Example 1) (Example 2)
2. Automate these Steps with Cypress
   1. Create Cypress Skeleton & add this to the repo
   2. Add Cucumber-Cypress pre-processor, and pass a setting to it that defines where you have the automation tests (e.g. Example)
      1. Define where you're writing the Automation steps (e.g. Example)
   3. Define the place where the feature file sits (e.g. Example )

Extra Credit

• If the student does well with the E2E tests during the GSOC project, they can ask the squad for support to pick up additional feature development in React as part of their project, e.g. picking up epics that need work to set up a good end-to-end user workflow/experience on the 3.0 demo site. Feature backlog: https://issues.openmrs.org/secure/RapidBoard.jspa?rapidView=231&view=planning&selectedIssue=MF-449&epics=visible&issueLimit=100&selectedEpic=MF-335 

Demo

Resources

• Learning:
  • Detailed background about OpenMRS 3.0: OpenMRS 3.0: A Frontend Framework that enables collaboration and better User Experience
  • Review these tips: https://css-tricks.com/using-cypress-to-write-tests-for-a-react-application/ 
  • Cypress demo examples from other projects in the OMRS community: Cypress Demo
  • "Testing Strategies" section of Cypress Docs on network requests: https://docs.cypress.io/guides/guides/network-requests#Testing-Strategies
• Epic with Test Tasks to be done during the GSOC Project: 
  • MF-531 - Getting issue details... STATUS
• 3.0 RefApp Workflow Cases
• QA Dashboard: Project Status
• OpenMRS contrib-qaframework repo
• Developer Documentation

Resources