Testing and Continuous Integration Setup for the OCL Client

Owned by Lincoln Karuhanga
Last updated: Jul 29, 2020 by Grace Potma
3 min read

Testing and Continuous Integration Setup for the OCL client

Environments

There are 4 environments to be aware of for this project:

  1. The two current OCL for OpenMRS environments:
    1. QA: https://openmrs.qa.openconceptlab.org
      1. This is the staging environment. Merge here, and use for UAT. Has the latest code commits and is reset with each code deployment.
      2. Lighter-weight than production with ~2,000 concepts.
      3. Pushing to master rebuilds QA, resets DB. Currently, CIEL Sources and users persist, but other sources and collections reset. We need sources and especially collections to persist in QA (following up on this in Sprint 32).
    2. Demo: https://openmrs.demo.openconceptlab.org
      1. This is for sharing with the world what we've got. It should be a demo of production for implementers to use as they experiment with the offering.
      2. Has the same code as production and is reset daily.
      3. Larger content set: ~50,000 concepts.
  2. The old OCL for OpenMRS website: https://openmrs.openconceptlab.org/
  3. The central, external OCL website: https://openconceptlab.org/

CI Builds

  • The OCL web client makes use of travis.org for open source to run application builds on each branch, pull request and on master post merge.
  • travis.org setup is a two step process, first a configuration file is setup. This file can be found in the repository, here and details for how to set this up can be found in the travis.org documentation. The second step involves linking the repository to travis.org.
  • This runs the build and updates the pull request to reflect the build status.

Test Coverage Results

  • If the previous build was successful, coverage information is sent to coveralls.io, which also updates the pull request with details of coverage and regression.
  • The coveralls setup file itself is also included in the repository, here.

Testing Proposed Changes In A Pull Request

We deploy a version of the OCL Client whenever a pull request is opened on the repository and destroy it as soon as the PR is merged/ closed. A link to the deployment is added to the PR review page.

Why was this necessary?

  • This makes it easier to test proposed changes, as opposed to the current pull and build process developers on the OCL team have to go through.
  • It also makes it easier to get feedback on proposed changes, from the product owners and other stakeholders.
  • This will also cut down the length of the feedback loop in regards to proposed improvements to the OCL client.

Setup

  • The OCL web client also makes use of the free Heroku tier to build independent applications on each pull request, provided the build on travis.org for that pull request passes. Links to the deployments are available on the PR page while the PR is open, as shown above.
  • The setup configuration files for this process are in the repository. The static.json file contains details on how the Heroku PaaS should serve each static build and the app.json file contains details of how each app should be setup. Details on how to setup this configuration can be found on the heroku.com's Pull Request apps page.
  • The heroku account currently in use belongs to openmrs.ocl@gmail.com. This heroku account has been granted permission to read the repository and update pull requests with details of the PR app deployment. Details of how to do this and how to revoke this access are documented below.

Rationale for using an external tool(Heroku)

  • This setup could possibly be done using in-house tools
  • We have chosen an out-of-the-box external tool(heroku), primarily for the ease of setup and the minimal number of updates required to bring the current deployment setup up to date with this approach.
  • This functionality can also easily be done away with in the future, that is by getting rid of the static.json and the app.json files and deactivating the account, if a better approach to this is suggested.

Granting and Revoking Heroku Access to the OpenMRS OCL Client Repository

In order to allow Heroku pull the code from the repository, build an instance, and update the PR page with a link to the instance, it must given these permissions to the repository.

  • Read Access- To allow code pulls and builds
  • Write Access- Creating a custom hook for automatic builds and updating the PR page with the deployment link

Details of how to connect the heroku account to the OCL Client Github repo can be found in the heroku documentation.

Details of how to revoke this access can be found under disconnecting the account.

Resources

OpenMRS OCL Client Wiki.