mattermost/e2e-tests/playwright/CLAUDE.OPTIONAL.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Purpose

This is the Playwright E2E testing suite for Mattermost. It contains end-to-end tests for validating the Mattermost web application functionality using the Playwright testing framework.

Key Commands

Installation

# Install npm packages
npm i

# Install browser binaries (if prompted)
npx playwright install

Running Tests

# Run a specific test across all browsers (Chrome, Firefox, iPad)
npm run test -- <test-name>

# Run a specific test for a specific browser
npm run test -- <test-name> --project=chrome
npm run test -- <test-name> --project=firefox
npm run test -- <test-name> --project=ipad

# Run all tests (including visual tests)
npm run test

# Run CI tests (excludes visual tests, runs only in Chrome)
npm run test:ci

# Run tests with UI mode
npm run playwright-ui

# Run tests with slow-motion to debug
npm run test:slomo

# Run visual tests
npm run test -- visual

# Update visual test snapshots
npm run test:update-snapshots

# Visual testing with Percy
npm run percy:docker

Development Commands

# Build the project
npm run build

# Watch mode for development
npm run build:watch

# Type checking
npm run tsc

# Linting
npm run lint

# Format code
npm run prettier:fix

# Verify test documentation format
npm run lint:test-docs

# Run all checks (lint, prettier, typescript, test docs)
npm run check

# Clean the project
npm run clean

# Show test report
npm run show-report

Architecture Overview

Key Components

1. lib/ Directory: Contains the shared library (@mattermost/playwright-lib) that provides:

   • Page objects for Mattermost UI pages
   • Component abstractions for UI elements
   • Test utilities and fixtures
   • Server setup and management functions
   • Visual testing support

2. specs/ Directory: Contains the actual test files organized by type:

   • functional/ - Functional tests for various features
   • visual/ - Visual regression tests
   • accessibility/ - Accessibility tests
   • client/ - Client API tests

3. Test Fixtures: The main test fixture (pw) provides:

   • Browser context management
   • Page actions and utilities
   • Server API helpers
   • Random data generators
   • Visual testing helpers

4. Page Object Model: UI abstractions are organized in:

   • lib/src/ui/pages/ - Page objects (Login, Channels, etc.)
   • lib/src/ui/components/ - Component objects (Posts, Menus, etc.)

Test Flow

1. Tests typically follow this pattern:

   • Initialize test setup with pw.initSetup()
   • Login to a test account with pw.testBrowser.login()
   • Navigate to the relevant page
   • Perform actions and assertions
   • Optionally take visual snapshots

2. Visual tests also:

   • Hide dynamic content with pw.hideDynamicChannelsContent()
   • Take snapshots with pw.matchSnapshot()

Environment Configuration

Tests can be configured through environment variables:

• PW_BASE_URL - Mattermost server URL (default: http://localhost:8065)
• PW_ADMIN_USERNAME - Admin username (default: sysadmin)
• PW_ADMIN_PASSWORD - Admin password (default: Sys@dmin-sample1)
• PW_HEADLESS - Run tests headless (default: true)
• PW_SNAPSHOT_ENABLE - Enable snapshot testing (default: false)
• PW_SLOWMO - Add delay between actions in ms (default: 0)
• PW_WORKERS - Number of parallel workers (default: 1)
• PERCY_TOKEN - Authentication token for Percy visual testing service (required for Percy tests)

Server Setup

Before running tests, a Mattermost server must be available. Two options:

1. Run from source:

   cd server && make run
   

2. Run using Docker (recommended for testing):

   # Configure environment in e2e-tests/.ci/env
   cd e2e-tests && TEST=playwright make
   

Best Practices

1. Page Object Pattern: Always use page/component objects from the library. No static UI selectors should be in test files.

2. Visual Testing: For visual tests:

   • Place all visual tests in the specs/visual/ directory
   • Always include the @visual tag in the test tags array
   • Run via Docker container for consistency to maintain screenshot integrity
   • Use pw.hideDynamicChannelsContent() to hide dynamic elements that could cause flaky tests
   • Update snapshots with npm run test:update-snapshots only from within the Docker container
   • For Percy-based visual testing:
     • A valid PERCY_TOKEN environment variable must be set
     • Tests should only be run inside the Playwright Docker container
   • Follow the visual test documentation format like other tests, with proper JSDoc and comments

3. Test Title Validation with Claude Code: When using Claude:

   • Run claude spec/path/to/file.spec.ts to check your test file
   • Ask: "Check if test titles follow the format in CLAUDE.md"
   • Claude will analyze each test title and suggest improvements
   • Format should be action-oriented, feature-specific, context-aware, and outcome-focused
   • Example: creates scheduled message from channel and posts at scheduled time

4. Test Structure:

   • Use descriptive test titles that follow this format:
     • Action-oriented: Start with a verb that describes the main action
     • Feature-specific: Include the feature or component being tested
     • Context-aware: Include relevant context (where/how it's being performed)
     • Outcome-focused: Specify the expected outcome or behavior
   • Examples of well-formatted test titles:
     • "creates scheduled message from channel and posts at scheduled time"
     • "edits scheduled message content while preserving send date"
     • "reschedules message to a future date from scheduled posts page"
     • "deletes scheduled message from scheduled posts page"
     • "converts draft message to scheduled message"
   • Test keys (MM-T\d+) in test titles are optional for new tests
     • New tests without keys will automatically be registered in the test management system after merge
     • Test keys will be assigned later through a separate automated process
   • Follow the # Action and * Verification comment pattern
   • Group related tests in the same spec file
   • Keep tests independent and isolated
   • Use tags to categorize tests with {tag: '@feature_name'}

5. Test Documentation Format:

   • Include JSDoc-style documentation before each test:

     /**
      * @objective Clear description of what the test verifies
      *
      * @precondition
      * Special setup or conditions required for the test
      * Note: Only include preconditions that are not part of the default setup.
      * Standard conditions like "a test server is running" should be omitted.
      */
     test('MM-T1234 descriptive test title', {tag: '@feature_tag'}, async ({pw}) => {
         // Test implementation
     });
     

   • If no special preconditions are needed, omit the @precondition tag entirely:

     /**
      * @objective Clear description of what the test verifies
      */
     test('descriptive test title', {tag: '@feature_tag'}, async ({pw}) => {
         // Test implementation
     });
     

   • For new tests, the MM-T ID is optional and will be assigned later:

     /**
      * @objective Clear description of what the test verifies
      */
     test('descriptive test title', {tag: '@feature_tag'}, async ({pw}) => {
         // Test implementation
     });
     

   • Use comment prefixes to clearly indicate actions and verifications:
     • // # descriptive action - Comments that describe steps being taken (e.g., // # Initialize user and login)
     • // * descriptive verification - Comments that describe assertions/checks (e.g., // * Verify message appears in channel)

6. Browser Compatibility:

   • Tests run on Chrome, Firefox, and iPad by default
   • Consider browser-specific behaviors for certain features
   • Use test.skip() for browser-specific limitations

7. Test Documentation Linting:

   • Run npm run lint:test-docs to verify all spec files follow the documentation format
   • The linter checks for proper JSDoc tags, test titles, feature tags, and action/verification comments
   • This is also included in the standard npm run check command
   • See the example in specs/functional/channels/scheduled_messages/scheduled_messages.spec.ts