Setting up the project

The basic repository setup:

1. Clone the project

    git clone git@github.com:openmrs/openmrs-test-3refapp.git
    cd openmrs-test-3refapp
   
   

2. Install the dependencies

   yarn install

Run the local instance

1. Checkout to docker directory

   cd docker
   
   

2. Run the app

   docker-compose -f docker-compose-refqa-3x.yml up
   
   

If the docker container doesn't work you have to set up the local instance by packaging.

Follow these steps for setting up the local instance

1. Clone the repository

   git clone -b 3.x git@github.com:openmrs/openmrs-distro-referenceapplication.git
   
   

2. Follow the instruction provided by the readme

• If the build fails, try deleting existing containers

  docker compose down -v

Run Cypress Tests

This package contains an E2E test suite using the Cypress framework. This is the "default" package for writing E2E tests (unless you are interested in writing offline-related tests - if so, head over to the playwright directory).

Running tests

Please ensure that you have followed the basic installation guide in the root README. Once everything is set up, you can navigate to this directory (if not done already) and run the scripts inside the package.json file using yarn:

# Given that you start in the repository's root:
cd packages/cypress

# Run any script from the Cypress project's package.json file, e.g. the login tests:
yarn refapp3Login

Generally, there are two ways of running tests:

1. Running with cypress runner Open the Cypress runner with

   cypress open
   

   and pick a test from the GUI.

2. Running in command line

   Run the desired test using yarn run, e.g.

   yarn run refapp3Login
   

   Writing a new test

   Given that you are inside the /packages/cypress directory:

   1. Create a new directory with your feature file under /resources/features/refapp-3.x/.

      The name of the directory should be <sequence>-<name>.

      Example of a feature file

   2. Create a new directory with the same name under cypress/integration/cucumber/step_definitions/refapp-3.x/ to store the step definition file. See the cypress-cucumber-preprocessor docs

   3. Run the test using either:

      • Command line: cypress run --spec <path-to-feature-file>

        (You can simplify the command by adding it to the yarn scripts section. See this example.)

      • Cypress runner: cypress open and choose the test

   Environment variables

   The environment variables are stored in the cypress.json file. The variables can be accessed with Cypress.env(); e.g.,

   Cypress.env('API_BASE_URL');
   

   See the Cypress docs.
   

   Creating a GitHub workflow

   1. Create a new GitHub workflow file under .github/workflows/ directory. An example workflow can be found here.
   2. Add the workflow badge to the readme file under 3.x RefApp section. It should take the following format:

      [![<workflow name>](<link-to-the-workflow>/badge.svg)](<link-to-the-workflow>)
      

   Before Releasing

   • Check for the platform, and manually run both Installation and upgrade workflows again.
   • Check all relevant builds to the release above to be sure they pass.