Riverty Design System: Playwright Tests

Riverty, your flexible Payment Companion. 25+ million users, 1+ billion secure transactions.

Riverty Design System: a design and development toolkit tailor-made for Riverty teams and collaborators.

→ designsystem.riverty.com

This package contains end-to-end (E2E) tests for the Riverty Design System using Playwright.

Contributing

We welcome contributions to our E2E test suite! Writing tests helps ensure quality and prevent regressions.

Development Setup

cd packages/playwright
npm install
# Browsers are automatically installed via postinstall script

Running Tests

# Run all tests
npm run test

# Run with UI mode (recommended for development)
npm run test-ui

# Run specific test file
npx playwright test e2e/button.spec.ts

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

# Run tests with specific workers
npx playwright test --workers=2

Structure

e2e/                    # E2E test files
server/                 # Test servers (e.g., form server)
types/                  # TypeScript types
utils/                  # Test utilities and helpers
playwright.config.ts    # Playwright configuration
test.extend.ts          # Custom test fixtures

Writing Tests

1. Create a test file in e2e/:

import { test, expect } from '../test.extend';
import { gotoStory } from '../utils/lib';

test.describe('Component Name', () => {
  
  test('`readonly` value will be submitted in formData', async ({ page }) => {
  

  test('should render correctly', async ({ page }) => {
    await gotoStory(page, {
      storyId: 'components-button--primary-button',
      args: {
        variant: 'primary',
        ...
      }
    });

    const button = page.locator('r-button');
    await expect(button).toBeVisible();
  });

  test('should handle click events', async ({ page }) => {
    await gotoStory(page, {
      storyId: 'components-button--primary-button',
      args: {
        variant: 'primary',
        ...
      }
    });
    const button = page.locator('r-button');
    await button.click();
    // Add assertions
  });
});

2. Test accessibility with axe-core:

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('should not have accessibility violations', async ({ page }) => {
  await gotoStory(page, {
      storyId: 'components-button--primary-button',
      args: {
        variant: 'primary',
        ...
      }
    });
  
  const accessibilityScanResults = await new AxeBuilder({ page }).analyze();
  expect(accessibilityScanResults.violations).toEqual([]);
});

3. Test visual regression:

test('should match screenshot', async ({ page }) => {
  await gotoStory(page, {
      storyId: 'components-button--primary-button',
      args: {
        variant: 'primary',
        ...
      }
    });
  await expect(page).toHaveScreenshot('button-primary.png');
});

Best Practices

Test Organization:

• Group related tests using test.describe()
• Use descriptive test names (should...)
• Keep tests independent and isolated
• Clean up state between tests

Selectors:

• Prefer user-facing attributes (role, text, label)
• Use data-testid for complex scenarios
• Avoid CSS selectors when possible
• Use component tags for web components

Assertions:

• Use Playwright's built-in assertions (auto-retry)
• Test user-visible behavior, not implementation
• Include accessibility checks
• Verify error states and edge cases

Performance:

• Minimize navigation (reuse pages when possible)
• Run tests in parallel
• Use test fixtures for common setup
• Mock external dependencies

Testing Checklist

When adding tests for a component:

• [ ] Visual rendering tests
• [ ] Interaction tests (click, type, hover)
• [ ] Keyboard navigation
• [ ] Accessibility tests (axe-core)
• [ ] Responsive behavior
• [ ] Error states
• [ ] Edge cases
• [ ] Visual regression (screenshots)

Debugging Tests

# Run with UI mode (best for debugging)
npm run test-ui

# Run with browser visible
npx playwright test --headed

# Debug specific test
npx playwright test --debug e2e/button.spec.ts

# Generate trace
npx playwright test --trace on

Viewing traces:

npx playwright show-trace trace.zip

Configuration

Playwright is configured in playwright.config.ts:

• Projects: Chromium, Firefox, WebKit
• Base URL: Points to Storybook
• Timeouts: Test and action timeouts
• Screenshots: On failure
• Traces: On first retry

Custom Fixtures

Custom test fixtures are defined in test.extend.ts for:

• Extended test context
• Reusable setup/teardown
• Custom matchers
• Helper functions

Visual Regression

Updating snapshots:

When visual changes are intentional:

# Update all snapshots
npx playwright test --update-snapshots

# Update specific test snapshots
npx playwright test e2e/button.spec.ts --update-snapshots

Important: Review snapshot changes carefully before committing.

Continuous Integration

Tests run automatically in CI/CD pipelines. Ensure:

• All tests pass locally before pushing
• Visual regression snapshots are committed
• Tests are not flaky (run multiple times)
• Proper test isolation

Useful Commands

# Run tests
npm run test

# UI mode
npm run test-ui

# Specific test
npx playwright test e2e/component.spec.ts

# Headed mode
npx playwright test --headed

# Debug mode
npx playwright test --debug

# Update snapshots
npx playwright test --update-snapshots

# Generate report
npx playwright show-report

# Run form server (for form testing)
npm run form-server

Resources

• Playwright Documentation
• Best Practices
• Accessibility Testing
• Visual Comparisons

For complete contribution guidelines, see CONTRIBUTING.md in the repository root.