upstream-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

```bash
# Install npm packages
npm i

# Install browser binaries (if prompted)
npx playwright install
```

### Running Tests

```bash
# 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

```bash
# 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
    - Testcontainers orchestration (`lib/src/containers/`) for `testcontainers` mode (see Server Setup below)
    - 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)
- `PW_USE_TESTCONTAINERS` - Selects `testcontainers` mode, see Server Setup below (default: false)
- `PW_TESTCONTAINERS_SERVICES` - Comma-separated additional services to start, e.g. `minio,openldap` (default: `minio,openldap,keycloak,elasticsearch`; set to an empty string to start none)
- `PW_TESTCONTAINERS_REUSE` - Reuse containers across repeated local runs instead of recreating them; tear down explicitly with `npm run testcontainers:down` (default: true)
- `SERVER_IMAGE` - Mattermost server image `testcontainers` mode starts (default: `mattermostdevelopment/mattermost-enterprise-edition:master`)
- `MM_ENV` - Comma-separated `KEY=VALUE` server config overrides for `testcontainers` mode (default: none)

## Server Setup

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

1. **Run from source**:

    ```bash
    cd server && make run
    ```

2. **Testcontainers** (recommended for testing, and what CI uses) — no separate step needed, Playwright starts and tears down the server + dependencies itself:
    ```bash
    PW_USE_TESTCONTAINERS=true npm run test
    # Starts minio,openldap,keycloak,elasticsearch by default; add PW_TESTCONTAINERS_SERVICES=... to change (e.g. add opensearch,azurite, or set to "" to start none)
    # Containers are reused across runs by default; tear down with `npm run testcontainers:down` (or set PW_TESTCONTAINERS_REUSE=false for a self-cleaning one-off run)
    # `npm run testcontainers:up` brings the stack up (or confirms an existing one) without running any tests
    ```

## Best Practices

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

2. **Locator Priority**: Follow the Playwright recommended locator strategy (see [Playwright Locators Quick Guide](https://playwright.dev/docs/locators#quick-guide)). Use locators in this priority order:
    1. `getByRole()` - Preferred. Locates by accessibility role and accessible name (e.g., `getByRole('button', {name: 'Submit'})`).
    2. `getByText()` - Locates by visible text content.
    3. `getByLabel()` - Locates form controls by their associated label text.
    4. `getByPlaceholder()` - Locates inputs by placeholder text.
    5. `getByAltText()` - Locates elements (usually images) by alt text.
    6. `getByTitle()` - Locates by the `title` attribute.
    7. `getByTestId()` - Last resort. Locates by `data-testid` attribute.
    - **Avoid** CSS selectors (`.class`, `#id`), XPath, and raw `locator()` calls unless none of the above locators can identify the element.
    - Use `{exact: true}` when the accessible name might partially match other elements (e.g., `getByRole('button', {name: 'Invite', exact: true})`).

3. **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

4. **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`

5. **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'}`

6. **Test Documentation Format**:
    - Include JSDoc-style documentation before each test:
        ```typescript
        /**
         * @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:
        ```typescript
        /**
         * @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:
        ```typescript
        /**
         * @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`)

7. **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

8. **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`