Add comprehensive end-to-end testing infrastructure with Playwright (#749)

### Summary & Motivation

This change establishes a comprehensive end-to-end testing
infrastructure using Playwright, providing a robust foundation for
testing user workflows across all self-contained systems. The
implementation includes authentication fixtures, test utilities, and
organized test suites that ensure application functionality works
correctly from a user's perspective.

Key features:
- Shared Playwright configuration and utilities in shared-webapp for
consistency across systems
- Worker-scoped authentication fixtures enabling parallel test execution
with isolated tenants
- Reusable test utilities including step decorators, assertions, and
test data generators
- Organized test flows covering authentication, user management,
permissions, themes, localization, and mobile views
- Performance optimizations including toast auto-closing and improved
error handling
- IDE integration for VS Code with debugging support
- Separation of smoke tests (@smoke), comprehensive tests
(@comprehensive), and slow tests (@slow)

The infrastructure supports multiple browsers (Chromium, Firefox,
WebKit) and provides detailed test reporting with screenshots and traces
on failures. Tests are organized by functional areas and use descriptive
step names for maintainability.

### Downstream projects

1. Copy the Playwright test configuration files from Back Office to your
self-contained system:
- Copy `application/back-office/WebApp/tests/playwright.config.ts` to
`your-self-contained-system/WebApp/tests/playwright.config.ts`
- Copy `application/back-office/WebApp/tests/tsconfig.json` to
`your-self-contained-system/WebApp/tests/tsconfig.json`

2. Update `your-self-contained-system/WebApp/rsbuild.config.ts` to
exclude test files from the build:

```diff
  server: {
    port: Number.parseInt(process.env.PORT || "9003"),
+   publicDir: {
+     name: "public",
+     copyOnBuild: true
+   }
  },
+ source: {
+   exclude: ["**/tests/**/*"]
+ }
```

3. Update `your-self-contained-system/WebApp/tsconfig.json` to exclude
test files:

```diff
  "compilerOptions": {
    // ... existing options
  },
- "exclude": ["node_modules", "dist"]
+ "exclude": ["node_modules", "dist", "tests"]
```

4. Create your first end-to-end test in
`your-self-contained-system/WebApp/tests/e2e/homepage.spec.ts` following
the pattern from Back Office.

### Checklist

- [x] I have added tests, or done manual regression tests
- [x] I have updated the documentation, if necessary

Author: tjementum

.cursor/rules/end-to-end-tests/e2e-tests.mdc

@@ -0,0 +1,262 @@
+---
+description: Rules for end-to-end tests
+globs: */tests/e2e/**
+alwaysApply: false
+---
+# End-to-End Tests
+
+These rules outline the structure, patterns, and best practices for writing end-to-end tests.
+
+## Implementation
+
+1. Use `[CLI_ALIAS] e2e` with these option categories to optimize test execution:
+   - Test filtering: `--smoke`, `--include-slow`, search terms (e.g., `"@smoke"`, `"smoke"`, `"user"`, `"localization"`), `--browser`
+   - Change scoping: `--last-failed`, `--only-changed`  
+   - Flaky test detection: `--repeat-each`, `--retries`, `--stop-on-first-failure`
+   - Performance: `--debug-timings` shows step execution times with color coding
+
+2. Test Search and Filtering:
+   - Search by test tags: `[CLI_ALIAS] e2e "@smoke"` or `[CLI_ALIAS] e2e "smoke"` (both work the same)
+   - Search by test content: `[CLI_ALIAS] e2e "user"` (finds tests with "user" in title or content)
+   - Search by filename: `[CLI_ALIAS] e2e "localization"` (finds localization-flows.spec.ts)
+   - Search by specific file: `[CLI_ALIAS] e2e "user-management-flows.spec.ts"`
+   - Multiple search terms: `[CLI_ALIAS] e2e "user" "management"`
+   - The CLI automatically detects which self-contained systems contain matching tests and only runs those
+
+3. Test-Driven Debugging Process:
+   - Focus on one failing test at a time and make it pass before moving to the next.
+   - Ensure tests use Playwright's built-in auto-waiting assertions: `toHaveURL()`, `toBeVisible()`, `toBeEnabled()`, `toHaveValue()`, `toContainText()`.
+   - Consider if root causes can be fixed in the application code, and fix application bugs rather than masking them with test workarounds.
+
+4. Organize tests in a consistent file structure:
+   - All e2e test files must be located in `[self-contained-system]/WebApp/tests/e2e/` folder (e.g., `application/account-management/WebApp/tests/e2e/`).
+   - All test files use the `*-flows.spec.ts` naming convention (e.g., `login-flows.spec.ts`, `signup-flows.spec.ts`, `user-management-flows.spec.ts`).
+   - Top-level describe blocks must use only these 3 approved tags: `test.describe("@smoke", () => {})`, `test.describe("@comprehensive", () => {})`, `test.describe("@slow", () => {})`.
+   - `@smoke` tests:
+     - Critical tests run on deployment of any self-contained system.
+     - Should be comprehensive scenarios that test core user journeys.
+     - Keep tests focused on specific flows to reduce fragility while maintaining coverage.
+     - Focus on must-work functionality with extensive validation steps.
+     - Include boundary cases and error handling within the same test scenario.
+     - Avoid testing the same functionality multiple times across different tests.
+
+   - `@comprehensive` tests:
+     - Thorough tests run when a specific self-contained system is deployed.
+     - Focus on edge cases, error conditions, and less common scenarios.
+     - Test specific features in depth with various input combinations.
+     - Include tests for concurrency, validation rules, accessibility, etc.
+     - Group related edge cases together to reduce test count while maintaining coverage.
+
+   - `@slow` tests:
+     - Optional and run only ad-hoc using `--include-slow` flag.
+     - Any tests that require waiting like `waitForTimeout` (e.g., for OTP timeouts) must be marked as `@slow`.
+     - Include tests for rate limiting with actual wait times, session timeouts, etc.
+     - Use `test.setTimeout()` at the individual test level based on actual wait times needed.
+
+5. Write clear test descriptions and documentation:
+   - Test descriptions must accurately reflect what the test covers and be kept in sync with test implementation.
+   - Use descriptive test names that clearly indicate the functionality being tested (e.g., "should handle single and bulk user deletion workflows with dashboard integration").
+   - Include JSDoc comments above complex tests listing all major features/scenarios covered.
+   - When adding new functionality to existing tests, update both the test description and JSDoc comments to reflect changes.
+
+6. Structure each test with step decorators and proper monitoring:
+   - All tests must start with `const context = createTestContext(page);` for proper error monitoring.
+   - Use step decorators: `await step("Complete signup & verify account creation")(async () => { /* test logic */ })();`
+   - Step naming conventions:
+     - Always follow "[Business action + details] & [expected outcome]" pattern.
+     - Use business action verbs like "Sign up", "Login", "Invite", "Rename", "Update", "Delete", "Create", "Submit".
+     - Never use test/assertion prefixes like "Test", "Verify", "Check", "Validate", "Ensure"; use descriptive business actions instead.
+     - Every step must include an action (arrange/act) followed by assertions, not pure assertion steps.
+   - Step structure:
+     - Use blank lines to separate arrange/act/assert sections within steps.
+     - Keep shared variable declarations outside steps when used across multiple steps.
+     - Use section headers with `// === SECTION NAME ===` to group related steps.
+     - Add JSDoc comments for complex test workflows.
+   - Use semantic selectors: `page.getByRole("button", { name: "Submit" })`, `page.getByText("Welcome")`, `page.getByLabel("Email")`.
+   - Assert side effects immediately after actions using `expectToastMessage`, `expectValidationError`, `expectNetworkErrors`.
+   - Form validation pattern: Use `await blurActiveElement(page);` when updating a textbox the second time before submitting a form to trigger validation.
+
+7. Timeout Configuration:
+   - Always use Playwright's built-in auto-waiting assertions: `toHaveURL()`, `toBeVisible()`, `toBeEnabled()`, `toHaveValue()`, `toContainText()`.
+   - Never add timeouts to `.click()`, `.waitForSelector()`, etc.
+   - Global timeout configuration is handled in the shared Playwright. Don't change this.
+
+8. Write deterministic tests - This is critical for reliable testing:
+   - Each test should have a clear, linear flow of actions and assertions.
+   - Never use if statements, custom error handling, or try/catch blocks in tests.
+   - Never use regular expressions in tests; use simple string matching instead.
+
+9. What to test:
+   - Enter invalid values, such as empty strings, only whitespace characters, long strings, negative numbers, Unicode, etc.
+   - Tooltips, keyboard navigation, accessibility, validation messages, translations, responsiveness, etc.
+
+10. Test Fixtures and Page Management:
+   - Use appropriate fixtures: `{ page }` for basic tests, `{ anonymousPage }` for tests with existing tenant/owner but not logged in, `{ ownerPage }`, `{ adminPage }`, `{ memberPage }` for authenticated tests.
+   - Destructure anonymous page data: `const { page, tenant } = anonymousPage; const existingUser = tenant.owner;`
+   - Pre-logged in users (`ownerPage`, `adminPage`, `memberPage`) are isolated between workers and will not conflict between tests.
+   - When using pre-logged in users, do not put the tenant or user into an invalid state that could affect other tests.
+
+11. Test Data and Constants:
+   - Use underscore separators: `const timeout = 30_000; // 30 seconds`
+   - Generate unique data: `const email = uniqueEmail();`
+   - Use faker.js to generate realistic test data: `const firstName = faker.person.firstName(); const email = faker.internet.email();`
+   - Long string testing: `const longEmail = \`${"a".repeat(90)}@example.com\`; // 101 characters total`
+
+12. Memory Management in E2E Tests:
+    - Playwright automatically handles browser context cleanup after tests
+    - Manual cleanup steps are unnecessary - focus on test clarity over micro-optimizations
+    - E2E test suites have minimal memory leak concerns due to their limited scope and duration
+
+## Examples
+
+### ✅ Good Step Naming Examples
+```typescript
+// ✅ DO: Business action + details & expected outcome
+await step("Submit invalid email & verify validation error")(async () => {
+  await page.getByLabel("Email").fill("invalid-email");
+  await blurActiveElement(page);
+  
+  await expectValidationError(context, "Invalid email.");
+})();
+
+await step("Sign up with valid credentials & verify account creation")(async () => {
+  await page.getByRole("button", { name: "Submit" }).click();
+  
+  await expect(page.getByText("Welcome")).toBeVisible();
+})();
+
+await step("Update user role to admin & verify permission change")(async () => {
+  const userRow = page.locator("tbody tr").first();
+  
+  await userRow.getByLabel("User actions").click();
+  await page.getByRole("menuitem", { name: "Change role" }).click();
+  
+  await expect(page.getByRole("alertdialog", { name: "Change user role" })).toBeVisible();
+})();
+```
+
+### ❌ Bad Step Naming Examples
+```typescript
+// ❌ DON'T: Pure assertion steps without actions
+await step("Verify button is visible")(async () => {
+  await expect(page.getByRole("button")).toBeVisible(); // No action, only assertion
+})();
+
+// ❌ DON'T: Using test/assertion prefixes
+await step("Check user permissions")(async () => { // "Check" is assertion prefix
+  await expect(page.getByText("Admin")).toBeVisible();
+})();
+
+await step("Validate form state")(async () => { // "Validate" is assertion prefix
+  await expect(page.getByRole("textbox")).toBeEmpty();
+})();
+
+await step("Ensure user is deleted")(async () => { // "Ensure" is assertion prefix
+  await expect(page.getByText("user@example.com")).not.toBeVisible();
+})();
+```
+
+### ✅ Complete Test Example
+```typescript
+import { step } from "@shared/e2e/utils/step-decorator";
+import { expectValidationError, blurActiveElement, createTestContext } from "@shared/e2e/utils/test-assertions";
+import { testUser } from "@shared/e2e/utils/test-data";
+
+test.describe("@smoke", () => {
+  test("should complete signup with validation", async ({ page }) => {
+    const context = createTestContext(page);
+    const user = testUser();
+
+    await step("Submit invalid email & verify validation error")(async () => {
+      await page.goto("/signup");
+      await page.getByLabel("Email").fill("invalid-email");
+      await blurActiveElement(page); // ✅ DO: Trigger validation when updating textbox second time
+
+      await expectValidationError(context, "Invalid email.");
+    })();
+
+    await step("Sign up with valid email & verify verification redirect")(async () => {
+      await page.getByLabel("Email").fill(user.email);
+      await page.getByRole("button", { name: "Continue" }).click();
+
+      await expect(page).toHaveURL("/verify");
+    })();
+  });
+});
+
+test.describe("@comprehensive", () => {
+  test("should handle user management with pre-logged owner", async ({ ownerPage }) => {
+    createTestContext(ownerPage); // ✅ DO: Create context for pre-logged users
+
+    await step("Access user management & verify owner permissions")(async () => {
+      await ownerPage.getByRole("button", { name: "Users" }).click();
+
+      await expect(ownerPage.getByRole("heading", { name: "Users" })).toBeVisible();
+    })();
+  });
+});
+
+test.describe("@slow", () => {
+  const requestNewCodeTimeout = 30_000; // 30 seconds
+  const codeValidationTimeout = 60_000; // 5 minutes
+  const sessionTimeout = codeValidationTimeout + 60_000; // 6 minutes
+
+  test("should handle user logout after to many login attempts", async ({ page }) => { // ✅ DO: use new page, when testing e.g. account lockout
+    test.setTimeout(sessionTimeout); // ✅ DO: Set timeout based on actual wait times
+    const context = createTestContext(page);
+
+    // ...
+
+    await step("Wait for code expiration & verify timeout behavior")(async () => {
+      await page.goto("/login/verify");
+      await page.waitForTimeout(codeValidationTimeout); // ✅ DO: Use actual waits in @slow tests
+
+      await expect(page.getByText("Your verification code has expired")).toBeVisible();
+    })();
+  });
+});
+```
+
+```typescript
+test.describe("@security", () => { // ❌ DON'T: Don't invent new tags - use @smoke, @comprehensive, @slow only
+  test("should handle login", async ({ page }) => {
+    // ❌ DON'T: Skip createTestContext(page); step
+    page.setDefaultTimeout(5000); // ❌ DON'T: Set timeouts manually - use global config
+    
+    // ❌ DON'T: Use test/assertion prefixes in step descriptions
+    await step("Test login functionality")(async () => { // ❌ Should be "Submit login form & verify authentication"
+    await step("Verify button is visible")(async () => { // ❌ Should be "Navigate to page & verify button is visible"
+    await step("Check user permissions")(async () => { // ❌ Should be "Click user menu & verify permissions"
+      if (page.url().includes("/login/verify")) { // ❌ DON'T: Add conditional logic - tests should be linear
+        await page.waitForTimeout(2000); // ❌ DON'T: Add manual timeouts
+        // Continue with verification... // ❌ DON'T: Write verbose explanatory comments
+      }
+      
+      await page.click("#submit-btn"); // ❌ DON'T: Use CSS selectors - use semantic selectors
+      
+      // ❌ DON'T: Skip assertions for side effects
+    })();
+
+    // ❌ DON'T: Use regular expressions - use simple string matching instead
+    await expect(page.getByText(/welcome.*home/i)).toBeVisible(); // ❌ Should be: page.getByText("Welcome home")
+    await expect(page.locator('input[name*="email"]')).toBeFocused(); // ❌ Should be: page.getByLabel("Email")
+  });
+
+  // ❌ DON'T: Place assertions outside test functions
+  expect(page.url().includes("/admin") || page.url().includes("/login")).toBeTruthy(); // ❌ DON'T: Use ambiguous assertions
+
+  // ❌ DON'T: Use try/catch to handle flaky behavior - makes tests unreliable
+  try {
+    await page.waitForLoadState("networkidle"); // ❌ DON'T: Add timeout logic in tests
+    await page.getByRole("button", { name: "Submit" }).click({ timeout: 1000 }); // ❌ DON'T: Add timeouts to actions
+  } catch (error) {
+    await page.waitForTimeout(1000); // ❌ DON'T: Add manual waits
+    console.log("Retrying..."); // ❌ DON'T: Add custom error handling
+  }
+});
+
+// ❌ DON'T: Create tests without proper organization
+test("isolated test without describe block", async ({ page }) => {
+  // ❌ DON'T: Violates organization rules
+});
+```

