180 lines
9.0 KiB
Markdown
180 lines
9.0 KiB
Markdown
# IdHub E2E Testing Project
|
||
|
||
## Table of Contents
|
||
- [Introduction](#introduction)
|
||
- [Getting Started](#getting-started)
|
||
- [Installation](#installation)
|
||
- [Usage](#usage)
|
||
- [Test Structure](#test-structure)
|
||
- [Pipeline Integration](#Pipeline-integration)
|
||
|
||
## 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.
|
||
|
||
|
||
We use Playwright for automating browser interactions for end-to-end testing.
|
||
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.
|
||
|
||
## 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/).
|
||
|
||
### 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://gitea.pangea.org/trustchain-oc1-orchestral/IdHub_E2E_testing.git` to clone the repository.
|
||
4. Navigate into the project directory using `cd idHub_E2E_testing`.
|
||
5. Install project dependencies: `npm install`
|
||
6. Set-up the **URL_IDHUB** value in the file **env_constants.ts** in the directory src/constants.ts, to point to the appropiate IdHub instance.
|
||
|
||
|
||
## Usage
|
||
### Running Tests
|
||
|
||
To run the tests, navigate to the project directory in your terminal and execute the following command:
|
||
|
||
```bash
|
||
npx playwright test
|
||
```
|
||
|
||
This command runs the test suite using Playwright, executing all tests defined in the project.
|
||
|
||
In the `playwright-report/` directory there is an index.html file with the result of all test done.
|
||
|
||
### 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, 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(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);
|
||
const dataProtectionPage = new DataProtectionPage(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 dataProtectionPage.checkAcceptPrivacyCheckBox();
|
||
await dataProtectionPage.checkAcceptCookiesCheckBox();
|
||
await dataProtectionPage.checkAcceptLegalCheckBox();
|
||
await dataProtectionPage.clickConfirmButton();
|
||
}
|
||
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.) and the 'DataProtectionPage' page object where the interactions to accept or deny the data protection options are defined.
|
||
|
||
## Project Directory Structure
|
||
|
||
### src/constants directory
|
||
|
||
The **constants.ts** file defines a collection of constants used for various purposes within a project, including file paths, JSON schema names and URLs, Excel file names for testing, schema names and types as they appear in the Idhub Admin interface, user alert messages, status types, and membership types. These constants are likely used across the project for consistent references to file paths, schema identifiers, and other configuration details, ensuring that changes to these values only need to be made in one place.
|
||
|
||
The **env_constants.ts** file defines environmental variables related to the specific instances used in the tests.
|
||
|
||
The **credentials_fields.ts** file is designed to store and manage constant values related to the fields or properties of the diferent types of credentials defined in the pilots.
|
||
|
||
### src/data_stores directory
|
||
|
||
The **credential_data_store.ts** file serves as a data store for different types of credentials, each represented as an array of objects. This structure is particularly useful for testing or simulating a database of credentials without the need for a backend service. Each type of credential, such as FinancialVulnerabilityCredential_data, MembershipCard_data, FederationMembership_data, CourseCredential_data, and EOperatorClaim_data, is populated with example data. The file also includes a section for undefined credential data (CREDENTIAL_TYPE_DATASTORE_UNDEFINED), as mock data for handle cases where credential data is not available.
|
||
|
||
The **users_data_store.ts** file contains simulated user data for testing purposes.
|
||
|
||
### src/interfaces directory
|
||
|
||
The **credential_interfaces.ts** file defines the interfaces that represent the structure of different types of credentials. Each interface specifies the fields that a credential object must have, along with the type of each field.
|
||
|
||
### src/page-objects directory
|
||
Here there are the Page Objects files corresponding to each tested page in the application. 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).
|
||
|
||
### src/steps.ts file contains reusable steps within that helps to maintain the tests and promotes code reuse.
|
||
|
||
### 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
|
||
A set of excel data files for each type of credentials, used to test the data file import functionality to enable credentials.
|
||
|
||
|
||
## Pipeline integration
|
||
|
||
### Gitea Actions Workflow Configuration for Running Playwright Tests
|
||
|
||
Following we outline the configuration of a Gitea Actions workflow.
|
||
|
||
```yaml
|
||
end2end-tests:
|
||
needs: deploy-testing-instances
|
||
runs-on: self-hosted
|
||
steps:
|
||
|
||
- name: Checkout E2E tests repo
|
||
uses: actions/checkout@v4
|
||
with:
|
||
repository: trustchain-oc1-orchestral/IdHub_E2E_testing
|
||
ref: master
|
||
token: ${{ secrets.SSIKIT_TOKEN }}
|
||
|
||
- name: Install dependencies
|
||
run: |
|
||
npm ci
|
||
|
||
- name: Install Playwright browsers
|
||
run: |
|
||
npx playwright install --with-deps
|
||
|
||
- name: Run Playwright tests
|
||
run: |
|
||
npx playwright test
|
||
|
||
```
|
||
|
||
|
||
|