integratedhub/tests/QUICK_START.md

# E2E Test Quick Reference

Fast reference for common E2E testing tasks.

## Quick Commands

```bash
# Run all tests
npx playwright test

# Run with UI
npx playwright test --ui

# Run in debug mode
npx playwright test --debug

# Run specific test file
npx playwright test tests/e2e/auth/login.spec.ts

# Run tests matching pattern
npx playwright test --grep "login"

# Run in headed mode
npx playwright test --headed

# View HTML report
npx playwright show-report

# View trace
npx playwright show-trace test-results/trace.zip
```

## Using the Helper Script

```bash
# Run all tests
./tests/e2e-run.sh

# Run with UI
./tests/e2e-run.sh --ui

# Run specific category
./tests/e2e-run.sh --auth
./tests/e2e-run.sh --landlord
./tests/e2e-run.sh --tenant
./tests/e2e-run.sh --error

# Run with debug
./tests/e2e-run.sh --debug

# Run with pattern filter
./tests/e2e-run.sh --grep "login"
```

## Test Structure

```
tests/e2e/
├── auth/              # Authentication (3 files)
├── landlord/          # Landlord features (6 files)
├── tenant/            # Tenant features (4 files)
├── error-handling/    # Error scenarios (1 file)
└── helpers/           # Test utilities
```

## E2E Users

- `landlord` - Alex Landlord (properties: e2e-prop-1, e2e-prop-2)
- `tenant` - Sam Tenant (lease: e2e-lease-1)
- `admin` - System administrator

## Basic Test Template

```typescript
import { expect, test } from "../../helpers/test-utils.ts";

test.describe("Feature Name", () => {
  test.beforeEach(async ({ page }) => {
    await page.addInitScript(() => {
      globalThis.localStorage.setItem("E2E_TEST", "true");
    });
  });

  test("should do something", async ({ page }) => {
    await page.goto("/route", {
      headers: { "x-e2e-user": "landlord" },
    });

    await page.waitForTimeout(1000);
    await expect(page.locator("h1")).toBeVisible();
  });
});
```

## Common Patterns

### Navigation with Auth

```typescript
await page.goto("/protected/route", {
  headers: { "x-e2e-user": "landlord" },
});
```

### Console Error Tracking

```typescript
const errors: string[] = [];
page.on("console", (msg) => {
  if (msg.type() === "error") errors.push(msg.text());
});
// ... test code ...
const filteredErrors = errors.filter(
  (err) => !err.includes("net::ERR_BLOCKED_BY_CLIENT"),
);
expect(filteredErrors.length).toBe(0);
```

### Conditional Assertions

```typescript
const element = page.locator("#feature");
if (await element.isVisible({ timeout: 3000 })) {
  await expect(element).toBeVisible();
}
```

### Form Interaction

```typescript
await page.locator('input[name="title"]').fill("Test");
await page.locator('button[type="submit"]').click();
```

### API Testing

```typescript
const response = await page.request.get("/api/endpoint", {
  headers: { "x-e2e-user": "landlord" },
});
expect([200, 404].includes(response.status())).toBe(true);
```

## Configuration

Key settings in `playwright.config.ts`:

- **Timeout**: 60s per test
- **Workers**: 1 (local), 2 (CI)
- **Retries**: 0 (local), 2 (CI)
- **Reporters**: HTML, JSON, JUnit, List

## Debugging

```bash
# Debug specific test
npx playwright test --debug tests/e2e/auth/login.spec.ts

# Run with trace
npx playwright test --trace on

# Slow motion
npx playwright test --headed --slow-mo=1000

# Show only failures
npx playwright test --only-changed
```

## Test Files by Category

### Authentication (3 files, ~40 tests)

- `login.spec.ts` - Login flow, OAuth bypass
- `logout.spec.ts` - Logout, session cleanup
- `rbac.spec.ts` - Role-based access control

### Landlord (6 files, ~80 tests)

- `dashboard.spec.ts` - Landlord dashboard
- `properties.spec.ts` - Property CRUD
- `applications.spec.ts` - Rental applications
- `leases.spec.ts` - Lease management
- `maintenance.spec.ts` - Maintenance requests
- `payments.spec.ts` - Financial data

### Tenant (4 files, ~50 tests)

- `applications.spec.ts` - Tenant applications
- `leases.spec.ts` - Tenant leases
- `maintenance.spec.ts` - Maintenance requests
- `payments.spec.ts` - Payment management

### Error Handling (1 file, 30 tests)

- `validation.spec.ts` - All error scenarios

## Environment Variables

```bash
export E2E_TEST=true              # Enable E2E mode
export PORT=8080                   # Server port
export E2E_BASE_URL=http://127.0.0.1:8080  # Base URL
```

## CI/CD

- **Triggers**: Push, PR, Schedule (daily 2AM UTC)
- **Workers**: 4 shards in parallel
- **Retries**: 2 in CI
- **Artifacts**: 14 days retention

## Common Issues

| Issue                 | Solution                                  |
| --------------------- | ----------------------------------------- |
| Port in use           | `lsof -ti:8080 \| xargs kill -9`          |
| Element not found     | Increase timeout or use conditional check |
| Test flaky            | Increase retries or disable parallel      |
| Browser not installed | `npx playwright install chromium`         |
| Database error        | Check database is running                 |

## Documentation

- **Full Guide**: [E2E_TEST_GUIDE.md](./E2E_TEST_GUIDE.md)
- **Troubleshooting**: [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
- **Overview**: [README.md](./README.md)

## Stats

- **Total Tests**: 200+
- **Test Files**: 13
- **Code Coverage**: All major features
- **Execution Time**: ~5-10 minutes (parallel)

## Tips

1. Use `--ui` for interactive test exploration
2. Use `--debug` for stepping through tests
3. Use `--grep` to run specific tests
4. Use conditional checks for missing features
5. Always track console errors
6. Use E2E mode for authentication
7. Clean up test data to avoid conflicts
8. Run tests serially when debugging

## Keyboard Shortcuts (in UI Mode)

- `Space` - Pause/play
- `F` - Focus test list
- `R` - Run tests
- `Shift+F` - Focus test file
- `Ctrl/Cmd+C` - Stop tests