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

(test) O3 2411: Setting up esm-home repository for E2E testing #168

Open
wants to merge 2 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
63 changes: 63 additions & 0 deletions .github/workflows/e2e.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
name: E2E Tests

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

jobs:
main:
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- name: Checkout repo
uses: actions/checkout@v3

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

- name: Setup node
uses: actions/setup-node@v3
with:
node-version: "16.x"

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

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

- name: Install Playwright Browsers
run: npx playwright install chromium --with-deps

- 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@v3
if: always()
with:
name: playwright-report
path: playwright-report/
retention-days: 30
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -79,3 +79,9 @@ dist

# i18next parser creating moduleName folder when parsing index.ts
moduleName

# Playwright and e2e tests
/test-results/
/playwright-report/
/playwright/.cache/
e2e/storageState.json
Binary file added e2e/.DS_Store
Binary file not shown.
115 changes: 115 additions & 0 deletions e2e/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
# 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 --sources 'packages/esm-*-app/'
```
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:
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) `example.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```
32 changes: 32 additions & 0 deletions e2e/core/global-setup.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
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: {
'Content-Type': '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';
9 changes: 9 additions & 0 deletions e2e/pages/home-page.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
import { Page } from '@playwright/test';

export class HomePage {
constructor(readonly page: Page) {}

async goto() {
await this.page.goto(`home`);
}
}
1 change: 1 addition & 0 deletions e2e/pages/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
export * from './home-page';
10 changes: 10 additions & 0 deletions e2e/specs/sample-test.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
import { test, expect } from '@playwright/test';
import { HomePage } from '../pages';

// This test is a sample E2E test. You can delete it.

test('Sample test', async ({ page }) => {
const homePage = new HomePage(page);
await homePage.goto();
await expect(homePage.page.getByRole('link', { name: 'Home' })).toBeVisible();
});
34 changes: 34 additions & 0 deletions e2e/support/github/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# syntax=docker/dockerfile:1.3
FROM --platform=$BUILDPLATFORM node:18-alpine as dev

ARG APP_SHELL_VERSION=next

RUN mkdir -p /app
WORKDIR /app

COPY . .

RUN npm_config_legacy_peer_deps=true npm install -g openmrs@${APP_SHELL_VERSION:-next}
ARG CACHE_BUST
RUN npm_config_legacy_peer_deps=true openmrs assemble --manifest --mode config --config spa-assemble-config.json --target ./spa

FROM --platform=$BUILDPLATFORM openmrs/openmrs-reference-application-3-frontend:nightly as frontend
FROM nginx:1.23-alpine

RUN apk update && \
apk upgrade && \
# add more utils for sponge to support our startup script
apk add --no-cache moreutils

# clear any default files installed by nginx
RUN rm -rf /usr/share/nginx/html/*

COPY --from=frontend /etc/nginx/nginx.conf /etc/nginx/nginx.conf
# this assumes that NOTHING in the framework is in a subdirectory
COPY --from=frontend /usr/share/nginx/html/* /usr/share/nginx/html/
COPY --from=frontend /usr/local/bin/startup.sh /usr/local/bin/startup.sh
RUN chmod +x /usr/local/bin/startup.sh

COPY --from=dev /app/spa/ /usr/share/nginx/html/

CMD ["/usr/local/bin/startup.sh"]
24 changes: 24 additions & 0 deletions e2e/support/github/docker-compose.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# This docker compose file is used to create a backend environment for the e2e.yml workflow.
version: "3.7"

services:
gateway:
image: openmrs/openmrs-reference-application-3-gateway:${TAG:-nightly}
ports:
- "8080:80"

frontend:
build:
context: .
environment:
SPA_PATH: /openmrs/spa
API_URL: /openmrs

backend:
image: openmrs/openmrs-reference-application-3-backend:nightly-with-data
depends_on:
- db

# MariaDB
db:
image: openmrs/openmrs-reference-application-3-db:nightly-with-data
Loading