.cursor/rules/workflows/create-e2e-tests.mdc

@@ -0,0 +1,64 @@
+---
+description: Workflow for creating end-to-end tests
+globs: 
+alwaysApply: false
+---
+# E2E Testing Workflow
+
+This workflow guides you through the process of creating comprehensive end-to-end tests for specific features like login and signup. It focuses on identifying what tests to write, planning complex scenarios, and ensuring tests follow the established conventions.
+
+## Workflow
+
+1. Understand the feature under test:
+   - Study the frontend components and their interactions.
+   - Review API endpoints and authentication flows.
+   - Understand validation rules and error handling.
+   - Identify key user interactions and expected behaviors.
+
+2. Use Browser MCP to explore the webapp functionality:
+   - Navigate to the application: `mcp0_browser_navigate({ url: "https://localhost:9000" })`.
+   - Interact with the feature manually to understand user flows.
+   - Take snapshots to identify UI elements and their structure.
+   - Document key interactions and expected behaviors.
+   - Note any edge cases or potential issues discovered during exploration.
+
+3. Review existing test examples:
+   - Read [End-to-End Tests](/.cursor/rules/end-to-end-tests/e2e-tests.mdc) for detailed information.
+   - Examine [signup.spec.ts](/application/account-management/WebApp/tests/e2e/signup.spec.ts) and [login.spec.ts](/application/account-management/WebApp/tests/e2e/login.spec.ts) for inspiration.
+   - Note the structure, assertions, test organization, and the "Act & Assert:" comment format.
+
+4. Plan comprehensive test scenarios:
+   - Identify standard user journeys through the feature.
+   - Plan for complex multi-session scenarios like:
+     - Concurrent sessions: What happens when a user has two tabs open?
+     - Cross-session state changes: What happens when state changes in one session affect another?
+     - Authentication conflicts: How does the system handle authentication changes across sessions?
+     - Form submissions across sessions: What happens with concurrent form submissions?
+     - Antiforgery token handling: How are antiforgery tokens managed across tabs?
+     - Browser navigation: Back/forward buttons, refresh, direct URL access.
+     - Network conditions: Slow connections, disconnections during operations.
+     - Input validation: Boundary values, special characters, extremely long inputs.
+     - Accessibility: Keyboard navigation, screen reader compatibility.
+     - Localization: Testing with different languages and formats.
+
+5. Categorize tests appropriately:
+   - `@smoke`: Essential functionality that will run on deployment of any system.
+     - Create one comprehensive smoke.spec.ts per self-contained system.
+     - Test complete user journeys: signup → profile setup → invite users → manage roles → tenant settings → logout.
+     - Include validation errors, retries, and recovery scenarios within the journey.
+   - `@comprehensive`: More thorough tests covering edge cases that will run on deployment of the system under test.
+     - Focus on specific feature areas with deep testing of edge cases.
+     - Group related scenarios to minimize test count while maximizing coverage.
+   - `@slow`: Tests involving timeouts or waiting periods that will run ad-hoc, when features under test are changed.
+
+6. Create or update test structure:
+   - For smoke tests: Create/update `application/[scs-name]/WebApp/tests/e2e/smoke.spec.ts`.
+   - For comprehensive tests: Create feature-specific files like `user-management.spec.ts`, `authentication.spec.ts`.
+   - Avoid creating many small, isolated tests - prefer comprehensive scenarios that test multiple aspects.
+
+## Key principles
+
+- Comprehensive coverage: Test all critical paths and important edge cases.
+- Follow conventions: Adhere to the established patterns in [End-to-End Tests](/.cursor/rules/end-to-end-tests/e2e-tests.mdc).
+- Clear organization: Properly categorize tests and use descriptive names.
+- Realistic user journeys: Test scenarios that reflect actual user behavior.

