# RoboCorp UI Automation

This repository contains the UI automation framework for the [RoboCorp application](https://robocorp-fe-dev.promptyf.cloud), built using [Playwright](https://playwright.dev/) and TypeScript.

## Current Scope

This README is focused on the prioritized 20-user execution set only:

- Individual users: `A1` to `A10`
- Business users: `B1` to `B10`

These map to:

- `tests/individual_users/`
- `tests/business_users/`

Other specs still exist in the repository, but they are intentionally out of scope for the runbook below.

## Prerequisites

- Node.js (v14 or higher)
- npm (Node Package Manager)

## Setup

1.  **Clone the repository** (if applicable) or navigate to the project directory.

2.  **Install dependencies**:
    ```bash
    npm install
    ```

3.  **Install Playwright Browsers**:
    ```bash
    npx playwright install
    ```

4.  **Configure Environment Variables**:
    Create a `.env` file in the root directory:
    ```env
    USER_PASSWORD=your_password
    USER_FULL_NAME=Automation User
    ACTIVATION_CODE_API_URL=https://user-management-gen2.promptyf.cloud/api/v1/auth/activation-code
    STEAM_EMAIL=your_steam_email
    STEAM_PASSWORD=your_steam_password
    GITHUB_USERNAME=your_github_username
    GITHUB_PASSWORD=your_github_password
    SPOTIFY_USERNAME=your_spotify_username
    SPOTIFY_PASSWORD=your_spotify_password
    ```
    Notes:
    - New-user tests generate a fresh email automatically in the format `automation+<timestamp>@datafab.ai`.
    - Activation code is fetched from `ACTIVATION_CODE_API_URL`.
    - `USER_EMAIL` is not required for the new-user registration flows.
    - `tests/onboarding.spec.ts` generates its own onboarding full name and Ethereum-style wallet address at runtime.
    - Social-provider storage-state capture scripts read provider credentials from `.env`.

## Provider Auth Storages

- Provider storage states are saved under `.auth/` and are ignored by git.
- Supported providers:
  - `steam`
  - `github`
  - `spotify`
- Save a provider storage state:
  ```bash
  npm run save-provider-storage-state -- steam
  npm run save-provider-storage-state -- github
  npm run save-provider-storage-state -- spotify
  ```
- Output files:
  - `.auth/steam-storage-state.json`
  - `.auth/github-storage-state.json`
  - `.auth/spotify-storage-state.json`
- Optional `.env` path variables for tests that reuse provider sessions:
  ```env
  STEAM_STORAGE_STATE_PATH=.auth/steam-storage-state.json
  GITHUB_STORAGE_STATE_PATH=.auth/github-storage-state.json
  SPOTIFY_STORAGE_STATE_PATH=.auth/spotify-storage-state.json
  ```
- GitHub password supports both `GITHUB_PASSWORD` and the current legacy local typo `GITHUH_PASSWORD`.
- To use all saved provider sessions at once, merge them into one storage file:
  ```bash
  npm run merge-storage-states 
  ```
- This writes:
  - `.auth/merged-storage-state.json`
- The merged file intentionally excludes RoboCorp app auth and contains only provider sessions.
- Then run codegen with the merged state:
  ```bash
  npx playwright codegen https://robocorp-fe-dev.promptyf.cloud --load-storage=.auth/merged-storage-state.json
  ```

## Prioritized User Suites

Only the following suites are covered by this README and the intended runner usage:

| User Group | Coverage | Spec file range |
| --- | --- | --- |
| Individual users | `A1` to `A10` | `tests/individual_users/a1_user.spec.ts` to `tests/individual_users/a10_user.spec.ts` |
| Business users | `B1` to `B10` | `tests/business_users/b1_user.spec.ts` to `tests/business_users/b10_user.spec.ts` |

Recommended execution model:

- Run one user spec at a time when validating a specific user.
- Run the full `tests/individual_users` or `tests/business_users` directory for grouped execution.
- Publish a separate report per run so user-specific failures are easy to review.

## Running Tests

### Run a single prioritized user flow
```bash
npx playwright test tests/individual_users/a1_user.spec.ts --project=chromium
```

```bash
npx playwright test tests/business_users/b1_user.spec.ts --project=chromium
```

### Run all prioritized individual users
```bash
npx playwright test tests/individual_users --project=chromium
```

### Run all prioritized business users
```bash
npx playwright test tests/business_users --project=chromium
```

### Run the full prioritized 20-user batch
```bash
npx playwright test tests/individual_users tests/business_users --project=chromium
```

### Run in UI mode (Interactive)
```bash
npx playwright test --ui
```

### Debug mode
```bash
npx playwright test --debug
```

## Viewing Reports

After the tests complete, a report is generated automatically. To open the HTML report:
```bash
npx playwright show-report
```

## Docker

Docker is useful when you want to run this suite in a reproducible environment such as Jenkins or a dedicated runner host.

### Build the image

```bash
docker build -t robocorp-automation .
```

### Run the default test command

This runs the image default command, which is:
```bash
npx playwright test
```

For the prioritized setup, prefer overriding the command with a specific user spec or user directory instead of running the whole repository by default.

The report and test output folders are mounted to the host so they can be viewed after the container exits.

```bash
docker run --rm \
  --env-file .env \
  -v "$(pwd)/playwright-report:/app/playwright-report" \
  -v "$(pwd)/test-results:/app/test-results" \
  robocorp-automation
```

### Run a specific prioritized flow

Override the default command to run a single prioritized user spec:

```bash
docker run --rm \
  --env-file .env \
  -v "$(pwd)/playwright-report:/app/playwright-report" \
  -v "$(pwd)/test-results:/app/test-results" \
  robocorp-automation \
  npx playwright test tests/individual_users/a1_user.spec.ts --project=chromium
```

Run the full prioritized 20-user batch in Docker:

```bash
docker run --rm \
  --env-file .env \
  -v "$(pwd)/playwright-report:/app/playwright-report" \
  -v "$(pwd)/test-results:/app/test-results" \
  robocorp-automation \
  npx playwright test tests/individual_users tests/business_users --project=chromium
```

### Reuse local auth state

If a prioritized user flow depends on persisted Playwright auth files, mount them into the container:

```bash
docker run --rm \
  --env-file .env \
  -v "$(pwd)/playwright/.auth:/app/playwright/.auth" \
  -v "$(pwd)/playwright-report:/app/playwright-report" \
  -v "$(pwd)/test-results:/app/test-results" \
  robocorp-automation \
  npx playwright test tests/business_users/b1_user.spec.ts --project=chromium-auth
```

### View the report

After the container finishes, open the generated HTML report from the host:

```bash
npx playwright show-report playwright-report
```

### Notes

- The image does not include `.env`, `.auth`, or `playwright/.auth`; pass them at runtime.
- `playwright-report/` and `test-results/` are intentionally written outside the container for later review or artifact publishing.
- For Jenkins, use the same `docker run` pattern and archive `playwright-report/` and `test-results/` after the run.

## Project Structure

- `tests/individual_users/`: Prioritized individual user specs `A1` to `A10`.
- `tests/business_users/`: Prioritized business user specs `B1` to `B10`.
- `tests/`: Contains all test specification files, including suites not covered by this README.
- `pages/`: Page Object Models (POM) for properly structuring page interactions.
- `playwright.config.ts`: Main configuration file for Playwright.