docs(e2e): consolidate guidelines, remove duplication

- Replace inline rules in AGENTS.md with pointer to guidelines file
- Remove redundant waitForMendixApp calls from template (fixture wraps goto)
- Drop checklist section — rules already covered inline
- Drop Session Management section — merged into Imports & Setup
- Expand Locator Patterns: composed selectors, text-only = false positive

Author: samuelreichert

AGENTS.md

@@ -35,14 +35,7 @@ docs/requirements/                -> Detailed technical requirements
 
 ## E2E Test Rules (Playwright)
 
-- Import from `@mendix/run-e2e/fixtures` (not `@playwright/test`)
-- Wait with `waitForMendixApp(page)`, never `waitForTimeout` or `networkidle`
-- Use web-first assertions: `toBeVisible`, `toHaveCount`, `toContainText`, `toHaveCSS`
-- Locators: prefer `.mx-name-*` attributes over nth() or text selectors
-- Screenshots: no per-test threshold overrides, ensure element visible first
-- No manual afterEach logout — fixture handles session lifecycle
-- Tag critical-path tests with `@smoke`
-- See `docs/requirements/e2e-test-guidelines.md` for full rules + template
+- docs/requirements/e2e-test-guidelines.md — Full rules + template
 
 ## Development Setup
 

docs/requirements/e2e-test-guidelines.md

@@ -1,110 +1,101 @@
 # E2E Test Guidelines
 
-Rules for writing reliable, non-flaky Playwright E2E tests in this monorepo. Derived from systematic fixes to 58+ spec files.
+Rules for writing reliable, non-flaky Playwright E2E tests in this monorepo.
 
 ## Imports & Setup
 
 Always use the custom fixtures, never raw Playwright:
 
 ```javascript
 import { test, expect } from "@mendix/run-e2e/fixtures";
-import { waitForMendixApp } from "@mendix/run-e2e/mendix-helpers";
 ```
 
-The custom fixture:
+Import helpers only when explicitly needed:
 
-- Auto-wraps `page.goto()` to call `waitForMendixApp()`
-- Manages worker-scoped Mendix sessions (1 per worker, auto-logout on teardown)
-- No manual `afterEach` logout needed
+```javascript
+import { waitForDataReady } from "@mendix/run-e2e/mendix-helpers";
+```
 
-## Waiting Strategies
+The custom fixture:
 
-### Hierarchy (use the highest applicable level)
+- Auto-wraps `page.goto()` to call `waitForMendixApp()` — do NOT call it manually after `goto`
+- Worker-scoped sessions: 1 Mendix session per Playwright worker (4 in CI, 2 locally)
+- Auto-logout on teardown — no manual `afterEach` logout needed
 
-1. `waitForMendixApp(page)` — session exists + no progress indicator + `.mx-page` rendered
-2. `await expect(element).toBeVisible()` — specific element appeared
-3. `await expect(rows).toHaveCount(N)` — data loaded with expected count
-4. `waitForDataReady(page)` — opt-in ONLY when data sync timing genuinely matters
+## Waiting Strategies
 
-### Banned Patterns
+Prefer web-first assertions over explicit waits — they auto-retry until timeout.
 
 | Don't                                            | Do Instead                            | Why                                                  |
 | ------------------------------------------------ | ------------------------------------- | ---------------------------------------------------- |
 | `page.waitForTimeout(N)`                         | Web-first assertion on expected state | Arbitrary delays: too short = flaky, too long = slow |
 | `page.waitForLoadState("networkidle")`           | `waitForMendixApp(page)`              | Unrelated network traffic delays indefinitely        |
 | `page.waitForSelector(...)` then separate assert | `await expect(locator).toBeVisible()` | Combined wait+assert auto-retries                    |
 
+Use `waitForDataReady(page)` only when data sync timing genuinely matters.
+
 ## Assertions
 
-Always prefer Playwright web-first assertions — they auto-retry until timeout.
+Preferred: `toBeVisible`, `toHaveText`, `toHaveCount`, `toHaveCSS`, `toContainText`, `toHaveScreenshot`.
 
 | Don't                                                                | Do Instead                                           | Why                                              |
 | -------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------ |
 | `const text = await el.allTextContents(); expect(text).toEqual(...)` | `await expect(locator).toContainText([...])`         | Non-retrying snapshot vs auto-retrying           |
 | `await el.evaluate(el => el.getBoundingClientRect())`                | `await expect(el).toHaveCSS("transform", "...")`     | DOM inspection races vs CSS state assertion      |
