integratedhub/tests/QUICK_START.md

E2E Test Quick Reference

Fast reference for common E2E testing tasks.

Quick Commands

# 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

# 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

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

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

Console Error Tracking

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

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

Form Interaction

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

API Testing

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

# 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

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
• Troubleshooting: TROUBLESHOOTING.md
• Overview: 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