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:

      ^{[](<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.