upstream-rocketchat/apps/meteor/tests/e2e/README.md

# E2E Testing with playwright

## Running tests
The application must be started with `TEST_MODE=true`

```sh
$ TEST_MODE=true yarn dev
```

Then we can run a single suite with

```sh
$ yarn test:e2e ./tests/e2e/administration.spec.ts
```

Or all the tests with

```sh
$ yarn test:e2e
```

We can also provide some env vars to `test:e2e` script:
- `BASE_URL=<any_url>` Run the tests to the given url
- `PWDEBUG=1` Control the test execution

## Page Objects
- Any locator name must start with of one the following prefixes: `btn`, `link`, `input`, `select`, `checkbox`, `text`

## Important links
- [playwright docs](https://playwright.dev/docs/intro)

## Assertions and waiting

- Prefer Playwright web-first assertions such as `toBeVisible()` and `toHaveText()`. They retry until the expected condition is met.
- Use Playwright's `expect` matchers instead of Node-style `assert` statements.
- Rely on Playwright's built-in auto-waiting whenever possible.
- When an explicit wait is necessary, wait for a specific condition with APIs such as `locator.waitFor()`, `page.waitForURL()`, or `page.waitForResponse()`.
- Prefer waiting for observable conditions over fixed delays. If a fixed delay is unavoidable, document why no observable condition can be awaited.

```ts
 await expect(anyElement).toBeVisible();
 ```

# Playwright Locator Best Practices

## Preferred locator types:

### 1. By role `.getByRole()`:
This is the most recommended locator type. 
- It ensures our element is accessible to screen readers and other assistive technologies.
- It ensures that the element is uniquely identifiable.
- It's recommended to use the `exact` option to ensure that the locator doesn't match any other element with the same role


```ts
await page.getByRole('button', { name: 'Save', exact: true });

// Without the `exact` option, Playwright would match buttons with 'Save' and 'Save changes' labels.
```


### 2. By text `.getByText()` or `.getByLabel()`:
- Use this when locating by role is not possible or not sufficient.
- Be sure to restrict the scope of the locator to the element you are looking for.

### 3. Locator with `has`:
Our input elements hide the native input and render a custom component.

To target the input and trigger changes, you should locate the label that wraps the input and use the `has` locator.
```ts
page.locator('label', { has: this.page.getByRole('checkbox', { name: 'Private' }) });
```

## Locator types to avoid (at all costs):
If you are not able to find the element by role, label or text, it's a sign that the element is not accessible to the user.
The component should be refactored to allow a more accessible locator.
### 1. By `data-qa-id` or testId `.getByTestId()`:
```ts
// DON'T ❌ 
page.locator('[data-qa-id="menu-more-actions"]'); 

// DO ✅
page.getByRole('menu', {name: 'More actions', exact: true }); 
```

### 2. By elements and class names `.locator('div.class-name')`:
The HTML structure and/or class names can easily change over time, so it's better to use the locator by role and name.

```ts
// DON'T ❌
page.locator('#modal-root .rcx-button-group--align-end .rcx-button--primary');

// #modal-root was used to locate the injected portal element for the modal.
// This can be better located by role 'dialog' and making sure the modal has the proper name attribute.

// DO ✅
page.getByRole('dialog', name: 'Modal name example').getByRole('button', { name: 'Confirm', exact: true });
```

### 3. By position:
Using `nth-child` or similar selectors is not recommended as it can easily change.
It's a fragile locator and it's hard to maintain.

### 4. Parent/Child relationships: 
A change in the DOM structure can break the test.

## Use our page-objects:
> apps/meteor/tests/e2e/page-objects
- page-objects are a great way to reuse locators across tests using `getters` and `methods`.
- They make it easier to write tests that are more readable and maintainable.
- Always make sure to use the most restricted scope possible - not the whole page to avoid multiple matches.
- Page objects own navigation - see [Navigation](#navigation-goto-owns-the-wait).

If you are writing a new test, make sure to look at the existing page-objects to see if there is a suitable one for your use case.

If not, evaluate if creating a reusable getter/method is worth it and create the ones you need in the respective context.

E.g.:
Writing a new test for a sidebar behavior.
- check `apps/meteor/tests/e2e/page-objects/fragments/sidebar.ts` if the fragments you need are already there.
- If not, create new getters and/or methods in this file.

Usage example:

```ts
// apps/meteor/tests/e2e/page-objects/fragments/sidebar.ts
// ...

	get sidebar(): Locator {
		return this.page.getByRole('navigation', { name: 'sidebar' });
	}

	get channelsList(): Locator {
		return this.sidebar.getByRole('list', { name: 'Channels' });
	}

  // Restricted scope: inside navigation > sidebar > list named Channels > link with name
	getSearchRoomByName(name: string) {
		return this.channelsList.getByRole('link', { name });
	}
```

```ts
// test.spec.ts

  test('should display sidebar items', async ({ page }) => {
      poHomeChannel = new HomeChannel(page);
      await poHomeChannel.goto();
      const targetChannel = 'channel-test';

      await expect(poHomeChannel.sidebar.getSearchRoomByName(targetChannel)).toBeVisible();
  });
```

## Navigation: `goto()` owns the wait

`page.goto()` resolves as soon as the document loads, long before the SPA has rendered - the next
locator then races the app. So page objects own navigation: `goto()` navigates *and* waits.

```ts
poAdminUsers = new AdminUsers(page);
await poAdminUsers.goto(); // the next line can act on the page
```

Never call `page.goto()` from a test. If the page you need has no page object, add one - under
`Admin`, `Account` or `OmnichannelAdmin` it is usually two lines:

```ts
export class AdminThirdPartyLogin extends Admin {
	protected readonly route = AdminSectionsHref.thirdPartyLogin;

	protected readonly title = 'Third-party login';
}
```

`title` is the page's heading, matched with `exact: true` - copy it from
`packages/i18n/src/locales/en.i18n.json` rather than guessing the casing. It also scopes
`pageContent`, the `main` region to hang the page's other locators off.

Anything else extends `RoutedPage` directly and implements `waitForReady()`. Override it when the
heading is not enough - `AdminUsers` waits for its search box, `OmnichannelAdmin` for its table.

Two more hooks:

- `gotoExpecting(until)` - the route settles on something else, e.g. an upsell dialog on CE.
- `navigateTo(route, until?)` - build extra `gotoSomething()` methods when a page object owns more
  than one route (`gotoGeneral()`, `gotoChannel(name)`). `until` takes a `Locator` or an async waiter.

Auth screens (`Login`, `Registration`, `Authenticated`) take the url to navigate to, since an
anonymous visitor asking for `/home` lands somewhere else.

A raw `page.goto()` is still right for external urls, urls derived from `page.url()`, and tests that
must not wait for the route to settle.

## Cleanup after tests
- Remember to delete all users, channels, rooms, etc, created during the tests.
- Reset settings to their default values after the tests, if changed.
- Close all new pages opened during the tests.
- You can use the `test.afterAll()` or `test.afterEach()` methods to clean up after the tests.


```ts
// test.spec.ts

test.describe.serial('feature example', ({ api}) => {
	  let targetChannel;
	  let targetDiscussion;

    test.beforeAll(async ({ api }) => {
      // change setting value
		  await setSettingValueById(api, 'Accounts_AllowFeaturePreview', true);

      // create channel
      targetChannel = await createTargetChannel(api, { members: ['user1'] });

      // create discussion
      targetDiscussion = await createTargetDiscussion(api);
    });
    test.afterAll(async ({ api }) => {
      // reset setting value
		  await setSettingValueById(api, 'Accounts_AllowFeaturePreview', false);

      // delete  channel
      await deleteChannel(api, targetChannel);

      // delete discussion
      await deleteRoom(api, targetDiscussion._id);
    });
})
```

## General recommendations

### Use descriptive test names

Test names should clearly describe the behavior and expected outcome being verified.

### Use `test.describe` for grouping tests
It can be used to group related tests into a test suite. It provides a way to organize tests logically and improve the readability and maintainability of your test code.
```ts
test.describe('Feature Test', () => {
  test('should display the feature heading after navigation', async ({ api}) => {
    // do some tests
  });
});
```

### Use `test.step` for grouping steps
Enhances test readability and provides more detailed information in test reports
```ts
test.describe('Feature Test', () => {
  test('should display the feature heading after navigation', async ({ page }) => {
    await test.step('open the feature page', async () => {
      const poFeature = new FeaturePage(page);
      await poFeature.goto();
      await expect(page.getByRole('heading', { name: 'Feature' })).toBeVisible();
    });
  });
});
```

### Big test files should not be `.serial`:
- Ok for tests with very few steps, when steps have dependencies on each other, you can simulate the user flow sequentially.
- Avoid chaining big tests with `test.serial` - dependant steps make it harder to debug and/or make small changes
> If you are changing something on the 34th step, you would have to run the whole test suite multiple times during development, instead of olny running the test step in question.

## Performance patterns

E2E tests are the most expensive tests we run. Two patterns, applied together, typically cut a suite's runtime by ~80% and remove the most common sources of flake. They are the standard for new suites and the target for migrating existing ones.

### Pattern 1 — seed state through the API, not the UI

Use the browser **only for what the test actually verifies**. Everything else — creating rooms, DMs, discussions, threads, sending setup messages — goes through REST.

Why:
- A REST call costs 30–150ms; the equivalent UI flow (menu → modal → input → submit → wait for nav) costs 2–8s per step.
- API errors are deterministic and synchronous. UI errors manifest as timeouts on overloaded CI, which is a slow and ambiguous signal.
- The test fails only when the feature under test breaks, not when an unrelated setup UI regresses. A broken "create discussion" modal should not take down every test that needs a discussion as fixture.
- Removes the most flake-prone interactions: hover-revealed menus, modal animations, search debounces.

Do **not** apply when the setup UI is the actual subject of the test (`create-direct.spec.ts`, `create-discussion.spec.ts`, `create-channel.spec.ts`, etc.). There, keep one test per creation flow going through the UI; unrelated tests rely on the API path.

### Pattern 2 — share the browser context across a serial suite

For suites already using `test.describe.serial`, move `browser.newContext(), pageObject.goto()` and the initial room navigation from `beforeEach` to `beforeAll`.

Why: bootstrapping a Playwright context plus hydrating the Meteor app costs ~1.5–2.5s per test. In a serial suite the isolation cost is already paid — collecting the speed benefit is free.

Preconditions:
- Suite is `test.describe.serial`.
- All tests share the same user / storage state.
- Each test leaves the page in a known "home position" (base room open, no modals, threads, or side panels lingering).

Do **not** apply when:
- Tests need different users or storage states.
- Suite covers auth, 2FA, or session lifecycle — the browser state is the subject.
- Suite has more than ~15 tests: the debug cost of shared state outgrows the speed win (see "Big test files should not be `.serial`" above).

### Pattern 3 — navigate to a known room by URL, not by search

When a test already knows the room it needs (a channel created via API, `general`, etc.), open it directly with `poHomeChannel.gotoChannel(name)` instead of going home and searching for it.

```ts
// ❌ fragile — three independent things must align before the combobox `fill` resolves
await page.goto('/home');
await poHomeChannel.navbar.openChat(targetChannel);

// ✅ deterministic — navigate straight to the room, then wait for it to be ready
await poHomeChannel.gotoChannel(targetChannel);
```

Why: searching the navbar couples the navigation to (1) the app shell hydrating, (2) the **search index** having picked up the room — a real lag for a channel created moments earlier via API — and (3) the listbox rendering and the option becoming clickable. Any one stalling makes `searchInput.fill` hang until the test timeout, surfacing as the misleading `Target page, context or browser has been closed`. `gotoChannel` loads `/channel/<name>` and then `waitForChannel()` (main region, heading, message list, `aria-busy` cleared), so it has a proper readiness wait without the search dependency.

Do **not** apply when:
- The navbar search is the actual subject of the test.
- Navigating to a **DM** (`/direct/<username>`) or a **discussion** — `gotoChannel` builds a `/channel/` URL only.
- Reaching a channel the user is **not a member of** — the direct URL hits a different preview/join flow; verify the behavior before switching.

## API helpers for state seeding

Prefer these helpers in `beforeAll` / `beforeEach` and in setup `test.step`s. All live under `apps/meteor/tests/e2e/utils/`.

| Intent                               | Helper                                                    | REST endpoint             |
| ------------------------------------ | --------------------------------------------------------- | ------------------------- |
| Create public channel                | `createTargetChannel(api)`                                | `/channels.create`        |
| Create public channel (full room)    | `createTargetChannelAndReturnFullRoom(api)`               | `/channels.create`        |
| Create private channel               | `createTargetPrivateChannel(api)`                         | `/groups.create`          |
| Create private group (full room)     | `createTargetGroupAndReturnFullRoom(api)`                 | `/groups.create`          |
| Create team                          | `createTargetTeam(api)`                                   | `/teams.create`           |
| Create discussion (fresh parent)     | `createTargetDiscussion(api)`                             | `/rooms.createDiscussion` |
| Create discussion on existing msg    | `createDiscussion(api, parentRoomId, parentMsgId, name)`  | `/rooms.createDiscussion` |
| Create DM room (get id back)         | `createDirectMessageRoom(api, username)`                  | `/im.create`              |
| Send message to a room               | `sendMessage(api, roomId, msg)`                           | `/chat.sendMessage`       |
| Send message inside a thread         | `sendMessage(api, roomId, msg, parentMsgId)`              | `/chat.sendMessage`       |
| Send message as a specific user      | `sendMessageFromUser(request, user, rid, msg)`            | `/chat.postMessage`       |
| Delete channel (by name)             | `deleteChannel(api, roomName)`                            | `/channels.delete`        |
| Delete room (by id)                  | `deleteRoom(api, roomId)`                                 | `/rooms.delete`           |
| Delete team                          | `deleteTeam(api, teamName)`                               | `/teams.delete`           |

If the helper you need is missing, add it under `utils/` and re-export it from `utils/index.ts` rather than inlining the REST call in the spec.

## Template: optimized `.serial` suite

Copy-paste starting point for a new suite that applies both patterns.

```ts
import type { Page, BrowserContext } from 'playwright-core';

import { Users } from './fixtures/userStates';
import { HomeChannel } from './page-objects';
import { createTargetChannel, sendMessage } from './utils';
import { expect, test } from './utils/test';

test.use({ storageState: Users.admin.state });

test.describe.serial('Feature X', () => {
    let poHomeChannel: HomeChannel;
    let targetChannel: string;
    let targetChannelId: string;
    let page: Page;
    let context: BrowserContext;

    test.beforeAll(async ({ browser, api }) => {
        targetChannel = await createTargetChannel(api);
        const info = await (await api.get(`/channels.info?roomName=${targetChannel}`)).json();
        targetChannelId = info.channel._id;

        context = await browser.newContext();
        page = await context.newPage();
        poHomeChannel = new HomeChannel(page);

        await poHomeChannel.gotoChannel(targetChannel);
    });

    test.afterAll(async ({ api }) => {
        await api.post('/channels.delete', { roomName: targetChannel });
        await page.close();
        await context.close();
    });

    test('exercises the feature', async ({ api }) => {
        const messageText = 'seed';
        await sendMessage(api, targetChannelId, messageText);
        await expect(poHomeChannel.content.lastUserMessage).toContainText(messageText);
        // assertions for the feature under test
    });
});
```

## Migrating an existing suite

Recipe for a single spec. Keep PRs to at most 5 files so reviews stay tractable.

1. **Baseline**. Run the spec three times locally and record the median per-test time. Paste it in the PR body.
2. **Map setup**. For every test, mark each `test.step` and every `beforeEach` call that only prepares state (creates rooms, messages, threads, opens menus). These are candidates for API seeding.
3. **Apply Pattern 1**. Replace the marked UI setup with helpers from the table above. If a helper is missing, add it under `utils/` and export it from `utils/index.ts`.
4. **Apply Pattern 2** — only if the suite is `.serial` and the preconditions hold. Move context, page, navigation to `beforeAll`. Close page and context in `afterAll`. Ensure every test returns the page to the home position.
5. **Check coverage when consolidating**. If you merge tests (e.g. four formatting tests into one), confirm the merged test still asserts every behavior the originals covered. List the merges in the PR body.
6. **Compare**. Run three times again, record the new median. If the improvement is under 30%, revisit — the coupling may not be worth it.
7. **PR body must include**: before/after timings, the list of UI setups moved to API, and an explicit reason if you chose not to apply one of the patterns.

## Anti-patterns to flag in review

- `poHomeChannel.content.sendMessage(...)` used inside `beforeEach` or `beforeAll` — that is setup, should be `sendMessage(api, ...)`.
- Opening meatball menus or modals purely to create a discussion, thread, or DM as a setup step.
- `test.describe.serial` that builds a fresh context and navigates in `beforeEach` — both should be shared in `beforeAll`.
- Any raw `page.goto(...)` in a spec — use the page object's `goto()` (see [Navigation](#navigation-goto-owns-the-wait)).
- `goto()` + `navbar.openChat(name)` to reach a room the test already knows — use `poHomeChannel.gotoChannel(name)` (see Pattern 3). Searching a just-created channel races the search index and hangs until timeout.
- New non-serial suites whose tests still each carry >3s of UI setup.
- Inline `api.post('/im.create', …)` / `api.post('/chat.sendMessage', …)` in a spec instead of extending the helpers in `utils/`.