AGENTS.md

1# E2E — dotCMS Playwright
2 
3> **Source of truth for code conventions.** `CLAUDE.md` in this directory points here.
4 
5**How to run tests, CI parity, unit vs E2E cheat sheet, and AI workflow:** see [README.md](README.md).
6 
7## Layout
8 
9```
10src/
11  fixtures/     # auth, API setup (e.g. relationship.fixture.ts)
12  pages/        # shared page objects (*.page.ts)
13  utils/        # iframe, portlets, credentials
14  requests/     # REST API helpers for test data (content types, contentlets, sites, …)
15  tests/edit-content/fields/{field-type}/
16    helpers/    # locators for that field only
17    *.spec.ts
18playwright.config.ts
19```
20 
21## Conventions
22 
23- **Files:** kebab-case; specs `{feature}-{journey}.spec.ts`; helpers in `helpers/` (no suffix); shared pages `*.page.ts`; fixtures `{feature}.fixture.ts`.
24- **Tests:** `test('action description @critical')` — action only, no "should"; `@critical` / `@smoke` optional.
25- **Classes:** locator wrappers named like the UI (`RelationshipField`); pages end with `Page`; no `Component` suffix.
26 
27## Locators
28 
291. `getByRole` → 2. `getByTestId` → 3. `getByLabel` → 4. CSS **only** in Dojo iframe.
30 
31Unsure? **Codegen first** (`npx playwright codegen http://localhost:4200/dotAdmin`). Avoid fragile `#dijit_*` IDs, CSS when `data-testid` exists, `.locator('button')` on `getByRole('button')`, and `isVisible()` for waits (use `waitFor` / `expect().toBeVisible`).
32 
33## Angular + Dojo
34 
35- **Angular:** shell, edit form, dialogs — main `page`.
36- **Dojo:** content listing in `#detailFrame` — `getLegacyFrame(page)` from `@utils/iframe`.
37- **Nav:** `Portlet` from `@utils/portlets`; new content via `NewEditContentFormPage.goToNew()` (listing → New), not direct `/content/new/` URL.
38- **Dojo menus:** wait for menu visibility, then click normally (no `force: true`).
39 
40Field-specific selectors and flows: copy `tests/.../helpers/` and nearest `*.spec.ts` (e.g. `relationship-field/`, `key-value-field/`).
41 
42## Where to put code
43 
44| Need | Place |
45|---|---|
46| Cross-feature UI | `pages/` |
47| One field / feature | `tests/.../helpers/` |
48| Generic (iframe, URLs) | `utils/` |
49| HTTP setup | `requests/` + `fixtures/` |
50 
51## REST API setup (`src/requests/`)
52 
53**Always create test data through the REST API** — never via the UI during setup. Specs and fixtures import helpers from `src/requests/`; raw endpoint calls live there, not in test files.
54 
55Modules: `contentType.ts`, `contentlets.ts`, `sites.ts`, `folders.ts`, `pages.ts`, `templates.ts`, `schemas.ts`, `workflow.ts`, `workflowActions.ts`, `field-variables.ts`, `updateFeatureFlag.ts`.
56 
57**Adding a new helper:**
58 
591. Search `src/requests/` first — reuse an existing function if it covers your endpoint/payload.
602. Do not duplicate the same API call in a spec, fixture, or another request file.
613. If missing, add to the appropriate `src/requests/*.ts` file so all specs can reuse it.
624. Multi-step orchestration → `fixtures/`; single-endpoint calls → `requests/`.
63 
64## Data & isolation
65 
66- Assume **empty starter** — create types/content via API helpers in `src/requests/` inside `beforeEach`, delete in `afterEach`; unique names (`testSuffix`, `Date.now()`, UUID).
67- **`mode: 'serial'`:** use only when tests truly share one contentlet inode/workflow step or strict ordering inside one test chain. Do **not** use serial to guard describe-level `let` — create content types inside each test (or `try/finally` delete) so `fullyParallel` and CI `workers: 2` can run tests in the same file concurrently.
68- Content types need **SystemWorkflow** for Save — see existing fixtures/requests.
69- **Relationships:** reuse `fixtures/relationship.fixture.ts` and `tests/edit-content/fields/relationship-field/`; do not invent payloads or cardinality numbers.
70 
71## Must-know gotchas
72 
731. Login: `click` → `fill` email → `Tab` → then password (`userNameInput`, `password`, `submitButton`).
742. `waitForResponse` **before** the click that triggers the request.
753. Relationship/menu copy: use fixture + helpers; labels are **"Existing Content"** / **"New Content"** (verify with codegen).
764. Single-cardinality: menu items disable with `aria-disabled`; `+` button stays enabled.
775. Custom types for editor v2: `metadata.CONTENT_EDITOR2_ENABLED`; HTML pages need real `hostFolder` from `GET /api/v1/site`, not `'default'`.
786. HTML edit: no `data-testid="title"` — `goToContent()` may hang; use direct `#/content/{inode}` + wait for sidebar.
79