docs(e2e): Revise README for dotCMS End-to-End Testing (dotCMS#36602)

This pull request updates the documentation for the dotCMS UI E2E test
suite to clarify project structure, setup, and best practices. The
changes improve onboarding for both human developers and AI agents,
standardize terminology, and provide detailed guidance on data setup,
environment configuration, and when to use E2E vs. unit/integration
tests. The documentation now emphasizes REST API-based test data setup,
project layout, and the preferred workflow for writing and debugging
tests.

**Major documentation improvements:**

*General onboarding and entry points:*
- Updated `README.md` to serve as the canonical entry point for human
developers, with step-by-step local debug flow, CI parity instructions,
and a clear project layout.
- Clarified that `AGENTS.md` is the source of truth for code conventions
and is the primary reference for AI agents, while humans should start at
`README.md`.
[[1]](diffhunk://#diff-321c3ccef76190510309d87100a88a346ae02222eadd2be3c29ce977f44530dcL3-R5)
[[2]](diffhunk://#diff-ff8c2a8737638f98cbda3a44a2446fc3e7e129efe9afe526cb9ccea38434f918L3-R3)

*Test data setup and REST API usage:*
- Standardized the requirement that all test data must be created via
REST API helpers in `src/requests/`, not through the UI, and described
the available helper modules and how to add new ones.
[[1]](diffhunk://#diff-321c3ccef76190510309d87100a88a346ae02222eadd2be3c29ce977f44530dcR51-R66)
[[2]](diffhunk://#diff-d013b2a862cab8f5c8a89abc5657680b0f8f881e854ad0997d64868d36113afcL1-R263)
- Updated documentation to clarify that specs and fixtures should import
from `src/requests/`, with orchestration in `fixtures/` and raw endpoint
calls in `requests/`.
[[1]](diffhunk://#diff-321c3ccef76190510309d87100a88a346ae02222eadd2be3c29ce977f44530dcL12-L33)
[[2]](diffhunk://#diff-321c3ccef76190510309d87100a88a346ae02222eadd2be3c29ce977f44530dcR51-R66)
[[3]](diffhunk://#diff-d013b2a862cab8f5c8a89abc5657680b0f8f881e854ad0997d64868d36113afcL1-R263)

*Environment and workflow:*
- Expanded and clarified environment variable documentation, test run
modes (dev vs. CI), and the full local/CI test lifecycle with commands
and expected behavior.
- Provided a detailed cheat sheet for when to use unit, integration, or
E2E tests, and established rules for test isolation and data cleanup.

*Project structure and conventions:*
- Improved project layout documentation, clarified folder purposes, and
reinforced file naming and locator conventions.
[[1]](diffhunk://#diff-321c3ccef76190510309d87100a88a346ae02222eadd2be3c29ce977f44530dcL12-L33)
[[2]](diffhunk://#diff-d013b2a862cab8f5c8a89abc5657680b0f8f881e854ad0997d64868d36113afcL1-R263)
- Added guidance on how to create new E2E tests, including copying
patterns, using the Page Object Model, and locator priority.

*AI-assisted workflow:*
- Outlined a recommended process for AI-assisted E2E test creation,
including redundancy checks and integration with QA/test planning.

This PR fixes: dotCMS#31718

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: nicobytes

core-web/apps/dotcms-ui-e2e/AGENTS.md

@@ -1,6 +1,8 @@
 # E2E — dotCMS Playwright
 
-> **Source of truth.** `CLAUDE.md` in this directory only points here.
+> **Source of truth for code conventions.** `CLAUDE.md` in this directory points here.
+
+**How to run tests, CI parity, unit vs E2E cheat sheet, and AI workflow:** see [README.md](README.md).
 
 ## Layout
 
@@ -9,28 +11,13 @@ src/
   fixtures/     # auth, API setup (e.g. relationship.fixture.ts)
   pages/        # shared page objects (*.page.ts)
   utils/        # iframe, portlets, credentials
-  requests/     # content type / contentlet API
+  requests/     # REST API helpers for test data (content types, contentlets, sites, …)
   tests/edit-content/fields/{field-type}/
     helpers/    # locators for that field only
     *.spec.ts
 playwright.config.ts
 ```
 
-## Run
-
-```bash
-pnpm nx e2e dotcms-ui-e2e --grep "pattern"
-HEADLESS=true pnpm nx e2e dotcms-ui-e2e --grep "pattern"
-pnpm e2e:dev | e2e:dev:headless | e2e:ci | e2e:ui   # from core-web/
-npx playwright codegen http://localhost:4200/dotAdmin
-```
-
-| | `dev` (default) | `ci` |
-|---|---|---|
-| URL | `:4200` (proxy → `:8080`) | `:8080` direct |
-
-Env: `CURRENT_ENV`, `HEADLESS`, `E2E_BASE_URL`, `E2E_REUSE_EXISTING_SERVER`. Reports: `dist/.playwright/apps/dotcms-ui-e2e/`.
-
 ## Conventions
 
 - **Files:** kebab-case; specs `{feature}-{journey}.spec.ts`; helpers in `helpers/` (no suffix); shared pages `*.page.ts`; fixtures `{feature}.fixture.ts`.
@@ -41,7 +28,7 @@ Env: `CURRENT_ENV`, `HEADLESS`, `E2E_BASE_URL`, `E2E_REUSE_EXISTING_SERVER`. Rep
 
 1. `getByRole` → 2. `getByTestId` → 3. `getByLabel` → 4. CSS **only** in Dojo iframe.
 
-Unsure? **Codegen first.** Avoid fragile `#dijit_*` IDs, CSS when `data-testid` exists, `.locator('button')` on `getByRole('button')`, and `isVisible()` for waits (use `waitFor` / `expect().toBeVisible`).
+Unsure? **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`).
 
 ## Angular + Dojo
 
@@ -61,9 +48,22 @@ Field-specific selectors and flows: copy `tests/.../helpers/` and nearest `*.spe
 | Generic (iframe, URLs) | `utils/` |
 | HTTP setup | `requests/` + `fixtures/` |
 
+## REST API setup (`src/requests/`)
+
+**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.
+
+Modules: `contentType.ts`, `contentlets.ts`, `sites.ts`, `folders.ts`, `pages.ts`, `templates.ts`, `schemas.ts`, `workflow.ts`, `workflowActions.ts`, `field-variables.ts`, `updateFeatureFlag.ts`.
+
+**Adding a new helper:**
+
+1. Search `src/requests/` first — reuse an existing function if it covers your endpoint/payload.
+2. Do not duplicate the same API call in a spec, fixture, or another request file.
+3. If missing, add to the appropriate `src/requests/*.ts` file so all specs can reuse it.
+4. Multi-step orchestration → `fixtures/`; single-endpoint calls → `requests/`.
+
 ## Data & isolation
 
-- Assume **empty starter** — create types/content via API in `beforeEach`, delete in `afterEach`; unique names (`testSuffix`, `Date.now()`, UUID).
+- Assume **empty starter** — create types/content via API helpers in `src/requests/` inside `beforeEach`, delete in `afterEach`; unique names (`testSuffix`, `Date.now()`, UUID).
 - Content types need **SystemWorkflow** for Save — see existing fixtures/requests.
 - **Relationships:** reuse `fixtures/relationship.fixture.ts` and `tests/edit-content/fields/relationship-field/`; do not invent payloads or cardinality numbers.
 

core-web/apps/dotcms-ui-e2e/CLAUDE.md

@@ -1,3 +1,3 @@
 # E2E — dotCMS Playwright
 
-**Read [AGENTS.md](AGENTS.md)** — single source of truth for structure, commands, locators, and gotchas.
+**Humans:** start at [README.md](README.md). **Agents:** read [AGENTS.md](AGENTS.md) for code conventions, locators, and gotchas.