Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

O3-2413: (test) Setup playwright for automated tests in Fast Data Entry App #88

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 102 additions & 0 deletions .github/workflows/e2e.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
name: E2E Tests

on:
push:
branches:
- main
pull_request:
branches:
- main

env:
TURBO_API: 'http://127.0.0.1:9080'
TURBO_TOKEN: 'turbo-token'
TURBO_TEAM: ${{ github.repository_owner }}

jobs:
run_e2e_tests:
runs-on: ubuntu-latest
steps:
- name: 📥 Checkout repo
uses: actions/checkout@v4

- name: 📝 Copy test environment variables
run: cp example.env .env

- name: 🛠️ Setup node
uses: actions/setup-node@v4
with:
node-version: 18

- name: 💾 Cache dependencies
id: cache-dependencies
uses: actions/cache@v4
with:
path: '**/node_modules'
key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}

- name: 📦 Install dependencies
if: steps.cache-dependencies.outputs.cache-hit != 'true'
run: yarn install --immutable

- name: 🎭 Get installed Playwright version
id: playwright-version
run: echo "PLAYWRIGHT_VERSION=$(grep '@playwright/test@' yarn.lock | sed -n 's/.*npm:\([^":]*\).*/\1/p' | head -n 1)" >> $GITHUB_ENV

- name: 💾 Cache Playwright binaries
id: playwright-cache
uses: actions/cache@v4
with:
path: |
~/.cache/ms-playwright
key: ${{ runner.os }}-playwright-${{ env.PLAYWRIGHT_VERSION }}

- name: 🎭 Install Playwright Browsers
run: npx playwright install chromium --with-deps
if: steps.playwright-cache.outputs.cache-hit != 'true'

- name: 🚀 Setup local cache server for Turborepo
uses: felixmosh/turborepo-gh-artifacts@v3
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
server-token: ${{ env.TURBO_TOKEN }}

- name: 🏗️ Build apps
run: yarn turbo run build --color --concurrency=5

- name: 🚀 Run dev server
run: bash e2e/support/github/run-e2e-docker-env.sh

- name: ⏳ Wait for OpenMRS instance to start
run: while [[ "$(curl -s -o /dev/null -w ''%{http_code}'' http://localhost:8080/openmrs/login.htm)" != "200" ]]; do sleep 10; done

- name: 🧪 Run E2E tests
run: yarn test-e2e

- name: 🛑 Stop dev server
if: '!cancelled()'
run: docker stop $(docker ps -a -q)

- name: 📤 Upload report
uses: actions/upload-artifact@v4
if: '!cancelled()'
with:
name: playwright-report
path: playwright-report/
retention-days: 30
overwrite: true

- name: 📝 Capture Server Logs
if: always()
uses: jwalton/gh-docker-logs@v2
with:
dest: './logs'

- name: 📤 Upload Logs as Artifact
uses: actions/upload-artifact@v4
if: always()
with:
name: server-logs
path: './logs'
retention-days: 2
overwrite: true
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -75,3 +75,7 @@ dist/
!.yarn/versions

.turbo
/test-results/
/playwright-report/
/blob-report/
/playwright/.cache/
103 changes: 103 additions & 0 deletions e2e/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# E2E Tests

This directory contains an E2E test suite using the [Playwright](https://playwright.dev)
framework.

## Getting Started

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

```sh
yarn start
```

Then, in a separate terminal, run:

```sh
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:

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

# Run all e2e tests:

```sh
yarn test-e2e --headed
```

To run a specific test by title:

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

Check [this documentation](https://playwright.dev/docs/running-tests#command-line) 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](https://playwright.dev/docs/intro)
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 / Bamboo
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](https://playwright.dev/docs/debug) 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 Actions 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```
33 changes: 33 additions & 0 deletions e2e/core/global-setup.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@

import { request } from '@playwright/test';
import * as dotenv from 'dotenv';

dotenv.config();

/**
* This configuration is to reuse the signed-in state in the tests
* by log in only once using the API and then skip the log in step for all the tests.
*
* https://playwright.dev/docs/auth#reuse-signed-in-state
*/

async function globalSetup() {
const requestContext = await request.newContext();
const token = Buffer.from(`${process.env.E2E_USER_ADMIN_USERNAME}:${process.env.E2E_USER_ADMIN_PASSWORD}`).toString(
'base64',
);
await requestContext.post(`${process.env.E2E_BASE_URL}/ws/rest/v1/session`, {
data: {
sessionLocation: process.env.E2E_LOGIN_DEFAULT_LOCATION_UUID,
locale: 'en',
},
headers: {
Accept: 'application/json',
Authorization: `Basic ${token}`,
},
});
await requestContext.storageState({ path: 'e2e/storageState.json' });
await requestContext.dispose();
}

export default globalSetup;
1 change: 1 addition & 0 deletions e2e/core/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
export * from './test';
20 changes: 20 additions & 0 deletions e2e/core/test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
import { APIRequestContext, Page, test as base } from '@playwright/test';
import { api } from '../fixtures';

// This file sets up our custom test harness using the custom fixtures.
// See https://playwright.dev/docs/test-fixtures#creating-a-fixture for details.
// If a spec intends to use one of the custom fixtures, the special `test` function
// exported from this file must be used instead of the default `test` function
// provided by playwright.

export interface CustomTestFixtures {
loginAsAdmin: Page;
}

export interface CustomWorkerFixtures {
api: APIRequestContext;
}

export const test = base.extend<CustomTestFixtures, CustomWorkerFixtures>({
api: [api, { scope: 'worker' }],
});
26 changes: 26 additions & 0 deletions e2e/fixtures/api.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
import { APIRequestContext, PlaywrightWorkerArgs, WorkerFixture } from '@playwright/test';

/**
* A fixture which initializes an [`APIRequestContext`](https://playwright.dev/docs/api/class-apirequestcontext)
* that is bound to the configured OpenMRS API server. The context is automatically authenticated
* using the configured admin account.
*
* Use the request context like this:
* ```ts
* test('your test', async ({ api }) => {
* const res = await api.get('patient/1234');
* await expect(res.ok()).toBeTruthy();
* });
* ```
*/
export const api: WorkerFixture<APIRequestContext, PlaywrightWorkerArgs> = async ({ playwright }, use) => {
const ctx = await playwright.request.newContext({
baseURL: `${process.env.E2E_BASE_URL}/ws/rest/v1/`,
httpCredentials: {
username: process.env.E2E_USER_ADMIN_USERNAME,
password: process.env.E2E_USER_ADMIN_PASSWORD,
},
});

await use(ctx);
};
1 change: 1 addition & 0 deletions e2e/fixtures/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
export * from './api';
Empty file added e2e/pages/index.ts
Empty file.
18 changes: 18 additions & 0 deletions e2e/specs/example.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
import { test, expect } from '@playwright/test';

test('has title', async ({ page }) => {
await page.goto('https://playwright.dev/');

// Expect a title "to contain" a substring.
await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
await page.goto('https://playwright.dev/');

// Click the get started link.
await page.getByRole('link', { name: 'Get started' }).click();

// Expects page to have a heading with the name of Installation.
await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});
6 changes: 6 additions & 0 deletions example.env
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# This is an example environment file for configuring dynamic values.
E2E_BASE_URL=http://localhost:8080/openmrs/
E2E_USER_ADMIN_USERNAME=admin
E2E_USER_ADMIN_PASSWORD=Admin123
E2E_LOGIN_DEFAULT_LOCATION_UUID=44c3efb0-2583-4c80-a79e-1f756a03c0a1
# The above location UUID is for the "Outpatient Clinic" location in the reference application
Loading
Loading