From f9acce7d7ebf053e155eba542e9ec1177f357c0c Mon Sep 17 00:00:00 2001
From: "v.scharf" <v.scharf@opencloud.eu>
Date: Tue, 14 Jul 2026 13:12:00 +0200
Subject: [PATCH] docs(e2e): add README how to run e2e tests

---
 tests/e2e/README.md            | 89 ++++++++++++++++++++++++++++++++++
 tests/e2e/playwright.config.ts |  6 ++-
 2 files changed, 94 insertions(+), 1 deletion(-)
 create mode 100644 tests/e2e/README.md

diff --git a/tests/e2e/README.md b/tests/e2e/README.md
new file mode 100644
index 0000000000..48f19ca553
--- /dev/null
+++ b/tests/e2e/README.md
@@ -0,0 +1,89 @@
+# E2E Tests
+
+[Gherkin](https://cucumber.io/docs/gherkin/) features run with [Playwright](https://playwright.dev/) via
+[playwright-bdd](https://github.com/vitalets/playwright-bdd).
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Generating Tests From Features](#generating-tests-from-features)
+- [Running Tests From the Terminal](#running-tests-from-the-terminal)
+- [Running Tests in VS Code](#running-tests-in-vs-code)
+- [Test Report](#test-report)
+- [Debugging](#debugging)
+
+## Prerequisites
+
+- A running OpenCloud backend (root [docker-compose.yml](../../docker-compose.yml), `docker-compose up -d`)
+- `pnpm build` run once (repo root)
+- Install playwright browsers: `npx playwright install` (in `tests/e2e`)
+
+## Generating Tests From Features
+
+Feature files (`tests/e2e/features/**/*.feature`) are compiled into Playwright spec (`tests/e2e/.features-gen`, gitignored)
+files with [playwright-bdd](https://github.com/vitalets/playwright-bdd):
+
+```bash
+(cd tests/e2e pnpm bddgen)
+```
+
+> [!IMPORTANT]
+> Re-run after adding/changing a `.feature` file or adding/renaming a step. All commands below assume
+> `.features-gen` is up to date.
+
+## Running Tests From the Terminal
+
+```bash
+pnpm test:e2e   # from repo root: runs bddgen + playwright test
+```
+
+Tests run **headless** by default. See the [Playwright CLI docs](https://playwright.dev/docs/test-cli) for all flags:
+
+```bash
+pnpm test:e2e --headed                                          # show the browser
+pnpm test:e2e test --ui                                         # interactive UI mode (https://playwright.dev/docs/test-ui-mode)
+pnpm test:e2e favorites.feature.spec.js:10 --project=chromium   # single scenario, single project
+pnpm test:e2e -g "mark and unmark resources as favorites using batch action"
+pnpm test:e2e --workers=1                                       # override worker count (default: ~4 locally, 1 on CI)
+```
+
+Available [projects](./playwright.config.ts): `chromium`, `firefox`, `webkit`, `mobile-chromium`, `mobile-webkit`,
+`ipad-chromium`, `ipad-landscape-webkit`.
+
+Useful env vars (set before the command, e.g. `OC_BASE_URL=... pnpm test:e2e`; full list in
+[`playwright.config.ts`](./playwright.config.ts) `appConfig`):
+
+| Variable                       | Default                     | Description                      |
+| ------------------------------ | --------------------------- | -------------------------------- |
+| `OC_BASE_URL`                  | `host.docker.internal:9200` | URL of the OpenCloud instance    |
+| `BASIC_AUTH`                   | `false`                     | Basic auth instead of OIDC login |
+| `KEYCLOAK`                     | `false`                     | Enable Keycloak-specific tests   |
+| `FEDERATED_SERVER`             | `false`                     | Run against the federated server |
+| `SLOW_MO`                      | `0`                         | Slow down operations by N ms     |
+| `TEST_TIMEOUT`                 | `120`                       | Per-test timeout in seconds      |
+| `FAIL_ON_UNCAUGHT_CONSOLE_ERR` | `true`                      | Fail on uncaught console errors  |
+
+## Running Tests in VS Code
+
+Install [Playwright Test for VSCode](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright)
+(recommended in [`.vscode/extensions.json`](../../.vscode/extensions.json)).
+
+1. `cd tests/e2e && pnpm bddgen` at least once.
+2. Open the **Testing** sidebar (flask icon) — generated specs appear as a tree.
+3. Run/debug via the ▶ icons; toggle "Show browser" for `--headed`.
+
+## Test Report
+
+[HTML report](https://playwright.dev/docs/test-reporters#html-reporter) of the **last test run**
+(`playwright-report/`):
+
+```bash
+(cd tests/e2e && pnpm exec playwright show-report)
+```
+
+## Debugging
+
+- `pnpm playwright test --debug` — [Playwright Inspector](https://playwright.dev/docs/debug#playwright-inspector)
+  (combine with `--project=chromium -g "scenario name"` to target one test).
+- `pnpm playwright show-trace <trace.zip>` — [Trace Viewer](https://playwright.dev/docs/trace-viewer) for a recorded
+  trace (recorded `on-first-retry` by default, see `playwright.config.ts`).
diff --git a/tests/e2e/playwright.config.ts b/tests/e2e/playwright.config.ts
index 00ecd057ee..05f8ece0f1 100644
--- a/tests/e2e/playwright.config.ts
+++ b/tests/e2e/playwright.config.ts
@@ -1,5 +1,9 @@
 import { defineConfig, devices } from '@playwright/test'
 import { defineBddConfig } from 'playwright-bdd'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 /**
  * Read environment variables from file.
@@ -8,7 +12,7 @@ import { defineBddConfig } from 'playwright-bdd'
 // import dotenv from 'dotenv';
 // import path from 'path';
 const testDir = defineBddConfig({
-  featuresRoot: './features',
+  featuresRoot: path.join(__dirname, 'features'),
   steps: ['steps/ui/*.ts', 'steps/*.ts', 'environment/fixtures.ts', 'environment/hooks.ts']
 })