---
description: "Playwright E2E tests for the dotCMS admin UI. Use when editing specs, page objects or helpers under core-web/apps/dotcms-ui-e2e."
globs: core-web/apps/dotcms-ui-e2e/**/*.ts
alwaysApply: false
---

# E2E Tests (`core-web/apps/dotcms-ui-e2e`)

**Source of truth: `core-web/apps/dotcms-ui-e2e/AGENTS.md`.** It says so itself, and
`docs/testing/E2E_TESTS.md` points there too. Read it before writing a spec — it carries the real
layout, the Dojo iframe handling, the REST setup modules and a list of gotchas that cost hours if
missed. This rule is a reminder, not a second copy.

For running the suite and CI parity: `@docs/testing/E2E_TESTS.md`.

## Locators — in this order

1. `getByRole` → 2. `getByTestId` → 3. `getByLabel` → 4. CSS **only** inside the Dojo iframe.

`getByRole` comes first, and CSS is legitimate in the legacy Dojo portlets where `data-testid` does
not exist — reach for `getLegacyFrame(page)` from `@utils/iframe` there. Unsure about a selector?
Run codegen before guessing.

Avoid `#dijit_*` ids, `.locator('button')` where `getByRole('button')` works, and `isVisible()` as a
wait — use `waitFor` or `expect().toBeVisible`.

## Test data

Create it through the **REST API**, never through the UI during setup. Helpers live in
`src/requests/`; search there before writing a new one, and put multi-step orchestration in
`src/fixtures/`. Assume an empty starter: create in `beforeEach`, delete in `afterEach`, unique
names.

## Two traps worth carrying inline

- **`waitForResponse` goes before the click** that triggers the request, not after.
- **`page.on('dialog', ...)` goes before the click** too. Playwright auto-dismisses native dialogs,
  so a handler attached afterwards sees nothing and the test hangs to timeout instead of failing
  usefully.

## Environment

`CURRENT_ENV=ci` changes the login path and stops Playwright starting its own server on :4200. To
run against a container: `E2E_BASE_URL=http://localhost:<port> CURRENT_ENV=ci`.

## On-demand

- `@docs/testing/E2E_TESTS.md` — running the suite, CI parity, sharding
- `core-web/apps/dotcms-ui-e2e/AGENTS.md` — conventions, Dojo, REST setup, gotchas
- `core-web/apps/dotcms-ui-e2e/README.md` — local loop, Docker, Playwright UI mode