uui-e2e-testing

name	uui-e2e-testing
description	Helps create and maintain E2E and screenshot tests for UUI components using Playwright. Use when adding E2E tests, creating screenshot tests, updating preview configurations, or working with Property Explorer previews for testing.

UUI E2E Testing

UUI uses Playwright for E2E and screenshot testing. All test infrastructure is in uui-e2e-tests/ folder. These tests are part of PR quality gate.

Prerequisites: The UUI docs server must be running before E2E tests. Start with yarn start or yarn build-server && yarn start-server. Tests default to http://localhost:9009. For setup details (Docker, browsers, env vars), see uui-e2e-tests/readme.md.

Screenshot Testing

Screenshot tests use Preview pages from Property Explorer. When editing/adding component props, update screenshot tests accordingly.

Create/Edit Preview

1. Go to app/src/docs/explorerConfigs and find/add config file for your component
2. Add preview configuration using preview function:

preview: (docPreview: DocPreviewBuilder<ComponentProps>) => {
    const TEST_DATA = { icon: 'action-account-fill.svg' };
    
    // Object form
    docPreview.add({
        id: TComponentPreview['Size Variants'],
        matrix: {
            size: { examples: '*' },
            caption: { values: ['Test'] },
        },
        cellSize: '210-60',
    });
    
    // 3-argument shorthand form
    docPreview.add(TComponentPreview['Color Variants'], {
        color: { examples: '*' },
        fill: { examples: '*' },
    }, '140-60');
}

Skin-specific overrides with docPreview.update():

preview: (docPreview: DocPreviewBuilder<ComponentProps>) => {
    docPreview.add({ id: TComponentPreview['Size Variants'], matrix: { /* ... */ } });

    // Override matrix for specific skins
    docPreview.update(TComponentPreview['Size Variants'], {
        [TSkin.Loveship]: { fill: { values: ['solid'] } },
    });
}

Guidelines:

• Split size (layout) and color (appearance) props into separate previews
• Use examples: '*' to test all enum values
• Use values: [...] for specific test values
• Use condition for conditional props

Define Screenshot Tests

Add test configuration in uui-e2e-tests/tests/previewTests/preview.e2e.ts:

// Array form — multiple test configs per component
.add(componentName, [
    {
        previewId: [TComponentPreview['Color Variants']],
        skins: SKINS.promo_loveship_electric,
        slow: true, // Optional: for complex renders
    },
    {
        previewId: [TComponentPreview['Size Variants']],
    },
    {
        onlyChromium: true, // Optional: browser-specific
        previewId: [TComponentPreview['Color Variants']],
        previewTag: 'PseudoStateHover',
        skins: SKINS.promo_loveship_electric,
        forcePseudoState: [{ state: 'hover', selector: '.uui-component' }],
    },
])

// Single-object shorthand — simple components
.add(alert, { previewId: values(TAlertPreview) })
.add(tooltip, { previewId: values(TTooltipPreview), skins: SKINS.promo_loveship })

Additional options:

• clickElement: () => 'input' — click an element before screenshot (e.g. for DatePicker open state)

E2E Tests

E2E tests validate complex component behavior that's hard to test via unit tests.

Location: uui-e2e-tests/tests/Integration/

Setup: Use setupDocExampleTest with testUrl, PageObjectConstructor, and Playwright fixtures (pageWrapper, testInfo). Page objects live in uui-e2e-tests/framework/pageObjects/.

Example:

import { test } from '../../../framework/fixtures';
import { DropdownObject } from '../../../framework/pageObjects/dropdownObject';
import { setupDocExampleTest } from '../testUtils';

test('Dropdown / Boundary mode', async ({ pageWrapper }, testInfo) => {
    const { pageObject } = await setupDocExampleTest({
        testInfo,
        pageWrapper,
        PageObjectConstructor: DropdownObject,
        testUrl: '/preview?theme=loveship&isSkin=true&componentId=dropdown&previewId=...',
    });
    await pageObject.waitForContentLoad();
    await pageObject.hoverTarget();
    await pageObject.waitDropdownBodyVisible();
    // ... assertions
});

testUrl can target doc examples (/docExample?examplePath=...) or preview pages (/preview?componentId=...&previewId=...).

Commands

• yarn test-e2e — Run all E2E tests
• yarn test-e2e-chromium — Run in Chromium only
• yarn test-e2e-update — Update screenshot baselines
• yarn test-e2e-open-report — Open test report

Workflow

When adding/editing component props:

1. Update preview configuration in app/src/docs/explorerConfigs
2. Add screenshot test entries in preview.e2e.ts
3. Run yarn test-e2e to verify
4. Update screenshots if needed: yarn test-e2e-update

References

• Setup and troubleshooting: uui-e2e-tests/readme.md
• Integration test examples: uui-e2e-tests/tests/Integration/