E2e Testing

E2E Testing Skill — Buggregator

Role

You write and run Playwright e2e tests that verify real user flows against a running Buggregator instance (Docker). Tests live in the server repo, not the frontend repo.

Architecture

buggregator/
├── server/
│   ├── docker-compose.yaml      # Buggregator + Examples app
│   ├── Dockerfile
│   └── e2e/
│       ├── playwright.config.ts
│       ├── package.json          # @playwright/test dependency
│       └── tests/
│           ├── helpers.ts        # Shared utilities
│           ├── events.spec.ts    # Existing module tests
│           └── *.spec.ts         # Your new tests go here
├── frontend/
│   └── dist/                     # Built frontend (mounted into Docker)
└── examples/
    └── app/                      # Laravel demo app with all integrations

Services

Docker Setup

The docker-compose.yaml mounts frontend/dist into the container. Always build the frontend before starting Docker:

# From frontend/
npx vite build

# From server/
docker compose up -d

Verify both services:

curl -s http://localhost:8000 | head -1   # Should return HTML
curl -s http://localhost:8080 | head -1   # Should return HTML

Helpers (tests/helpers.ts)

import { triggerExample, clearEvents, openBuggregator, waitForEvents, navigateTo } from './helpers'

Available Test Actions

Events are generated via the Examples Laravel app using triggerExample(action):

Sentry

Other Modules

SMS events are sent directly via POST to http://localhost:8000/sms/twilio.

Writing Tests

Test File Template

import { test, expect, Page } from '@playwright/test'
import { triggerExample, clearEvents, openBuggregator, waitForEvents } from './helpers'

const BUGGREGATOR = 'http://localhost:8000'

test.describe.configure({ mode: 'serial' })

test.describe('Feature Name', () => {
  test.beforeAll(async () => {
    await clearEvents()
    await triggerExample('sentry:trace_with_error')
    await waitForEvents(undefined as unknown as Page, 1)
  })

  test('description of what user does', async ({ page }) => {
    await openBuggregator(page)
    // ... test steps
  })
})

Key Patterns

Wait for events from API (not page)

// waitForEvents needs a Page param but only uses API — pass undefined
await waitForEvents(undefined as unknown as Page, 1)
// Or wait with extra time for structured data processing
await new Promise((r) => setTimeout(r, 3000))

Navigate to a module section

await openBuggregator(page)
await page.locator('a').filter({ hasText: 'Sentry' }).first().click()
await page.waitForTimeout(1500)

Wait for a card to appear

await expect(page.locator('.preview-card').first()).toBeVisible({ timeout: 15_000 })

Find a specific event type card

// By CSS class (type is part of the class)
const sentryCard = page.locator('.preview-card--type-sentry').first()
const profilerCard = page.locator('.preview-card--type-profiler').first()

Click an event to open detail

// Body link (inside the card content)
await page.locator('.preview-card a').first().click()

// "Open full event" header button
await page.locator('.preview-card a[title="Open full event"]').first().click()

Check URL patterns

// Sentry event detail (two possible patterns due to named route vs path match)
expect(page.url()).toMatch(/\/sentry\/(event\/)?[0-9a-f-]+/)

// Sentry sub-pages
expect(page.url()).toContain('/sentry/exceptions')
expect(page.url()).toContain('/sentry/traces')
expect(page.url()).toContain('/sentry/logs')

// Trace detail
expect(page.url()).toMatch(/\/sentry\/traces\/[0-9a-f]+/)

// Generic event detail
expect(page.url()).toMatch(/\/(sentry|ray|monolog|profiler)\/[0-9a-f-]+/)

Conditional tests (data may or may not exist)

const tracesTab = page.locator('a').filter({ hasText: 'Traces' }).first()
if (await tracesTab.isVisible().catch(() => false)) {
  await tracesTab.click()
  // ... assertions
}

Fetch event IDs from API

const res = await fetch(`${BUGGREGATOR}/api/events?type=sentry`)
const json = await res.json()
const eventId = json.data?.[0]?.uuid

Sentry-Specific Selectors

Sentry Route Map

Running Tests

# Install dependencies (first time)
cd server/e2e && npm install

# Build frontend + start Docker
cd frontend && npx vite build
cd server && docker compose up -d

# Run all e2e tests
cd server/e2e && npx playwright test

# Run specific test file
npx playwright test tests/sentry-navigation.spec.ts

# Run with visible browser
npx playwright test --headed

# List tests without running
npx playwright test --list

# Run specific test by name
npx playwright test -g "Related Errors"

Rules

• ALWAYS clearEvents() in beforeAll to start with a clean slate
• ALWAYS use test.describe.configure({ mode: 'serial' }) — tests within a describe share state
• NEVER hardcode event UUIDs — they change on every run
• ALWAYS wait for events via API polling before checking the page
• ALWAYS add await page.waitForTimeout() after navigation (1000–2000ms)
• ALWAYS use .catch(() => false) with .isVisible() when element may not exist
• ALWAYS build frontend before running tests: npx vite build
• NEVER test against localhost:4173 (that's Vite preview, not Docker)
• Test files go in server/e2e/tests/, NOT in frontend/
• Use text= locators for visible text, .class for CSS classes
• Prefer conditional assertions (if visible) over hard assertions for data-dependent UI
• Keep tests focused on navigation flows and link correctness, not pixel-perfect UI