Automated Testing Guidelines

Owned by raff
Last updated: Aug 26, 2016
2 min read
We are currently working on fixing UI tests to follow guidelines, which are aimed to improve tests stability, readability and maintainability.
If you want to help, please fork and clone https://github.com/openmrs/openmrs-distro-referenceapplication and try running tests locally using mvn clean install (by default firefox is used to run tests so you must have it installed).
Once you confirm you can run tests locally and the build is passing you can pick up any of test classes, which you can find under  https://github.com/openmrs/openmrs-distro-referenceapplication/tree/master/ui-tests/src/test/java/org/openmrs/reference
If you see that the test is not annotated with @Category(BuildTests.class) then it must be fixed. Please create a sub-task for
Error rendering macro 'jira' : Unable to locate Jira server for this macro. It may be due to Application Link configuration.
 for the test that needs to be fixed. Modify the test to conform the following guidelines:
  1. Tests should be added under https://github.com/openmrs/openmrs-distro-referenceapplication/tree/master/ui-tests/src/test/java/org/openmrs/reference
  2. Tests and Pages should include the OpenMRS license at the beginning of the file.
  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 @Category(BuildTests.class) 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. In rare cases we let test classes to have more than one test method.
  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. It is not allowed to call Driver's methods in a page. You should be calling methods provided by the Page superclass.
  8. Each test class should start from homePage and extend ReferenceApplicationTestBase.
  9. 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();
  10. Do not store pages in class fields as it suggests they can be used for other tests.
  11. 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/main/java/org/openmrs/reference/page
  12. The page class should be named after page's title and end with Page.
  13. Elements of the page must be found by id or class attributes. It is not allowed to find them by xpath expressions unless absolutely necessary. Locators must be defined as private (not public) static final fields of the class. See CSS Selectors.

For reference please use https://github.com/openmrs/openmrs-distro-referenceapplication/blob/master/ui-tests/src/test/java/org/openmrs/reference/SearchActiveVisitsTest.java and https://github.com/openmrs/openmrs-distro-referenceapplication/blob/master/ui-tests/src/main/java/org/openmrs/reference/page/ActiveVisitsPage.java

In case of questions, please write on talk.openmrs.org. The guidelines are work in progress and if you disagree, let's discuss. Send us a pull request with your changes and provide a link in the JIRA issue.