.cursor/rules/workflows/implement-product-increment.mdc

@@ -17,10 +17,14 @@ Follow these steps which describe in detail how you must implement the tasks in
 
   Before implementing each task, review the relevant rules thoroughly:
 
-  - For **backend tasks**:
-    - Review all the [Backend](mdc:.cursor/rules/backend) rule files.
-  - For **frontend tasks**:
-    - Review all the [Frontend](mdc:.cursor/rules/frontend) rule files.
+- For **backend tasks**:
+  - Review all the [Backend](mdc:.cursor/rules/backend) rule files.
+- For **frontend tasks**:
+  - Review all the [Frontend](mdc:.cursor/rules/frontend) rule files.
+- For **end-to-end tests**:
+  - Review the [E2E Testing Workflow](mdc:.cursor/rules/workflows/create-e2e-tests.mdc) and all the [End-to-End Tests](mdc:.cursor/rules/end-to-end-tests) rule files.
+- For **Developer CLI commands**:
+  - Review all the [Developer CLI](mdc:.cursor/rules/developer-cli) rule files.
 
 These rules define the conventions and must be strictly adhered to during implementation.
 

.gitignore

@@ -400,3 +400,10 @@ dist/
 
 # Git submodules
 .gitmodules
+
+# Playwright E2E testing artifacts
+test-results/
+playwright-report/
+**/playwright/.cache/
+**/.auth/
+

.vscode/extensions.json

@@ -1,8 +1,9 @@
 {
   "recommendations": [
+    "biomejs.biome",
     "bradlc.vscode-tailwindcss",
     "ms-azuretools.vscode-bicep",
-    "github.vscode-github-actions",
-    "biomejs.biome",
+    "ms-playwright.playwright",
+    "github.vscode-github-actions"
   ]
 }