Skip to content

Latest commit

 

History

History
115 lines (88 loc) · 4.86 KB

README.md

File metadata and controls

115 lines (88 loc) · 4.86 KB
Raw

E2E Tests

This directory contains an E2E test suite using the Playwright framework. Check our E2E guide for more information about the E2E implementation.

Getting Started

Please ensure that you have followed the basic installation guide in the root README. Once everything is set up, make sure the dev server is running by using:

yarn start --sources

Then, in a separate terminal, run:

yarn test-e2e --headed

By default, the test suite will run against the http://localhost:8080. You can override this by exporting E2E_BASE_URL environment variables beforehand:

# Ex: Set the server URL to dev3:
export E2E_BASE_URL=https://dev3.openmrs.org/openmrs

# Run all e2e tests:
yarn test-e2e --headed

To run a specific test by title:

yarn test-e2e --headed -g "title of the test"

Check this documentation for more running options.

It is also highly recommended to install the companion VS Code extension: https://playwright.dev/docs/getting-started-vscode

Writing New Tests

In general, it is recommended to read through the official Playwright docs before writing new test cases. The project uses the official Playwright test runner and, generally, follows a very simple project structure:

e2e
|__ commands
|   ^ Contains "commands" (simple reusable functions) that can be used in test cases/specs,
|     e.g. generate a random patient.
|__ core
|   ^ Contains code related to the test runner itself, e.g. setting up the custom fixtures.
|     You probably need to touch this infrequently.
|__ fixtures
|   ^ Contains fixtures (https://playwright.dev/docs/test-fixtures) which are used
|     to run reusable setup/teardown tasks
|__ pages
|   ^ Contains page object model classes for interacting with the frontend.
|     See https://playwright.dev/docs/test-pom for details.
|__ specs
|   ^ Contains the actual test cases/specs. New tests should be placed in this folder.
|__ support
    ^ Contains support files that requires to run e2e tests, e.g. docker compose files.

When you want to write a new test case, start by creating a new spec in ./specs. Depending on what you want to achieve, you might want to create new fixtures and/or page object models. To see examples, have a look at the existing code to see how these different concepts play together.

Open reports from GitHub Actions

To download the report from the GitHub action/Bamboo plan, follow these steps:

  1. Go to the artifact section of the action/plan and locate the report file.
  2. Download the report file and unzip it using a tool of your choice.
  3. Open the index.html file in a web browser to view the report.

The report will show you a full summary of your tests, including information on which tests passed, failed, were skipped, or were flaky. You can filter the report by browser and explore the details of individual tests, including any errors or failures, video recordings, and the steps involved in each test. Simply click on a test to view its details.

Debugging Tests

Refer to this documentation on how to debug a test.

Configuration

This is very much underdeveloped/WIP. At the moment, there exists a (git-shared) .env file which can be used for configuring certain test attributes. This is most likely about to change in the future. Stay tuned for updates!

GitHub Action integration

The e2e.yml workflow is made up of two jobs: one for running on pull requests (PRs) and one for running on commits.

  1. When running on PRs, the workflow will start the dev server, use dev3.openmrs.org as the backend, and run tests only on chromium. This is done in order to quickly provide feedback to the developer. The tests are designed to generate their own data and clean up after themselves once they are finished. This ensures that the tests will have minimum effect from changes made to dev3 by other developers. In the future, we plan to use a docker container to run the tests in an isolated environment once we figure out a way to spin up the container within a small amount of time.
  2. When running on commits, the workflow will spin up a docker container and run the dev server against it in order to provide a known and isolated environment. In addition, tests will be run on multiple browsers (chromium, firefox, and WebKit) to ensure compatibility.

Troubleshooting tips

On MacOS, you might run into the following error: browserType.launch: Executable doesn't exist at /Users/<user>/Library/Caches/ms-playwright/chromium-1015/chrome-mac/Chromium.app/Contents/MacOS/Chromium In order to fix this, you can attempt to force the browser reinstallation by running: PLAYWRIGHT_BROWSERS_PATH=/Users/$USER/Library/Caches/ms-playwright npx playwright install