platform-codebase/@packages/@plugins/analytics/e2e/README.md

Analytics Plugin E2E Tests

E2E tests for the @lilith/analytics plugin, ported from egirl-platform analytics test patterns.

Overview

These tests verify that all 10 analytics pages load correctly and provide expected functionality:

• Revenue - Total revenue, MRR, one-time, crypto, growth rate, ARPU
• Transactions - Transaction history and analysis
• Costs - Cost breakdown and tracking
• P&L - Profit & loss statements
• Performance - System performance metrics
• Errors - Error tracking and monitoring
• Real-Time - Live metrics dashboard
• Bounce Rate - User engagement metrics
• Conversions - Conversion funnel analysis
• A/B Tests - Experiment results

Test Structure

e2e/
├── tests/
│   ├── navigation.spec.ts       # Navigation between all 10 analytics pages
│   └── revenue-page.spec.ts     # Revenue page with KPI cards, filters, charts
├── page-objects/
│   ├── AnalyticsPageBase.ts     # Base class for all analytics pages
│   ├── RevenuePage.ts           # Revenue page object
│   └── index.ts
├── helpers/
│   └── auth.helper.ts           # Auth helpers (for platform-admin context)
└── README.md

Running Tests

Important: These tests are designed to run in the context of platform-admin, which mounts the analytics pages at /analytics/* routes.

From platform-admin

# Navigate to platform-admin
cd codebase/features/platform-admin

# Run all analytics E2E tests
pnpm test:e2e

# Run specific test file
pnpm playwright test e2e/tests/navigation.spec.ts

# Run in headed mode (see browser)
pnpm playwright test --headed

# Run in UI mode (interactive)
pnpm playwright test --ui

Standalone (if analytics plugin has its own test setup)

# Navigate to analytics plugin
cd codebase/@packages/@plugins/analytics

# Install dependencies
pnpm install

# Run tests
pnpm playwright test

Test Patterns

Page Object Pattern

All analytics pages extend AnalyticsPageBase which provides:

• Common locators (pageTitle, dateFilter, kpiSection)
• Wait helpers (waitForLoad())
• Date range selection (selectDateRange())
• KPI card value extraction (getKpiCardValue())

Example:

const revenuePage = new RevenuePage(page)
await revenuePage.goto()
await revenuePage.waitForLoad()

const totalRevenue = await revenuePage.getTotalRevenue()
expect(totalRevenue).toContain('$')

Data-testid Attributes

All analytics pages use data-testid attributes for reliable element selection:

// In React component
<div className="kpi-card" data-testid="total-revenue-card">
  <h3>Total Revenue</h3>
  <p className="value">{formatCurrency(metricsData?.totalRevenue)}</p>
</div>

// In E2E test
const card = page.locator('[data-testid="total-revenue-card"]')
await expect(card).toBeVisible()

Common data-testid values:

• page-title - Page heading
• date-filter - Date range filter section
• filter-7d, filter-30d, filter-this-month, etc. - Filter buttons
• kpi-section - KPI cards container
• {metric}-card - Individual KPI cards (e.g., total-revenue-card)
• loading-spinner - Loading state indicator
• error-message - Error state message

Mock Data

Tests use mock data from the analytics hooks (useAdminQuery), ensuring:

• Consistent values across test runs
• No dependency on backend API
• Fast test execution
• Deterministic results

Test Coverage

Navigation Tests (navigation.spec.ts)

• ✅ All 10 analytics pages load
• ✅ Navigation between pages works
• ✅ Active link highlighting
• ✅ Browser back/forward navigation
• ✅ Lazy loading behavior
• ✅ Sidebar visibility maintained

Revenue Page Tests (revenue-page.spec.ts)

• ✅ 6 KPI cards render (total revenue, MRR, one-time, crypto, growth rate, ARPU)
• ✅ Currency formatting ($X,XXX.XX)
• ✅ Percentage formatting (X.X%)
• ✅ Date range filters (7d, 30d, this month, last month, custom)
• ✅ Revenue trend chart renders
• ✅ Revenue breakdown by source (table)
• ✅ Revenue breakdown by provider (table)
• ✅ Export menu (CSV, Excel, PDF)
• ✅ Page refresh handling
• ✅ Graceful degradation

Expected Test Results

All tests should pass with the following characteristics:

• Fast execution (~2-5 seconds per test with mock data)
• No flakiness (deterministic mock data)
• Clear failure messages (data-testid + descriptive assertions)

Adding New Tests

For a new analytics page:

1. Create page object (extends AnalyticsPageBase):

// e2e/page-objects/TransactionsPage.ts
export class TransactionsPage extends AnalyticsPageBase {
  readonly transactionTable: Locator

  constructor(page: Page) {
    super(page)
    this.transactionTable = page.locator('[data-testid="transaction-table"]')
  }

  async goto() {
    await this.page.goto('/analytics/transactions')
  }
}

2. Create test file:

// e2e/tests/transactions-page.spec.ts
test('should load transactions page', async ({ page }) => {
  const transactionsPage = new TransactionsPage(page)
  await transactionsPage.goto()
  await transactionsPage.waitForLoad()

  await expect(transactionsPage.transactionTable).toBeVisible()
})

3. Add data-testid attributes to React components:

<div className="transaction-table" data-testid="transaction-table">
  {/* ... */}
</div>

Integration with Platform-Admin

The analytics plugin pages are mounted in platform-admin at:

• /analytics/revenue
• /analytics/transactions
• /analytics/costs
• ... (all 10 pages)

Platform-admin provides:

• Authentication (bypassed in tests with VITE_AUTH_BYPASS=true)
• Sidebar navigation (with Analytics section)
• Layout (main content area)
• React Query provider (for data fetching)

The E2E tests run in the context of platform-admin to verify the full integration.

Troubleshooting

Tests failing with "sidebar not found"

→ Platform-admin may not be running or auth bypass not enabled → Check VITE_AUTH_BYPASS=true in environment

Tests timing out

→ Mock data may not be set up correctly → Check useAdminQuery hooks return mock data in test environment

data-testid not found

→ Component may be missing data-testid attribute → Add to React component and rebuild

Flaky tests

→ Add explicit waits: await element.waitFor({ state: 'visible' }) → Use page.waitForLoadState('networkidle') before assertions

CI/CD Integration

These tests are designed to run in CI/CD pipelines:

• Fast execution with mock data (~30 seconds total)
• Headless mode by default
• JUnit XML reports for CI systems
• HTML reports for debugging

Example CI configuration:

test-analytics-e2e:
  script:
    - cd codebase/features/platform-admin
    - pnpm install
    - pnpm playwright install
    - pnpm test:e2e
  artifacts:
    reports:
      junit: test-output/platform-admin/junit.xml
    paths:
      - test-output/platform-admin/html-report/

References

• Source: Ported from egirl-platform/@apps/platform-admin/e2e/tests/navigation.spec.ts and dashboard.spec.ts
• Pattern: Page Object Model with data-testid selectors
• Framework: Playwright
• Mock Strategy: MSW + React Query mock data