Back to Mattermost

@mattermost/playwright-lib

e2e-tests/playwright/lib/README.md

11.10.012.0 KB
Original Source

@mattermost/playwright-lib

A comprehensive end-to-end testing library for Mattermost web, desktop and plugin applications using Playwright.

Overview

This library provides:

  • Pre-built page objects and components for common Mattermost UI elements
  • Server configuration and initialization utilities
  • Test fixtures and helpers
  • Visual testing support with Percy integration
  • Accessibility testing support with axe-core
  • Browser notification mocking
  • File handling utilities
  • Common test actions and assertions

Installation

bash
npm install @mattermost/playwright-lib

Peer Dependencies

This library requires @playwright/test version 1.55.0 or higher:

bash
npm install @playwright/test@^1.55.0

Usage

Basic example of logging in and posting a message:

typescript
import {test, expect} from '@mattermost/playwright-lib';

test('user can post message', async ({pw}) => {
    // # Create and login a new user
    const {user} = await pw.initSetup();
    const {channelsPage} = await pw.testBrowser.login(user);

    // # Navigate and post a message
    await channelsPage.goto();
    const message = 'Hello World!';
    await channelsPage.postMessage(message);

    // * Verify message appears
    const lastPost = await channelsPage.getLastPost();
    await expect(lastPost).toHaveText(message);
});

Key Components

Page Objects

Ready-to-use page objects for common Mattermost pages:

  • Login
  • Signup
  • Channels
  • System Console
  • And more...

UI Components

Reusable component objects for UI elements:

  • Headers
  • Posts
  • Menus
  • Modals
  • And more...

Test Utilities

Helper functions for common testing needs:

  • Server setup and configuration
  • User/team creation
  • File handling
  • Visual testing
  • And more...

Configuration

The library can be configured via optional environment variables:

Environment Variables

All environment variables are optional with sensible defaults.

Server Configuration

VariableDescriptionDefault
PW_BASE_URLServer URLhttp://localhost:8065
PW_ADMIN_USERNAMEAdmin usernamesysadmin
PW_ADMIN_PASSWORDAdmin passwordSys@dmin-sample1
PW_ADMIN_EMAILAdmin email[email protected]
PW_ENSURE_PLUGINS_INSTALLEDComma-separated list of plugins to install[]
PW_RESET_BEFORE_TESTReset server before testfalse
PW_SMTP_URLInbucket HTTP API URLhttp://localhost:9001

High Availability Cluster Settings

VariableDescriptionDefault
PW_HA_CLUSTER_ENABLEDEnable HA clusterfalse
PW_HA_CLUSTER_NODE_COUNTNumber of cluster nodes2
PW_HA_CLUSTER_NAMECluster namemm_dev_cluster

Push Notifications

VariableDescriptionDefault
PW_PUSH_NOTIFICATION_SERVERPush notification server URLhttps://push-test.mattermost.com

Playwright Settings

VariableDescriptionDefault
PW_HEADLESSRun tests headlesstrue
PW_SLOWMOAdd delay between actions in ms0
PW_WORKERSNumber of parallel workers1

Visual Testing

VariableDescriptionDefault
PW_SNAPSHOT_ENABLEEnable snapshot testingfalse
PW_PERCY_ENABLEEnable Percy visual testingfalse

CI Settings

VariableDescriptionDefault
CISet automatically in CI environmentsN/A

Testcontainers

Selects testcontainers mode — Playwright brings up the server + dependencies itself via Testcontainers — instead of the external mode default, which expects a server already running at PW_BASE_URL.

VariableDescriptionDefault
PW_USE_TESTCONTAINERSSelects testcontainers modefalse
PW_TESTCONTAINERS_SERVICESComma-separated additional services to start (openldap, keycloak, elasticsearch, opensearch, minio, azurite); set to an empty string to start noneminio,openldap,keycloak,elasticsearch
PW_TESTCONTAINERS_REUSEReuse containers across repeated local runs instead of recreating them; tear down with npm run testcontainers:down (requires testcontainers.reuse.enable=true in ~/.testcontainers.properties)true
PW_TESTCONTAINERS_CONTAINER_RUNNERSet when the Playwright process itself runs inside a Docker container (e.g. CI), to join it to the Testcontainers networkfalse
SERVER_IMAGEPrebuilt Mattermost server image testcontainers mode startsmattermostdevelopment/mattermost-enterprise-edition:master
MM_ENVComma-separated KEY=VALUE server config overrides, merged over the test baselinenone
PW_LDAP_HOST / PW_LDAP_PORTOpenLDAP host/port (only used when openldap is started)localhost / 389
PW_KEYCLOAK_URLKeycloak URL (only used when keycloak is started)http://localhost:8484
PW_ELASTICSEARCH_URLElasticsearch URL (only used when elasticsearch is started)http://localhost:9200
PW_OPENSEARCH_URLOpenSearch URL (only used when opensearch is started)http://localhost:9201
PW_MINIO_URLMinio URL (only used when minio is started)http://localhost:9000
PW_AZURITE_URLAzurite URL (only used when azurite is started)http://localhost:10000

In testcontainers mode, these host/port defaults are never actually used — Testcontainers always assigns its own dynamic port or network alias per run, so a testcontainers-mode run can never collide with a same-machine external-mode session using the fixed defaults above. Tear a reused stack down explicitly with npm run testcontainers:down (from the playwright/ package).

Accessibility Testing

The library includes built-in accessibility testing using axe-core:

typescript
import {test, expect} from '@mattermost/playwright-lib';

test('verify login page accessibility', async ({page, axe}) => {
    // # Navigate to login page
    await page.goto('/login');

    // # Run accessibility scan
    const results = await axe.builder(page).analyze();

    // * Verify no accessibility violations
    expect(results.violations).toHaveLength(0);
});

The axe-core integration:

  • Runs WCAG 2.0 Level A & AA rules by default
  • Provides detailed violation reports
  • Supports rule customization
  • Can be configured per-test or globally

Visual Testing

The library supports visual testing through Playwright's built-in visual comparisons and Percy integration:

typescript
import {test, expect} from '@mattermost/playwright-lib';

test('verify channel header appearance', async ({pw, browserName, viewport}, testInfo) => {
    // # Setup and login
    const {user} = await pw.initSetup();
    const {page, channelsPage} = await pw.testBrowser.login(user);

    // # Navigate and prepare page
    await channelsPage.goto();
    await expect(channelsPage.appBar.playbooksIcon).toBeVisible();
    await pw.hideDynamicChannelsContent(page);

    // * Take and verify snapshot
    await pw.matchSnapshot(testInfo, {page, browserName, viewport});
});

Browser Notifications

Mock and verify browser notifications:

typescript
import {test, expect} from '@mattermost/playwright-lib';

test('verify notification on mention', async ({pw}) => {
    // # Setup users and team
    const {team, adminUser, user} = await pw.initSetup();

    // # Setup admin browser with notifications
    const {page: adminPage, channelsPage: adminChannelsPage} = await pw.testBrowser.login(adminUser);
    await adminChannelsPage.goto(team.name, 'town-square');
    await pw.stubNotification(adminPage, 'granted');

    // # Setup user browser and post mention
    const {channelsPage: userChannelsPage} = await pw.testBrowser.login(user);
    await userChannelsPage.goto(team.name, 'off-topic');
    await userChannelsPage.postMessage(`@ALL good morning, ${team.name}!`);

    // * Verify notification received
    const notifications = await pw.waitForNotification(adminPage);
    expect(notifications.length).toBe(1);
});

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

See LICENSE.txt for license information.