-| `el.nth(1)` to disambiguate                                          | More specific selector or wait first                 | nth() fragile to render order                    |
 | `page.$$eval(...)` to extract data                                   | `expect(locator).toContainText()` or `.toHaveText()` | evaluate snapshots DOM; locator assertions retry |
 
-Preferred assertions: `toBeVisible`, `toHaveText`, `toHaveCount`, `toHaveCSS`, `toContainText`, `toHaveScreenshot`.
-
 ## Locator Patterns
 
-| Don't                                   | Do Instead                                 | Why                                     |
-| --------------------------------------- | ------------------------------------------ | --------------------------------------- |
-| `.nth(N)` on ambiguous selectors        | `.mx-name-*` attribute selectors           | nth fragile to DOM order                |
-| Complex CSS selectors                   | `page.locator(".mx-name-widgetName")`      | mx-name attributes are stable, semantic |
-| `page.click("text=...")` for navigation | `page.locator(".mx-name-navItem").click()` | Text fragile to i18n/copy changes       |
+Prefer `.mx-name-*` attributes — set by Mendix Studio Pro from widget names, stable across DOM refactors and i18n changes.
+
+| Don't                               | Do Instead                                      | Why                                          |
+| ----------------------------------- | ----------------------------------------------- | -------------------------------------------- |
+| `.nth(N)` on ambiguous selectors    | `.mx-name-*` attribute selectors                | nth fragile to DOM order                     |
+| `page.click("text=...")` standalone | `.mx-name-*` or compose: CSS scope + role/label | Text alone = false positive, fragile to i18n |
+| Asserting text content in E2E       | Unit/snapshot tests for text correctness        | Text assertions belong in unit tests         |
+
+When `.mx-name-*` is not available, compose locators — see [Playwright locator docs](https://playwright.dev/docs/locators):
+
+```javascript
+// mx-name — preferred
+page.locator(".mx-name-btnSubmit");
+
+// composed: CSS scope + role
+page.locator(".mx-name-myForm").getByRole("button", { name: "Save" });
+
+// composed: CSS scope + label
+page.locator(".mx-name-myWidget").getByLabel("Start date");
+```
 
 ## Screenshot Testing
 
 - No per-test `{ threshold: N }` or `{ maxDiffPixels: N }` overrides — use global config (`threshold: 0.1`)
 - Always ensure element is visible before screenshot: `await expect(el).toBeVisible()`
 - Animations disabled globally (`animations: "disabled"` + `reducedMotion: "reduce"`)
 
-## Session Management
-
-- Worker-scoped sessions: 1 Mendix session per Playwright worker
-- Workers: 4 in CI, 2 locally (stays under 5-session license limit)
-- No manual `afterEach` logout — fixture handles cleanup
-- No per-test browser context creation
-
 ## ESLint Enforcement
 
-These rules are configured in `automation/run-e2e/eslint.config.mjs`:
+Configured in `automation/run-e2e/eslint.config.mjs`:
 
 ```
 playwright/no-wait-for-timeout: error
 playwright/no-networkidle: warn
 playwright/prefer-web-first-assertions: warn
 ```
 
-## Code Review Checklist
-
-- [ ] Uses `@mendix/run-e2e/fixtures` import (not `@playwright/test`)
-- [ ] No `waitForTimeout` calls
-- [ ] No `waitForLoadState("networkidle")` without explicit justification
-- [ ] All assertions use web-first Playwright assertions
-- [ ] No per-test screenshot threshold overrides
-- [ ] No manual `afterEach` logout
-- [ ] Locators use `.mx-name-*` attributes where possible
-- [ ] Tests tagged `@smoke` if they cover critical paths
-
 ## Spec File Template
 
 ```javascript
 import { test, expect } from "@mendix/run-e2e/fixtures";
-import { waitForMendixApp } from "@mendix/run-e2e/mendix-helpers";
 
 test.describe("WidgetName", () => {
     test.beforeEach(async ({ page }) => {
         await page.goto("/");
-        await waitForMendixApp(page);
     });
 
-    test("describes user-visible behavior", async ({ page }) => {
+    test("describes user-visible behavior @smoke", async ({ page }) => {
         // Arrange
         await page.locator(".mx-name-navItem").click();
-        await waitForMendixApp(page);
 
         // Act
         await page.locator(".mx-name-myWidget .some-input").fill("value");