test(ui): adds playwright setup

services/dashboard-ui/.gitignore

@@ -40,3 +40,9 @@ src/types/nuon-oapi-v3.d.ts
 NOTES.md
 compilation-analysis.json
 analyze.js
+
+# Playwright E2E testing
+/test-results/
+/playwright-report/
+/e2e-results/
+playwright/.cache/

services/dashboard-ui/AGENTS.md

@@ -1350,6 +1350,111 @@ export type TEnhancedInstall = components['schemas']['app.Install'] & {
 
 **Component Interfaces** (`I` prefix): Manually defined in component files or shared in `/src/types/`
 
+## E2E User Flow Documentation System
+
+The dashboard uses a structured approach to documenting and testing user flows. This system enables non-technical team members (Product, Design, QA) to document critical user journeys that can be automated with Playwright.
+
+### Directory Structure
+
+- `/e2e/flows/` - User flow documentation (markdown files)
+- `/e2e/tests/` - Playwright test implementations
+- `/e2e/fixtures/` - Reusable test utilities (auth, helpers)
+
+### For Non-Technical Contributors
+
+**Writing a User Flow**:
+
+1. **Copy the template**: `/e2e/flows/TEMPLATE.md`
+2. **Name your flow**: Use kebab-case (e.g., `create-install.md`, `deploy-workflow.md`)
+3. **Fill in the sections**:
+   - **Prerequisites**: What needs to be true before starting
+   - **User Flow**: Step-by-step actions
+   - **Test Data**: Example data used in the flow
+   - **Edge Cases**: What could go wrong
+
+4. **For each step, document**:
+   - What the user does (click, type, select)
+   - What should happen (expected result)
+   - Visible text on buttons/links
+   - Form field names (if known)
+   - **Screenshots are optional** - only add if they help clarify complex UI
+
+5. **Submit for review**: Create PR with the markdown file
+
+### For Developers (Writing Tests)
+
+**Converting Flow to Test**:
+
+1. **Read the flow documentation**: `/e2e/flows/[flow-name].md`
+2. **Create test file**: `/e2e/tests/[flow-name].spec.ts`
+3. **Follow the documented steps**: Each step becomes a test action
+4. **Use documented selectors**: Form fields, buttons, text from the flow doc
+5. **Update flow status**: Mark as ✅ Automated in `/e2e/flows/README.md`
+
+**Test Patterns**:
+- Use `page.getByRole()` for accessibility-friendly selectors
+- Use `page.locator('[name="field"]')` for form fields
+- Use `page.getByText()` for visible text matching
+- Add `data-testid` attributes to components if needed
+
+**Using the Authentication Fixture**:
+```typescript
+import { test, expect } from '../fixtures/auth.fixture';
+
+test('my test', async ({ authenticatedPage }) => {
+  await authenticatedPage.goto('/installs');
+  // Already authenticated - no manual cookie setup needed!
+});
+```
+
+### Using Claude to Write Flows
+
+**Prompt Template for Claude**:
+```
+I want to document a user flow for E2E testing.
+
+Flow: [Name of the flow]
+Description: [What the user is trying to accomplish]
+
+Steps:
+1. [First action]
+2. [Second action]
+3. [etc...]
+
+Please create a user flow document following the template at /e2e/flows/TEMPLATE.md.
+For each step, describe:
+- What the user does
+- What they see on screen
+- Expected results
+- Any form fields, buttons, or interactive elements
+
+Also write a corresponding Playwright test in /e2e/tests/.
+
+[Optional: Attach screenshots if complex UI needs clarification]
+```
+
+**Claude can**:
+- Write flow documentation from step descriptions
+- Read screenshots to identify UI elements (if provided)
+- Explore component code to find selectors
+- Generate Playwright tests from flow docs
+- Suggest edge cases based on flow complexity
+
+### Example Workflows
+
+**Adding a New Flow**:
+1. Copy TEMPLATE.md → `your-flow-name.md`
+2. Fill in prerequisites, steps, test data, edge cases
+3. Add entry to `/e2e/flows/README.md` under appropriate priority
+4. Submit PR for review
+5. Developer writes corresponding test
+6. Update status from ❌ to ✅ when automated
+
+**Navigation Pattern**:
+- Tests use `/installs`, `/apps`, etc. (no org-id needed)
+- Dashboard automatically redirects to first org
+- Use `authenticatedPage` fixture to skip auth setup
+
 ## Important Notes
 
 - **Ignore `/old/` directories**: Contains deprecated components and utilities

services/dashboard-ui/e2e/README.md

@@ -0,0 +1,89 @@
+# Dashboard UI E2E Tests
+
+End-to-end tests using Playwright for browser-based testing against the real API.
+
+## Prerequisites
+
+1. **Install dependencies**: `npm install`
+2. **Install browsers**: `npx playwright install chromium`
+3. **Running services**:
+   - Dashboard: Running on port 4000
+   - API: Running on port 8081
+4. **Authentication token**: `E2E_AUTH_TOKEN` environment variable set (created by nuonctl script)
+
+## Running Tests
+
+```bash
+# Run all E2E tests
+npm run test:e2e
+
+# Interactive UI mode (best for debugging)
+npm run test:e2e:ui
+
+# Watch browser execution
+npm run test:e2e:headed
+
+# Step-through debugger
+npm run test:e2e:debug
+
+# Generate tests from browser actions
+npm run test:e2e:codegen
+```
+
+## Test Organization
+
+- `/e2e/tests/` - Test spec files (`.spec.ts`)
+- `/e2e/flows/` - User flow documentation (markdown files)
+- `/e2e/fixtures/` - Reusable test fixtures (auth helpers, utilities)
+
+## User Flows
+
+User flows are documented in the `/e2e/flows/` directory. These documents describe critical user journeys and serve as the source of truth for E2E tests.
+
+**Flow Documentation**:
+- See `/e2e/flows/README.md` for catalog of all flows
+- Each flow corresponds to a test file in `/e2e/tests/`
+- Flows can be written by non-technical team members using the template
+
+**Writing User Flows**:
+1. Copy `/e2e/flows/TEMPLATE.md` to create a new flow
+2. Fill in the prerequisites, steps, test data, and edge cases
+3. Submit PR with the markdown file
+4. Developer writes corresponding test in `/e2e/tests/`
+
+**Using the Authentication Fixture**:
+```typescript
+import { test, expect } from '../fixtures/auth.fixture';
+
+test('my test', async ({ authenticatedPage }) => {
+  await authenticatedPage.goto('/installs');
+  // Already authenticated - no need to set cookies manually!
+});
+```
+
+## Writing Tests
+
+Tests are written using Playwright's test API. Example:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('should do something', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.locator('h1')).toHaveText('Welcome');
+});
+```
+
+## Debugging Tips
+
+1. **Use UI mode**: `npm run test:e2e:ui` - Interactive debugging interface
+2. **Run headed**: `npm run test:e2e:headed` - See browser window
+3. **Use debug mode**: `npm run test:e2e:debug` - Step through tests
+4. **Screenshots**: Automatically captured on failure
+5. **Videos**: Recorded when tests fail
+
+## Authentication
+
+Tests use the Nuon auth service with token from `E2E_AUTH_TOKEN` environment variable. The token is set as an `X-Nuon-Auth` cookie for authenticated requests.
+
+To run authenticated tests, ensure `E2E_AUTH_TOKEN` is set in your environment before running the tests.

services/dashboard-ui/e2e/fixtures/auth.fixture.ts

@@ -0,0 +1,54 @@
+import { test as base, expect, type Page } from '@playwright/test';
+
+/**
+ * Authentication fixture for Playwright E2E tests
+ *
+ * Provides an authenticated page context with the X-Nuon-Auth cookie already set.
+ * This eliminates the need to manually set authentication in every test.
+ *
+ * Usage:
+ * ```typescript
+ * import { test, expect } from '../fixtures/auth.fixture';
+ *
+ * test('my test', async ({ authenticatedPage }) => {
+ *   await authenticatedPage.goto('/installs');
+ *   // Page is already authenticated!
+ * });
+ * ```
+ *
+ * Requires E2E_AUTH_TOKEN environment variable to be set.
+ */
+
+// Define the type for our custom fixtures
+type AuthFixtures = {
+  authenticatedPage: Page;
+};
+
+export const test = base.extend<AuthFixtures>({
+  authenticatedPage: async ({ page }, use) => {
+    // Get auth token from environment
+    const authToken = process.env.E2E_AUTH_TOKEN;
+
+    if (!authToken) {
+      throw new Error(
+        'E2E_AUTH_TOKEN environment variable not set. ' +
+        'Set it with: export E2E_AUTH_TOKEN="your-token-here"'
+      );
+    }
+
+    // Add authentication cookie
+    await page.context().addCookies([
+      {
+        name: 'X-Nuon-Auth',
+        value: authToken,
+        domain: 'localhost',
+        path: '/',
+      },
+    ]);
+
+    // Provide the authenticated page to the test
+    await use(page);
+  },
+});
+
+export { expect };

services/dashboard-ui/e2e/flows/README.md

@@ -0,0 +1,78 @@
+# E2E User Flow Documentation
+
+This directory contains documented user flows for the Nuon dashboard. Each flow describes a critical user journey and corresponds to automated E2E tests.
+
+## Flow Status Legend
+
+- ✅ **Automated** - Flow is documented and has corresponding Playwright test
+- ⏳ **In Progress** - Flow is documented, test implementation in progress
+- ❌ **Not Automated** - Flow is documented but not yet automated
+
+## Critical Flows (Priority: High)
+
+- ✅ **[Create Install](./create-install.md)** - Provision a new install for an app
+  - Status: Automated with Playwright test
+  - Test File: [`tests/create-install.spec.ts`](../tests/create-install.spec.ts)
+
+## Secondary Flows (Priority: Medium)
+
+*No flows documented yet.*
+
+## How to Use This Documentation
+
+### For Non-Technical Contributors (Product, Design, QA)
+
+1. **Copy the template**: `cp TEMPLATE.md [your-flow-name].md`
+2. **Fill in the flow details**: Describe what the user does step-by-step
+3. **Submit for review**: Create a PR with your markdown file
+4. **Screenshots optional**: Only add if the UI is complex
+
+### For Developers
+
+1. **Read the flow doc**: `/e2e/flows/[flow-name].md`
+2. **Write the test**: `/e2e/tests/[flow-name].spec.ts`
+3. **Update this README**: Change status from ❌ to ✅ Automated
+4. **Link the test**: Add test file path to the flow entry below
+
+### For Everyone
+
+**Using Claude to write flows**: You can ask Claude to document a flow and write the test:
+
+```
+I want to document a user flow for [feature name].
+
+Steps:
+1. [User does X]
+2. [User does Y]
+3. [etc...]
+
+Please create a flow doc using /e2e/flows/TEMPLATE.md
+and write a Playwright test in /e2e/tests/.
+```
+
+Claude can:
+- Read component code to find selectors
+- Suggest edge cases
+- Generate test code from flow descriptions
+
+## Adding a New Flow
+
+1. Copy `TEMPLATE.md` → `your-flow-name.md`
+2. Fill in prerequisites, steps, test data, edge cases
+3. Add entry to this README under appropriate priority section
+4. Submit PR for review
+5. Once approved, developer writes corresponding test
+6. Update status from ❌ to ✅ when automated
+
+---
+
+## Upcoming Flows
+
+Flows to consider documenting:
+
+- Deploy workflow approval
+- Component configuration
+- Runner health monitoring
+- VCS connection setup
+- Build execution
+- App configuration sync