IdHub E2E Testing Project

Table of Contents

• Introduction
• Getting Started
• Installation
• Usage
• Test Structure
• Pipeline Integration
• License

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.

Playwright is designed for automating browser interactions, making it ideal 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. 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.
• 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:

npx playwright test

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:

test('Successful login as user', async ({ page }) => {
        await loginAsUser(page, USER1_EMAIL, URL_IDHUB);
        await expect.soft(page).toHaveTitle('Dashboard – IdHub');
    })

The 'loginAs' function, is defined in steps.ts as follow:

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' 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

Pipeline integration

GitHub Actions Workflow Configuration for Running Playwright Tests

Following we outline the configuration of a GitHub Actions workflow designed to running tests on GitHub using GitHub actions It breaks down the key components of the workflow to ensure clarity and understanding.

name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-node@v3
      with:
        node-version: 18
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright Browsers
      run: npx playwright install --with-deps
    - name: Run Playwright tests
      run: npx playwright test
    - uses: actions/upload-artifact@v3
      if: always()
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30

Workflow Name

• Workflow Name: The name of this workflow is "Playwright Tests". This identifier is used within GitHub Actions to reference this workflow.

Trigger Events

• Push to Main or Master Branches: The workflow is triggered on any push event to the main or master branches.
• Pull Requests to Main or Master Branches: Similarly, the workflow is also triggered upon any pull request that targets the main or master branches.

Jobs

• Jobs: The workflow defines a job named test. This job is executed when the workflow is triggered.

Job Configuration

• Timeout: A timeout of 60 minutes is set for this job. If the job exceeds this time, it will be automatically canceled.
• Environment: The job is configured to run on the latest version of Ubuntu provided by GitHub Actions.

Steps

1. Checkout Repository: The first step checks out the repository, allowing the workflow to access it.
   • uses: actions/checkout@v3
2. Setup Node.js Environment: Sets up a Node.js environment using the specified version (Node.js 18).
   • uses: actions/setup-node@v3 with node-version: 18
3. Install Dependencies: Installs the project dependencies using npm ci, leveraging the package-lock.json for precise dependency versions.
   • run: npm ci
4. Install Playwright Browsers: Installs the necessary Playwright browsers along with all necessary system dependencies using npx playwright install --with-deps.
   • run: npx playwright install --with-deps
5. Run Playwright Tests: Executes the Playwright tests using npx playwright test.
   • run: npx playwright test
6. Upload Artifact: 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 with if: always(), name: playwright-report, path: playwright-report/, and retention-days: 30

Summary

This workflow automates the process of running Playwright tests on pushes and pull requests to the main and master branches, ensuring that code changes do not break existing functionality. It includes steps for setting up the environment, installing dependencies, installing necessary browsers for Playwright, running the tests, and uploading test reports as artifacts for review.

License

[Include information about the project's license.]