This repository has been archived on 2024-05-31. You can view files and clone it, but cannot push or open issues or pull requests.
IdHub_E2E_testing/README.md

176 lines
7.5 KiB
Markdown
Raw Normal View History

2024-03-04 19:57:54 +00:00
# IdHub E2E Testing Project
## Table of Contents
- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Usage](#usage)
- [Test Structure](#test-structure)
2024-03-07 10:48:17 +00:00
- [Pipeline Integration](#Pipeline-integration)
2024-03-04 19:57:54 +00:00
## Introduction
The Orchestral project focus on developing the IdHub service, which facilitates organisations (acting as issuers or verifiers) and beneficiaries (acting as
subjects and credential holders) to issue, exchange, and verify data in the form of
verifiable credentials for credible and flexible access to benefits or services.
The Administration module enables administrators to manage users and roles, handle
aspects such as the creation of organisational Decentralized Identifiers (DIDs),
management of credentials issued by the organisation, and upload the information for
the issuance of credentials to users (including credential schemes and data).
Conversely, the User module equips users to manage their personal information, create
an identity (DID), request the issuance of a credential, and present these credentials to entities within our user community. This module operates as a user wallet.
The application's backend is responsible for issuing credentials upon user request
through the user module. Meanwhile, the idHub can function as a credential verifier
and engage in dialogues with other idHub instances that operate as user wallets by
implementing the OIDC4VP protocol that we have developed. Consequently, the
IdHub is multifaceted, capable of functioning as an issuer, wallet or verifier.
2024-03-04 20:05:09 +00:00
Playwright is designed for automating browser interactions, making it ideal for end-to-end testing.
2024-03-04 19:57:54 +00:00
The data used in our tests is pre-configurated or generated dynamically during the execution of the tests and is purely fictitious. This approach allows us to create a controlled testing environment isolated from real-world data, ensuring the integrity and reliability of ourtests.
The testing to be executed is grounded in the acceptance criteria defined within the
user stories during the requirements phase. These criteria are designed to match
specific user stories, providing clear, straightforward requirements that must be met
for the final product.
## Getting Started
### Prerequisites
To get started with the IdHub testing project, you need to have the following prerequisites installed on your system:
- **Node.js**: Ensure you have Node.js version 14 or later installed. You can check your version by running `node -v` in your terminal. If you need to install or update Node.js, visit the [official Node.js website](https://nodejs.org/).
- **TypeScript**: The project is written in TypeScript. You should have TypeScript version 4.0 or later. You can install it globally using npm by running `npm install -g typescript`.
- **Playwright**: Playwright is the tool used for end-to-end testing. You can install it by running `npm install playwright`.
### Installation
To clone the repository and install the project dependencies, follow these steps:
1. Open your terminal or command prompt.
2. Navigate to the directory where you want to clone the project.
3. Run `git clone https://github.com/idHub_testing.git` to clone the repository.
4. Navigate into the project directory using `cd idHub_testing`.
5. Install the project dependencies:
- Installing global dependencies: `npm install -g playwright`
- Installing project dependencies: `npm install`
- Setting up environment variables: [TODO]
## Usage
### Running Tests
To run the tests, navigate to the project directory in your terminal and execute the following command:
```bash
2024-03-06 19:57:38 +00:00
npx playwright test
2024-03-04 19:57:54 +00:00
```
This command runs the test suite using Playwright, executing all tests defined in the project.
### Writing Tests: When writing new tests, it's important to follow the established test structure. Here's a brief guide:
- **Test Files**: Place your test files in the `tests` directory, following the naming convention `test-name.spec.ts`.
- **Page Objects**: Use the Page Object Model (POM) pattern for organizing your tests. Each page in your application should have a corresponding Page Object file, e.g., `COMM_loginPage.ts`, `AD_ViewUsersPage.ts`, `US_ViewMyCredentialsPage.ts` (prefix 'AD_' for a page in the admin interface, prefix 'US_' for a page in the user interface, prefix 'COMM_' for common pages). The page objects are stored in the directory `src/page-objects`.
- **Step Definitions**: Define reusable steps within the `steps.ts` This helps in maintaining the tests and promotes code reuse. The `steps.ts` is stored in the `src` directory.
An example of a simple test might look like this:
```typescript
test('Successful login as user', async ({ page }) => {
await loginAsUser(page, USER1_EMAIL, URL_IDHUB);
await expect.soft(page).toHaveTitle('Dashboard IdHub');
})
```
The 'loginAs<User>' function, is defined in `steps.ts` as follow:
```typescript
export async function loginAsUser(page: Page, userEmail: string, url: string) {
try {
const loginPage = new LogInPage(page);
await loginPage.visit(url);
await loginPage.login(userEmail, USER_K);
const currentTitle = await page.title();
if (currentTitle === 'Data Protection IdHub') {
// Code to accept terms and conditions
await page.click('#id_accept_privacy');
await page.click('#id_accept_legal');
await page.click('#id_accept_cookies');
await page.click('a[type="button"]');
}
await expect(page).toHaveTitle('Dashboard IdHub');
} catch (error) {
console.error(`Failed to login as user: `);
throw error;
}
}
```
The 'loginAs<User>' function in `steps.ts` use the 'LoginPage' page object, where are defined all the user related actions (e.g., visit, login, etc.).
## Project Directory Structure
### src directory
- **constants directory:**: Describe....
- **data_stores directory**: Describe...
- **interfaces directory**: Describe
- **page-objects directory**: Describe
- **steps.ts**: Describe
- **utils.ts**: Describe
### tests directory
The tests directory is where all test files are stored. These test files contain the actual tests that Playwright will execute to validate the functionality of the application. The configuration for the tests directory and other related settings are defined in the Playwright configuration file, typically named playwright.config.ts.
### vc_excel directory
describe
2024-03-07 10:48:17 +00:00
## Pipeline integration
2024-03-13 11:10:10 +00:00
### Gitea Actions Workflow Configuration for Running Playwright Tests
Following we outline the configuration of a Gitea Actions workflow.
2024-03-06 19:57:38 +00:00
```yaml
2024-03-13 11:10:10 +00:00
end2end-tests:
needs: deploy-testing-instances
runs-on: self-hosted
2024-03-06 19:57:38 +00:00
steps:
2024-03-13 11:10:10 +00:00
- name: Checkout E2E tests repo
uses: actions/checkout@v4
with:
repository: trustchain-oc1-orchestral/IdHub_E2E_testing
ref: master
token: ${{ secrets.SSIKIT_TOKEN }}
2024-03-06 19:57:38 +00:00
2024-03-13 11:10:10 +00:00
- name: Install dependencies
run: |
npm ci
2024-03-06 19:57:38 +00:00
2024-03-13 11:10:10 +00:00
- name: Install Playwright browsers
run: |
npx playwright install --with-deps
2024-03-06 19:57:38 +00:00
2024-03-13 11:10:10 +00:00
- name: Run Playwright tests
run: |
npx playwright test
2024-03-06 19:57:38 +00:00
2024-03-13 11:10:10 +00:00
```
2024-03-06 19:57:38 +00:00
2024-03-13 11:10:10 +00:00
**Adding reporting**: Uploads the `playwright-report/` directory as an artifact named `playwright-report`. This step always runs, even if previous steps fail, and the artifact is retained for 30 days before automatic deletion.
- uses: actions/upload-artifact@v3
if: always()
with:
name: playwright-report
path: playwright-report/
retention-days: 30
2024-03-06 19:57:38 +00:00
2024-03-04 19:57:54 +00:00