ForgeLM/.agents/workflows/e2e-test.md

description

description
End-to-end testing with Playwright MCP

E2E Testing Workflow

Purpose

Validate complete user journeys through the full system using Playwright MCP.

Note: Paths below follow the project structure defined in project-structure.md. Adjust paths to match the actual project layout.

When to Use

• After completing an epic/milestone
• Before release/deploy
• When adding critical user flows

Prerequisites

• Services running (docker compose up or local dev)
• Feature implementation complete
• Unit and integration tests passing

Steps

1. Start Services

Ensure the full stack is running:

docker compose up -d
# Wait for health checks
docker compose ps

Or local development:

# Terminal 1: Backend
cd apps/backend && go run cmd/api/main.go

# Terminal 2: Frontend  
cd apps/frontend && pnpm run dev

2. Create E2E Test Plan

Document test cases in e2e/{feature}-{ui|api}.e2e.test.ts:

• Happy path flows
• Error handling
• Edge cases

3. Execute with Playwright MCP

Navigate to page:

mcp_playwright_browser_navigate(url="http://localhost:5173/login")

Capture page state:

mcp_playwright_browser_snapshot()

Interact with elements (use refs from snapshot):

mcp_playwright_browser_type(ref="<ref>", text="[email protected]")
mcp_playwright_browser_click(ref="<ref>")

Wait for results:

mcp_playwright_browser_wait_for(text="Welcome")

Capture snapshot for walkthrough documentation:

mcp_playwright_browser_snapshot(filename="docs/e2e-screenshots/{feature}-{description}.md")

4. Document Results

Screenshot location: docs/e2e-screenshots/{feature}-{description}.png

1. Create docs/e2e-screenshots/ if it doesn't exist
2. Save all snapshots there with descriptive names
3. For visual proof (video recording), use browser_subagent with RecordingName parameter
4. Embed walkthrough documentation in the walkthrough artifact
5. Note any failures or issues
6. Update test files if needed

E2E Test Structure

e2e/                                    # Single-app projects
├── api/                                # (For monorepo: apps/e2e/api/)
│   └── task-crud-api.e2e.test.ts       # API-only E2E
└── ui/                                 # (For monorepo: apps/e2e/ui/)
    ├── auth-flow-ui.e2e.test.ts        # Browser E2E
    └── task-flow-ui.e2e.test.ts

Path adapts to project type per project-structure.md § Adapting for Different Project Types.

Example: Auth Flow E2E

// e2e/ui/auth-flow-ui.e2e.test.ts
describe('Authentication Flow', () => {
  it('should register a new user', async () => {
    // Navigate to register
    // Fill form
    // Submit
    // Verify redirect to dashboard
  });

  it('should login existing user', async () => {
    // Navigate to login
    // Fill credentials
    // Submit
    // Verify dashboard loads
  });

  it('should show error for invalid credentials', async () => {
    // Navigate to login
    // Fill wrong password
    // Submit
    // Verify error message
  });
});

Completion Criteria

• All critical user flows tested
• Snapshots captured and embedded in walkthrough
• No blocking issues found