From 913101737d566bdd1289ef88b63e78fc6fe24989 Mon Sep 17 00:00:00 2001
From: Santiago Greco <fsgreco@redhat.com>
Date: Fri, 14 Aug 2026 11:17:47 +0200
Subject: [PATCH] CONSOLE-5454: Shared Playwright e2e context and test
 generation skill

Refactor e2e skill architecture to separate universal Playwright
knowledge from Cypress-specific migration content. This formalizes
the approach discussed in Console CCSIG calls.

- Create e2e-context.md: shared Playwright reference (patterns,
  fixtures, selectors, isolation strategies, flakiness prevention)
  consumed by gen-e2e-test, migrate-cypress, and debug-test
- Slim migration-context.md to Cypress-only content (translation
  tables, transformation rules, Gherkin collapse)
- Create gen-e2e-test skill for writing Playwright tests from scratch
- Add flakiness prevention guidance to both shared context and
  migrate-cypress skill
- Update migrate-cypress and debug-test to reference shared context

Assisted-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/e2e-context.md                  | 636 ++++++++++++++++++++++++
 .claude/migration-context.md            | 310 ++----------
 .claude/skills/debug-test/SKILL.md      |  32 +-
 .claude/skills/gen-e2e-test/SKILL.md    | 137 +++++
 .claude/skills/migrate-cypress/SKILL.md |  31 +-
 5 files changed, 871 insertions(+), 275 deletions(-)
 create mode 100644 .claude/e2e-context.md
 create mode 100644 .claude/skills/gen-e2e-test/SKILL.md

diff --git a/.claude/e2e-context.md b/.claude/e2e-context.md
new file mode 100644
index 00000000000..2c0ae2b054c
--- /dev/null
+++ b/.claude/e2e-context.md
@@ -0,0 +1,636 @@
+# Playwright E2E Test Context
+
+Shared reference for writing, migrating, and debugging Playwright e2e tests in OpenShift Console. Used by `/gen-e2e-test`, `/migrate-cypress`, and `/debug-test` skills.
+
+## High-Level Principles
+
+1. **Self-contained tests.** Each `test()` block must create its own resources, assert independently, and clean up after itself. Never rely on test execution order or shared mutable state. Exception: Strategy B allows sharing read-only resources via `beforeAll`/`afterAll` when per-test creation is too expensive.
+2. **Use the most specific API.** Prefer `getByTestId()`, `getByRole()`, `getByText()`, `getByLabel()` over generic `page.locator()`. Use `page.locator('[data-test="..."]')` only when other methods don't apply.
+3. **Leverage the framework.** Use existing page objects, clients, and fixtures. Search `e2e/pages/` before creating new page objects.
+4. **Live verification.** Use Playwright MCP browser tools to verify selectors, navigation flows, and element presence against the live UI before finalizing code.
+
+---
+
+## Project Structure & File Conventions
+
+```text
+frontend/
+  playwright.config.ts          # Config: testIdAttribute='data-test', viewport=1920x1080, timeout=120s
+  e2e/
+    fixtures/                   # Test fixtures (cleanup, k8sClient, testConfig)
+      index.ts                  # Main fixture file. Exports test, expect
+      cleanup-fixture.ts        # CleanupFixture implementation
+    clients/
+      kubernetes-client.ts      # KubernetesClient: all cluster API interactions
+    pages/                      # Page objects. Extend BasePage
+      base-page.ts              # Abstract base: robustClick, goTo, waitForLoadingComplete, etc.
+      <feature>.ts              # Feature-specific page objects
+    tests/                      # Test specs
+      <package>/                # Grouped by Playwright project
+        <name>.spec.ts          # Admin tests
+        developer/              # Developer-persona tests
+          <name>.spec.ts
+    mocks/                      # Test data (TypeScript objects and YAML manifests)
+    setup/                      # Global setup/teardown (auth, cluster, knative)
+```
+
+### Playwright Projects
+
+Tests are grouped by project, which determines auth state and test directory:
+
+| Project | Test directory | Auth |
+|---------|---------------|------|
+| `smoke` | `e2e/tests/smoke/` | admin |
+| `console` | `e2e/tests/console/` | admin |
+| `dev-console` | `e2e/tests/dev-console/` | admin |
+| `helm` | `e2e/tests/helm/` | admin |
+| `knative` | `e2e/tests/knative/` | admin |
+| `olm` | `e2e/tests/olm/` | admin |
+| `topology` | `e2e/tests/topology/` | admin |
+| `webterminal` | `e2e/tests/webterminal/` | admin |
+
+Projects with developer auth variants: `smoke-developer`, `dev-console-developer`, `topology-developer`, `webterminal-developer`. Developer tests go in a `developer/` subdirectory.
+
+---
+
+## Test Selectors
+
+Config: `testIdAttribute: 'data-test'` in `playwright.config.ts`, so `page.getByTestId('x')` queries `[data-test="x"]`.
+
+**Always use `page.getByTestId('x')`** for element selection. If a React element only has a legacy test attribute (`data-test-id`, `data-test-selector`, `data-test-action`, `data-test-dropdown-menu`, etc.) but no `data-test`, **add `data-test="<value>"` to the React component source** so `getByTestId()` can be used. Never remove legacy attributes since external consumers may depend on them.
+
+### Locator Priority
+
+1. `getByTestId('x')` for elements with `data-test`
+2. `getByRole('button', { name: 'Save' })` for interactive elements by role
+3. `getByText('text')` or `locator('selector', { hasText: 'text' })` for text content
+4. `locator('css-selector')` as a last resort, for elements that cannot be located clearly by role or by text
+
+### PatternFly wrapper elements
+
+Some PatternFly components place `data-test` on a wrapper element, not the actionable child. For example, `TextInputGroup` wraps `<input>` in a `<div>` that carries `data-test`. If `getByTestId('x').fill()` fails with "Element is not an input", chain `.locator('input')` or `.getByRole('textbox')` to reach the actionable child.
+
+```typescript
+// WRONG: data-test is on the wrapper div, not the input
+await this.page.getByTestId('console-select-search-input').fill(text);
+
+// RIGHT: chain to the actual input element
+await this.page.getByTestId('console-select-search-input').locator('input').fill(text);
+```
+
+### Adding `data-test` to React Components
+
+When a React component has only a legacy test attribute:
+
+1. Find the React component that renders the element.
+2. Add `data-test="x"` alongside the existing legacy attribute.
+3. In the page object, use `this.page.getByTestId('x')`.
+
+```tsx
+// Before
+<div data-test-id="horizontal-link-Details">Details</div>
+
+// After: data-test added, legacy preserved
+<div data-test="horizontal-link-Details" data-test-id="horizontal-link-Details">Details</div>
+```
+
+**Custom React components vs DOM elements:** `data-test="x"` on a native DOM element (`<div>`, `<button>`) creates the attribute directly. On a custom React component (`<ConsoleSelect>`, `<Dropdown>`), it becomes a prop that may be silently ignored if the component doesn't forward it. Check the component's prop interface. Many PF/console components use a `dataTest` prop instead. Verify the attribute reaches the DOM with the browser inspector.
+
+```tsx
+// WRONG: data-test on custom component is a prop, not a DOM attribute
+<ConsoleSelect data-test="my-select" />  // silently ignored
+
+// RIGHT: use the component's dataTest prop
+<ConsoleSelect dataTest="my-select" />   // forwarded to internal DOM element
+```
+
+In page objects, always use `getByTestId()` never reference legacy attributes directly:
+
+```typescript
+// WRONG: using legacy selector directly
+private readonly resourceRows = this.page.locator('[data-test-rows="resource-row"]');
+
+// RIGHT: use getByTestId (add data-test to React source if needed)
+private readonly resourceRows = this.page.getByTestId('resource-row');
+```
+
+---
+
+## Page Object Pattern
+
+All page objects extend `BasePage` (located at `e2e/pages/base-page.ts`).
+
+### BasePage Methods
+
+| Method | Purpose |
+|--------|---------|
+| `goTo(url)` | Navigate and wait for load |
+| `robustClick(locator, opts?)` | Click with retry logic for PatternFly overlay interception |
+| `waitForLoadingComplete(timeout?)` | Wait for all loading indicators to clear |
+| `navigateToTab(locator, timeout?)` | Navigate to a horizontal tab |
+| `clickButtonByText(text)` | Click a button by visible text |
+| `switchPerspective(target)` | Switch between Administrator and Developer perspectives |
+| `ensureFormView(locator?)` | Ensure form view is active (vs YAML) |
+| `getEditorContent()` / `setEditorContent(content)` | Monaco editor interaction |
+| `locator(selector, opts?)` | Scoped locator creation |
+| `retryOnError()` | Dismiss error pages and retry |
+
+### Conventions
+
+- Locators as `private readonly` properties using `getByTestId()` or `locator()`
+- Expose locators to specs via getter methods (`getX(): Locator`) specs should not access private locators directly
+- Actions as `async` methods returning `Promise<void>`
+- Use `robustClick()` inside page objects for clicks; specs use plain `.click()`
+- Never prefix methods or locators with `legacy` name for what they do
+- Usually (always check this) Page Object methods accept human-readable identifiers (display names, resource names), not `Locator` objects from specs. If the page object owns full locator composition then take advantage of it.
+
+```typescript
+// WRONG: spec passes a Locator into page object
+const row = operatorsPage.getOperatorRow(displayName);
+await expect(operatorsPage.getStatus(row)).toContainText('Succeeded');
+
+// RIGHT: page object accepts a string identifier and composes the locator internally
+await expect(operatorsPage.getStatus(displayName)).toContainText('Succeeded');
+```
+
+```typescript
+import type { Locator } from "@playwright/test";
+import BasePage from "./base-page";
+
+export class ClusterSettingsPage extends BasePage {
+  private readonly detailsTab = this.page.getByTestId("horizontal-link-Details");
+  private readonly pageHeading = this.page.getByTestId("cluster-settings-page-heading");
+
+  async navigateToDetails(): Promise<void> {
+    await this.goTo("/settings/cluster");
+  }
+
+  getPageHeading(): Locator {
+    return this.pageHeading;
+  }
+}
+```
+
+---
+
+## Fixtures Guide
+
+**Do not maintain a static fixture inventory.** Instead read `frontend/e2e/fixtures/index.ts` and trace its imports to discover all available fixtures before writing a test. The fixture source files are the single source of truth.
+
+### Core Concepts
+
+- **`test` and `expect`** should always import from `e2e/fixtures`, NEVER from `@playwright/test`
+- **Worker-scoped fixtures** are shared across all tests in a worker (e.g., `k8sClient`, `testConfig`). Use for expensive resources.
+- **Test-scoped fixtures** are created fresh per test (e.g., `cleanup`, `page`). Use for per-test isolation.
+- **Fixture composition** fixtures can depend on other fixtures. Playwright resolves the dependency graph automatically.
+
+### Cleanup Pattern
+
+The `cleanup` fixture tracks Kubernetes resources created during a test and deletes them automatically after the test completes.
+
+```typescript
+test('creates a resource', async ({ page, cleanup, k8sClient }) => {
+  const ns = `test-${Date.now()}`;
+  await k8sClient.createNamespace(ns);
+  cleanup.trackNamespace(ns); // auto-deleted after test
+
+  // ... test logic. Cleanup runs automatically
+});
+```
+
+Track methods: `trackNamespace(name)`, `trackCustomResource(...)`, `trackClusterCustomResource(...)`, `track(resource)`.
+
+### Creating New Fixtures
+
+When adding a new fixture:
+
+1. Define it in `frontend/e2e/fixtures/index.ts` by extending the `test` object.
+2. Choose the right scope: `{ scope: 'worker' }` for shared expensive resources, `{ scope: 'test' }` for per-test isolation (default).
+3. Follow the existing patterns in the file. Use/teardown pairs for cleanup.
+4. Export the fixture from `index.ts` so tests can destructure it.
+
+---
+
+## Test Structure & Isolation
+
+### Isolation Strategies
+
+- **Strategy A: Fully Self-Contained (preferred)**
+
+Each test creates its resources, runs assertions, and cleans up.
+
+```typescript
+import { test, expect } from "../../fixtures";
+
+test.describe("Resource lifecycle", { tag: ["@admin"] }, () => {
+  test("verify resource details", async ({ page, cleanup, k8sClient }) => {
+    const ns = `test-${Date.now()}`;
+    await k8sClient.createNamespace(ns);
+    await k8sClient.waitForNamespaceReady(ns);
+    cleanup.trackNamespace(ns);
+
+    await test.step("Create resource", async () => { /* ... */ });
+    await test.step("Verify details", async () => { /* ... */ });
+  });
+});
+```
+
+Use when: tests are short enough that resource creation doesn't dominate runtime.
+
+- **Strategy B: Shared Resources via `test.describe`**
+
+When multiple tests need the same expensive resource:
+
+```typescript
+test.describe("Operator tests", { tag: ["@admin"] }, () => {
+  let namespace: string;
+
+  test.beforeAll(async ({ k8sClient }) => {
+    namespace = `aut-operator-${Date.now()}`;
+    await k8sClient.createNamespace(namespace);
+    await k8sClient.waitForNamespaceReady(namespace);
+  });
+
+  test.afterAll(async ({ k8sClient }) => {
+    await k8sClient.deleteNamespace(namespace);
+  });
+
+  test("verify installed", async ({ page }) => { /* ... */ });
+  test("create operand", async ({ page }) => { /* ... */ });
+});
+```
+
+Use when: multiple read-only tests share the same resource and creating it per-test would be too slow.
+
+**Strategy C: API-Created Resources**
+
+Use `k8sClient` in `test.beforeAll` to create resources via API (faster than UI), then run UI-only assertions in tests.
+
+### `test.step()` vs Separate `test()` Blocks
+
+- Use **`test.step()`** for sequential phases of a single workflow (create → configure → verify). Steps share state and if one fails, the whole test fails, which is correct when later steps depend on earlier ones.
+- Use **separate `test()` blocks** for independently valuable assertions that don't depend on each other.
+- The tradeoff is valid when independent scenarios share expensive setup (e.g., an installed operator or `page.route()` handler). If you choose steps over separate tests for this reason, document it in the test.
+
+### Serial vs Parallel Execution
+
+By default, tests within the same **file** run serially (`fullyParallel` is not set in `playwright.config.ts`). Tests across different files run in parallel across workers. Use `test.describe.configure({ mode: 'parallel' })` to override this within a describe block, but only when:
+
+- Tests are truly independent: no shared mutable state, no overlapping namespaces
+- Tests don't modify cluster-wide resources that could affect each other
+- Each test creates and cleans up its own resources
+
+**Do NOT use parallel mode** when:
+
+- Tests share a namespace created in `beforeAll`
+- Tests modify global cluster settings
+- Tests depend on a specific cluster state set by earlier tests
+
+```typescript
+// Parallel-safe: each test creates its own namespace
+test.describe("Independent CRUD tests", () => {
+  test.describe.configure({ mode: 'parallel' });
+
+  test("create configmap", async ({ page, cleanup, k8sClient }) => {
+    const ns = `test-cm-${Date.now()}`;
+    cleanup.trackNamespace(ns);
+    // ...
+  });
+
+  test("create secret", async ({ page, cleanup, k8sClient }) => {
+    const ns = `test-secret-${Date.now()}`;
+    cleanup.trackNamespace(ns);
+    // ...
+  });
+});
+```
+
+---
+
+## What to Test
+
+### Scoping Guidance
+
+- **One user workflow per `test()`**, e.g., "create a ConfigMap and verify it appears in the list"
+- **One feature area per `test.describe()`**, e.g., "ConfigMap CRUD operations"
+- **Golden path first.** The primary happy path a user would follow
+- **Edge cases on request.** Error states, empty states, boundary conditions only when explicitly asked
+
+### Tags
+
+Tags are optional. CI currently filters by Playwright **project** (`--project=smoke`, `--project=console`), not by `--grep @tag`. Many existing specs carry tags from Cypress/Gherkin migration (`@smoke`, `@regression`, `@admin`) but nothing in the pipeline consumes them.
+
+**Don't add tags by default.** Only add them if they enable filtering that the project/directory structure doesn't already provide, e.g., `@smoke` to mark a subset of tests within a large project for fast feedback, or a feature-specific tag like `@yaml-editor` when a directory has many specs and you want to run a subset.
+
+### Test Naming
+
+Name tests by the user intent being verified, not by the implementation:
+
+```typescript
+// Good
+test("creates a deployment with custom replicas")
+test("shows validation error for invalid port number")
+
+// Bad
+test("test1")
+test("click button and check text")
+```
+
+---
+
+## Auto-Awaiting & Waits
+
+Playwright action methods (`fill()`, `click()`, `check()`, `uncheck()`, `selectOption()`, `type()`, `press()`) **auto-wait for the element to be actionable** (visible, enabled, stable). `robustClick()` in page objects also auto-waits.
+
+```typescript
+// WRONG: redundant waitFor before an action
+await input.waitFor({ state: 'visible' });
+await input.fill('text');
+
+// RIGHT: actions auto-wait
+await input.fill('text');
+await this.robustClick(action);
+
+// RIGHT: custom timeout passed to the action
+await input.fill('text', { timeout: 10_000 });
+
+// RIGHT: waiting for state without acting (navigation confirmation, loading indicator)
+// eslint-disable-next-line no-restricted-syntax
+await page.getByTestId('loading-indicator').waitFor({ state: 'detached' });
+```
+
+Do NOT call `waitForLoadingComplete()` at the end of page object methods (e.g., after `selectProject()`). The caller's next action will auto-wait for whatever element it needs.
+
+> **ESLint enforcement:** The `no-restricted-syntax` rule (defined in `packages/eslint-plugin-console/lib/config/playwright.js`, scoped to `e2e/**/*` in `eslint.config.ts`) warns on `.waitFor()` calls. Legitimate uses need `// eslint-disable-next-line no-restricted-syntax`.
+
+### Condition-Based Waits
+
+Never use `page.waitForTimeout()`. Always wait for a condition:
+
+```typescript
+// NEVER
+await page.waitForTimeout(5000);
+
+// ALWAYS: condition-based assertion
+await expect(statusLocator).toContainText("Running", { timeout: 120_000 });
+
+// or polling-based condition
+await expect(async () => {
+  const text = await statusLocator.textContent();
+  expect(text).toContain("Running");
+}).toPass({ timeout: 120_000 });
+```
+
+---
+
+## Avoiding Flaky Tests
+
+Flaky tests erode trust in the test suite. These patterns prevent the most common sources of intermittent failures in this project.
+
+### Use `robustClick()` for clicks in page objects
+
+PatternFly overlays, dropdowns, and loading spinners can intercept clicks. `robustClick()` retries with scroll-into-view and falls back to force-click. Always use it inside page objects. Specs use plain `.click()` since the page object should have already handled the tricky interactions.
+
+### Wait for resources to be ready before navigating
+
+After creating a namespace or resource via `k8sClient`, don't navigate to its page immediately. The resource may not be fully initialized. Use `k8sClient.waitForNamespaceReady(ns)` or `k8sClient.waitForDeploymentReady(name, ns)` before navigating to UI pages that depend on the resource.
+
+```typescript
+await k8sClient.createNamespace(ns);
+await k8sClient.waitForNamespaceReady(ns);
+// now safe to navigate
+await page.goto(`/k8s/ns/${ns}/configmaps`);
+```
+
+### Handle post-save "Error loading" pages
+
+After a create/save that redirects to a details page, the page may intermittently show an error state ("Error loading [Resource]") with a "Try again" button. This happens because the K8s API hasn't fully propagated the resource. This is not a loading indicator; `waitForLoadingComplete()` won't help because the error page is a fully rendered state.
+
+Add a retry method to page objects that navigate to details pages after mutations:
+
+```typescript
+async waitForDetailsReady(contentLocator: Locator): Promise<void> {
+  await this.waitForLoadingComplete();
+  const tryAgain = this.page.getByRole('button', { name: 'Try again' });
+  for (let attempt = 0; attempt < 5; attempt++) {
+    // eslint-disable-next-line no-restricted-syntax
+    if (await tryAgain.waitFor({ state: 'visible', timeout: 2_000 }).then(() => true).catch(() => false)) {
+      await tryAgain.click();
+      await this.waitForLoadingComplete();
+      continue;
+    }
+    break;
+  }
+  await expect(contentLocator).toBeVisible({ timeout: 30_000 });
+}
+```
+
+### Prefer `data-test` over CSS class selectors
+
+CSS classes change across PatternFly versions (e.g., `.pf-v5-c-button` to `.pf-v6-c-button`). `data-test` attributes are stable. When a test relies on a CSS class for selection, check if a `data-test` attribute exists or can be added.
+
+### Don't assert before loading completes
+
+If a page has loading indicators, wait for them to clear before asserting on content. Use `waitForLoadingComplete()` only when you need to confirm loading finished without acting on an element. For actions (`click`, `fill`), Playwright auto-waits.
+
+```typescript
+// WRONG: assert while page might still be loading
+await expect(page.getByTestId('resource-title')).toHaveText('my-app');
+
+// RIGHT: navigate, then let the assertion's built-in retry handle timing
+const details = new DetailsPage(page);
+await details.goTo(`/k8s/ns/${ns}/deployments/my-app`);
+await expect(details.title).toHaveText('my-app', { timeout: 30_000 });
+```
+
+### Use unique resource names per test
+
+Append `Date.now()` or a unique suffix to namespace and resource names. Tests running in parallel across workers must not collide on resource names.
+
+### Run tests 3 times before declaring them stable
+
+A test that passes once may be flaky. suggest user to run with `--retries=0` at least three consecutive times. If it fails on any run, it has a timing or state issue that needs fixing.
+
+---
+
+## k8sClient & Cleanup Patterns
+
+### All cluster interactions use `k8sClient`
+
+Never use shell commands (`execSync`, `child_process`) when `k8sClient` has a method. Destructure `k8sClient` from test fixtures.
+
+### `afterAll` must destructure fixtures
+
+Always destructure fixtures directly in `test.afterAll` parameters. Never assign fixtures to closure variables in `beforeAll` and reference them in `afterAll`. The closure pattern bypasses Playwright's lifecycle and silently skips cleanup if setup fails.
+
+```typescript
+// WRONG: closure variable, silently skips cleanup if beforeAll failed
+let k8sClient: KubernetesClient;
+test.beforeAll(async ({ k8sClient: client }) => { k8sClient = client; });
+test.afterAll(async () => {
+  if (!k8sClient) return;
+  await k8sClient.deleteNamespace(ns);
+});
+
+// RIGHT: fixture parameter, Playwright manages lifecycle
+test.afterAll(async ({ k8sClient }) => {
+  await k8sClient.deleteNamespace(ns);
+});
+```
+
+### Cleanup methods swallow 404s
+
+`deleteNamespace()`, `deleteCustomResource()`, and `deleteClusterCustomResource()` catch errors and silently swallow 404 "not found" responses. Do NOT wrap cleanup calls in try/catch.
+
+However, when multiple independent deletions must all run, use `Promise.allSettled`. This is about non-404 errors: if a subscription delete throws a 500, you still want CSV cleanup to run.
+
+```typescript
+// WRONG: if first delete throws 500, remaining cleanup is skipped
+test.afterAll(async ({ k8sClient }) => {
+  await k8sClient.deleteCustomResource(gvk, ns, 'subscriptions', subName);
+  const csvs = await k8sClient.listCustomResources(gvk, ns, 'clusterserviceversions');
+  for (const csv of csvs) { await k8sClient.deleteCustomResource(gvk, ns, 'clusterserviceversions', csv.metadata.name); }
+});
+
+// RIGHT: list first (read-only), then fire all deletions independently
+test.afterAll(async ({ k8sClient }) => {
+  const csvs = await k8sClient.listCustomResources(gvk, ns, 'clusterserviceversions');
+  await Promise.allSettled([
+    k8sClient.deleteCustomResource(gvk, ns, 'subscriptions', subName),
+    ...csvs.map(c =>
+      k8sClient.deleteCustomResource(gvk, ns, 'clusterserviceversions', c.metadata.name),
+    ),
+  ]);
+});
+```
+
+---
+
+## Mocking with `page.route()`
+
+When a test verifies multiple mock scenarios (e.g., compatible, incompatible, error), register the route handler once and swap data via a mutable reference. This avoids re-registering routes between steps.
+
+```typescript
+let activeMockData: MockType | null = null;
+
+await page.route('**/api/endpoint/**', async (route) => {
+  if (activeMockData) {
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify(activeMockData),
+    });
+  } else {
+    await route.abort();
+  }
+});
+
+await test.step('Scenario A', async () => {
+  activeMockData = makeScenarioA();
+  await page.reload();
+  // assert...
+});
+
+await test.step('Scenario B', async () => {
+  activeMockData = makeScenarioB();
+  await page.reload();
+  // assert...
+});
+```
+
+---
+
+## Feature Gates & Platform Guards
+
+### Feature gate skip
+
+Tests that require a specific feature gate should read `SERVER_FLAGS` from the browser and skip if the gate is disabled. This must happen after navigation (so the page has loaded) but before assertions.
+
+```typescript
+const serverFlags = await page.evaluate(() => (window as any).SERVER_FLAGS ?? {});
+test.skip(
+  !serverFlags.someFeatureFlag,
+  'Test requires the SomeFeature feature gate to be enabled',
+);
+```
+
+### MicroShift guard
+
+Tests using OLM APIs (`operators.coreos.com`) must skip on MicroShift clusters since these APIs are not available there. Use an API group availability check or tag with `[Skipped:MicroShift]`.
+
+### No silent fallbacks in setup
+
+If a test derives a value from the cluster (version, feature flag, resource name), it must fail explicitly when the value cannot be derived. Silent defaults produce misleading assertion failures downstream.
+
+```typescript
+// WRONG: silent fallback masks real problem
+const versionMatch = releaseVersion.match(/^(\d+\.\d+)/);
+const clusterMinorVersion = versionMatch ? versionMatch[1] : '4.18';
+
+// RIGHT: fail fast with clear error
+const versionMatch = releaseVersion.match(/^(\d+\.\d+)/);
+if (!versionMatch) {
+  throw new Error(`Unable to parse cluster minor version from: "${releaseVersion}"`);
+}
+const clusterMinorVersion = versionMatch[1];
+```
+
+---
+
+## Playwright MCP & Self-Signed Certificates
+
+OpenShift clusters use self-signed certificates. `browser_navigate` will fail with `ERR_CERT_AUTHORITY_INVALID`.
+
+**Workaround:** Use `browser_run_code_unsafe` to create a context with `ignoreHTTPSErrors: true`:
+
+```javascript
+async (page) => {
+  const browser = page.context().browser();
+  const ctx = await browser.newContext({ ignoreHTTPSErrors: true });
+  try {
+    const p = await ctx.newPage();
+    await p.goto('https://console-openshift-console.apps.<cluster>/');
+    // interact with p, not the MCP's tracked page
+  } finally {
+    await ctx.close();
+  }
+}
+```
+
+The MCP's tracked page stays on `about:blank`. Use the `p` reference from the new context for all interactions. Login via the OAuth form if needed (fill `#inputUsername`, `#inputPassword`, submit).
+
+---
+
+## Validation Commands
+
+```bash
+# Type checking (from frontend/)
+npx tsc --noEmit -p e2e/tsconfig.json
+
+# Linting (from frontend/)
+cd frontend && yarn eslint <file-paths>
+
+# Run tests (from frontend/)
+npx playwright test --project=<package> <spec-file> --retries=0
+
+# Run developer tests (from frontend/)
+npx playwright test --project=<package>-developer <spec-file> --retries=0
+```
+
+---
+
+## Things to NEVER Do
+
+- **Never import `test` or `expect` from `@playwright/test`** . Import from `e2e/fixtures`
+- **Never use `page.waitForTimeout()`**. Find the condition to wait for
+- **Never add `waitFor()` before an action**. `fill()`, `click()`, `check()` auto-wait for actionability
+- **Never use legacy test attribute selectors** (`[data-test-id="..."]`, `[data-test-rows="..."]`). Add `data-test` to the React source and use `getByTestId()`
+- **Never wrap k8sClient cleanup in try/catch**. Delete methods already swallow 404s. Use `Promise.allSettled` when multiple independent deletions must all run
+- **Never assign fixtures to closure variables**. Destructure them directly in `test.afterAll`/`test.beforeAll` parameters
+- **Never pass `Locator` objects from specs into page object  if the method accept the identifier**. Pass string identifiers; the page object composes locators internally
+- **Never use silent fallbacks for derived values**. If a test derives data from the cluster (version, feature flag), fail explicitly when the value cannot be parsed
+- **Never prefix methods with `legacy`**. Name for what they do
+- **Never put locators in spec files** when a page object exists or should exist
+- **Never rely on test order**. Each `test()` must work independently
+- **Never skip cleanup**. Every created resource must be tracked with `cleanup.track*()`
+- **Never use shell commands** (`execSync`, `child_process`) when `k8sClient` has a method
diff --git a/.claude/migration-context.md b/.claude/migration-context.md
index 0ee0ecb8f18..f9febb41c12 100644
--- a/.claude/migration-context.md
+++ b/.claude/migration-context.md
@@ -1,36 +1,13 @@
 # Cypress → Playwright Migration Context
 
-Shared reference for migrating Console's Cypress e2e tests to Playwright. Used by `/migrate-cypress` and `/debug-test` skills. Adapted from [openshift-ui-tests-template cypress-migrator.mdc](https://github.com/bmaio-redhat/openshift-ui-tests-template/blob/main/.cursor/rules/cypress-migrator.mdc).
+Migration-specific reference for translating Cypress and Gherkin tests to Playwright. For universal Playwright patterns (page objects, selectors, fixtures, cleanup, waits), see `e2e-context.md`.
 
-## High-Level Principles
+## Migration Principles
 
-1. **Understand, then rewrite.** Read the Cypress test to extract the _intent_ (what user workflow is being verified), then implement that intent using idiomatic Playwright patterns.
-2. **Self-contained tests.** Each `test()` block must create its own resources, assert independently, and clean up after itself. Never rely on test execution order or shared mutable state across `it` blocks.
-3. **Use the most specific API.** Prefer Playwright's built-in locator methods (`getByRole`, `getByTestId`, `getByText`, `getByLabel`) over generic `page.locator()` when they improve readability. Use `page.locator('[data-test="..."]')` for custom test attributes.
-4. **Leverage the framework.** Use existing page objects, and clients. Create new ones only when needed — always search first.
-5. **Live verification.** Use Playwright MCP browser tools to verify selectors, navigation flows, and element presence against the live UI before finalizing code.
-
-## Test Selectors
-
-Config: `testIdAttribute: 'data-test'` in `frontend/playwright.config.ts` (from root of the project) so `page.getByTestId('x')` queries `[data-test="x"]`.
-
-**Always use `page.getByTestId('x')`** for element selection. If a React element only has a legacy test attribute (`data-test-id`, `data-test-selector`, `data-test-action`, `data-test-dropdown-menu`, etc.) but no `data-test`, **add `data-test="<value>"` to the React component source** so `page.getByTestId()` can be used. Never remove legacy `data-test-*` attributes — external consumers may depend on them.
-
-### How to add `data-test` during migration
-
-When migrating a Cypress test that uses `cy.get('[data-test-id="x"]')` or `cy.byLegacyTestID('x')`:
-
-1. Find the React component that renders the element with `data-test-id="x"`.
-2. Add `data-test="x"` alongside the existing `data-test-id="x"`.
-3. In the Playwright page object, use `this.page.getByTestId('x')` instead of `this.page.locator('[data-test-id="x"]')`.
-
-```tsx
-// Before (React component)
-<div data-test-id="horizontal-link-Details">Details</div>
-
-// After — data-test added, data-test-id preserved
-<div data-test="horizontal-link-Details" data-test-id="horizontal-link-Details">Details</div>
-```
+1. **Understand, then rewrite.** Read the Cypress test to extract the _intent_ (what user workflow is being verified), then implement that intent using idiomatic Playwright patterns. Never transliterate line-by-line. `cy.get(x).click()` → `page.locator(x).click()` is not a migration.
+2. **Know how Cypress works.** Cypress tests run in the browser with automatic retry and implicit waits. `testIsolation: false` means sequential `it` blocks share browser state: the page, cookies, and DOM persist between blocks. Playwright isolates each `test()` by default, so sequential `it` blocks that depend on shared state must be merged into a single `test()` with `test.step()` blocks.
+3. **Cypress hooks create shared mutable state.** `before()` runs once and sets up state (resources, navigation) that all `it` blocks inherit. `beforeEach()` runs before every block. In Playwright, this shared state doesn't carry over between `test()` blocks, so hook logic must move into each test or into `test.beforeAll`/`test.beforeEach` with explicit fixture usage.
+4. **Cypress custom commands are global.** Commands like `cy.login()`, `cy.createProject()`, `cy.visitAndWait()` are registered globally via `Cypress.Commands.add()`. In Playwright, these become page object methods, fixture utilities, or setup functions. There is no global command registry.
 
 ---
 
@@ -63,7 +40,7 @@ When migrating a Cypress test that uses `cy.get('[data-test-id="x"]')` or `cy.by
 | `cy.get(s).check()`                | `await this.page.locator(s).check()`                                                                |
 | `cy.get(s).uncheck()`              | `await this.page.locator(s).uncheck()`                                                              |
 | `cy.get(s).scrollIntoView()`       | `await this.page.locator(s).scrollIntoViewIfNeeded()`                                               |
-| `cy.get(s).within(() => { ... })`  | `const container = this.page.locator(s); container.locator(child)` — scope via chained `.locator()` |
+| `cy.get(s).within(() => { ... })`  | `const container = this.page.locator(s); container.locator(child)`. Scope via chained `.locator()` |
 | `cy.get('input').attachFile(f)`    | `await this.page.locator('input[type="file"]').setInputFiles(f)`                                    |
 | `cy.dropFile(selector, file)`      | `await this.page.locator(selector).setInputFiles(filePath)`                                         |
 
@@ -97,10 +74,10 @@ When migrating a Cypress test that uses `cy.get('[data-test-id="x"]')` or `cy.by
 
 | Cypress                                                  | Playwright                                                                                                                                                |
 | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cy.wait(3000)`                                          | **AVOID.** Use `await expect(locator).toBeVisible()` or condition-based waits. Only use `page.waitForTimeout()` as absolute last resort during debugging. |
-| `cy.get(s, { timeout }).click()`                         | `await locator.click({ timeout })` — pass timeout to the action, not a separate `waitFor()`. All Playwright actions accept a `timeout` option             |
-| `cy.get(s, { timeout }).should('be.visible')`            | `await expect(locator).toBeVisible({ timeout })` — pass timeout to the assertion                                                                          |
-| `cy.get(s, { timeout })` (no action, just waiting)       | `await locator.waitFor({ state: 'visible', timeout })` — only when no action or assertion follows                                                         |
+| `cy.wait(3000)`                                          | **AVOID.** Use `await expect(locator).toBeVisible()` or condition-based waits. See `e2e-context.md` Auto-Awaiting section.                                |
+| `cy.get(s, { timeout }).click()`                         | `await locator.click({ timeout })`. Pass timeout to the action                                                                                          |
+| `cy.get(s, { timeout }).should('be.visible')`            | `await expect(locator).toBeVisible({ timeout })`. Pass timeout to the assertion                                                                          |
+| `cy.get(s, { timeout })` (no action, just waiting)       | `await expect(locator).toBeVisible({ timeout })`. Prefer assertion over `waitFor()` to avoid the `no-restricted-syntax` ESLint rule. Use `locator.waitFor()` with `// eslint-disable-next-line no-restricted-syntax` only for non-visible states like `'detached'` or `'hidden'` |
 | `cy.contains(text, { timeout })`                         | `await expect(page.getByText(text)).toBeVisible({ timeout })` or `await page.getByText(text).click({ timeout })` depending on what follows                |
 | `cy.intercept('GET', url).as('req')` + `cy.wait('@req')` | `await this.page.waitForResponse(url)` or `page.waitForResponse(resp => resp.url().includes(url))`                                                        |
 
@@ -113,7 +90,7 @@ When migrating a Cypress test that uses `cy.get('[data-test-id="x"]')` or `cy.by
 | `cy.exec('oc get ... -o jsonpath')`          | `k8sClient.getCustomResource(...)`                                  |
 | `cy.exec('oc patch ...')`                    | `k8sClient.patchConfigMap(...)` or equivalent K8s API method        |
 | `cy.create(resourceJSON)`                    | `k8sClient.createCustomResource(...)`                               |
-| `cy.deleteProject(name)`                     | `cleanup.trackNamespace(name)` — registers for auto-deletion after test |
+| `cy.deleteProject(name)`                     | `await k8sClient.deleteNamespace(name)`. For explicit deletion. Track namespaces at creation time with `cleanup.trackNamespace(name)` |
 | `cy.resourceShouldBeDeleted(ns, kind, name)` | `k8sClient.getCustomResource(...)` should throw 404                 |
 
 ### Conditional Logic
@@ -124,15 +101,28 @@ When migrating a Cypress test that uses `cy.get('[data-test-id="x"]')` or `cy.by
 | `cy.get(s).then($el => { ... })`                                      | `const text = await this.page.locator(s).textContent()` |
 | Multiple `.then()` chains                                             | Sequential `await` statements                           |
 
+### Custom Commands
+
+| Cypress custom command                                     | Playwright equivalent                                                     |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `cy.login()`                                               | `storageState`. Zero code in tests                                       |
+| `cy.initAdmin()`                                           | Admin project `storageState`                                              |
+| `cy.visitAndWait(url)`                                     | `pageObject.goTo(url)`                                                    |
+| `cy.clickNavLink([...])`                                   | `navPage.clickNavLink(...)`                                               |
+| `cy.createProject(name)` / `cy.createProjectWithCLI(name)` | `k8sClient.createNamespace(name)` + `cleanup.trackNamespace(name)`       |
+| `cy.deleteProject(name)` / `cy.deleteProjectWithCLI(name)` | `await k8sClient.deleteNamespace(name)`. Track at creation with `cleanup.trackNamespace(name)` |
+| `cy.resourceShouldBeDeleted(ns, kind, name)`               | `await k8sClient.getCustomResource(...)` should throw                    |
+| `checkErrors()`                                            | Not needed. Playwright catches uncaught exceptions                       |
+
 ---
 
 ## Structural Transformation Rules
 
-### Rule 1: Flatten Sequential `it` Blocks into Self-Contained Tests
+### Rule 1: Flatten Sequential `it` Blocks
 
 Cypress `testIsolation: false` means `it` blocks share browser state. In Playwright, each `test()` is isolated.
 
-**Cypress pattern (anti-pattern for Playwright):**
+**Cypress pattern (recognize and transform):**
 
 ```typescript
 describe("Resource lifecycle", () => {
@@ -155,7 +145,7 @@ describe("Resource lifecycle", () => {
 });
 ```
 
-**Playwright equivalent:**
+**Playwright equivalent** . merge into one `test()` with `test.step()`, use `cleanup` fixture:
 
 ```typescript
 import { test, expect } from "../../fixtures";
@@ -163,43 +153,32 @@ import { test, expect } from "../../fixtures";
 test.describe("Resource lifecycle", { tag: ["@admin"] }, () => {
   test("verify resource details after creation", async ({ page, cleanup, k8sClient }) => {
     const ns = `test-${Date.now()}`;
+    await k8sClient.createNamespace(ns);
+    cleanup.trackNamespace(ns);
 
     await test.step("Create resource", async () => {
-      await k8sClient.createNamespace(ns);
-      cleanup.trackNamespace(ns);
       // create resource via API or UI
     });
 
     await test.step("Verify details", async () => {
       const details = new DetailsPage(page);
       await details.navigateTo(`/k8s/ns/${ns}/deployments/my-app`);
-      await expect(details.title).toContainText("my-app");
+      await expect(details.getTitle()).toContainText("my-app");
     });
     // cleanup runs automatically after test
   });
 });
 ```
 
-### Rule 2: Replace `before`/`after` Hooks with `test.step` Blocks and `cleanup`
+### Rule 2: Replace `before`/`after` Hooks
 
-Cypress hooks that create resources become explicit `test.step` blocks within each test. Resource cleanup is handled by the `cleanup` fixture — track resources with `cleanup.track*()` and they are deleted automatically after the test.
+Dependent sequential `it` blocks that share state become one `test()` with `test.step()` blocks. Per-test resource cleanup uses `cleanup.track*()`. When using Strategy B (shared expensive resources), `test.beforeAll`/`test.afterAll` are acceptable for namespace creation and teardown.
 
-**Exception:** `test.beforeEach` for login is acceptable when ALL tests in a describe need the same login. Prefer the `storageState` mechanism from global setup.
+**Exception:** `test.beforeEach` for login is acceptable when ALL tests in a describe need the same login. However, prefer the `storageState` mechanism from global setup. `cy.login()` maps to zero test-level code via stored auth state (see Custom Commands table).
 
 ### Rule 3: Replace Custom Commands with Page Object Methods
 
-Every `cy.customCommand()` maps to a page object method. Tests call page objects directly.
-
-| Cypress custom command                                     | Playwright equivalent                                                     |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `cy.login()`                                               | `storageState` — zero code in tests                                       |
-| `cy.initAdmin()`                                           | Admin project `storageState`                                              |
-| `cy.visitAndWait(url)`                                     | `pageObject.goTo(url)`                                                    |
-| `cy.clickNavLink([...])`                                   | `navPage.clickNavLink(...)`                                               |
-| `cy.createProject(name)` / `cy.createProjectWithCLI(name)` | `k8sClient.createNamespace(name)` + `cleanup.trackNamespace(name)` |
-| `cy.deleteProject(name)` / `cy.deleteProjectWithCLI(name)` | `cleanup.trackNamespace(name)` — registers for auto-deletion after test  |
-| `cy.resourceShouldBeDeleted(ns, kind, name)`               | `await k8sClient.getCustomResource(...)` should throw                    |
-| `checkErrors()`                                            | Not needed — Playwright catches uncaught exceptions                       |
+Every `cy.customCommand()` maps to a page object method. See the Custom Commands table above.
 
 ### Rule 4: Replace Fixed Waits with Condition-Based Waits
 
@@ -216,15 +195,17 @@ await expect(async () => {
 }).toPass({ timeout: 120_000 });
 ```
 
-### Rule 5: Replace `cy.exec('oc ...')` with `k8sClient` Fixture
+See `e2e-context.md` Auto-Awaiting section for full details.
 
-All cluster interactions go through the `k8sClient` fixture (an instance of `KubernetesClient` injected per-worker) — never shell commands in tests.
+### Rule 5: Replace `cy.exec('oc ...')` with `k8sClient`
+
+All cluster interactions go through the `k8sClient` fixture. Never shell commands in tests.
 
 ```typescript
 // NEVER
 cy.exec("oc delete deployment test-app -n test-ns");
 
-// ALWAYS — destructure k8sClient from the test fixtures
+// ALWAYS: destructure k8sClient from the test fixtures
 test('deletes resource', async ({ page, cleanup, k8sClient }) => {
   await k8sClient.deleteCustomResource(
     "apps",
@@ -274,90 +255,7 @@ async dismissWelcomeIfPresent(): Promise<void> {
 
 ### Rule 8: Map Cypress Retries to Playwright Retries
 
-Cypress per-test `retries: { runMode: N }` becomes Playwright `test.describe.configure({ retries: N })` or is left to the global config. Never use per-test retries to mask flaky selectors — fix the root cause.
-
----
-
-## Test Isolation Strategies
-
-### Strategy A: Fully Self-Contained (preferred)
-
-Each test creates its resources, runs assertions, and cleans up — even if the Cypress source had a shared `before` hook creating resources for multiple `it` blocks.
-
-Use when: tests are short enough that resource creation doesn't dominate runtime.
-
-### Strategy B: Shared Resources via `test.describe` Setup
-
-When multiple tests need the same expensive resource (e.g., an installed operator):
-
-```typescript
-import { test, expect } from "../../fixtures";
-
-test.describe("Operator tests", { tag: ["@admin"] }, () => {
-  let namespace: string;
-
-  test.beforeAll(async ({ k8sClient }) => {
-    namespace = `aut-operator-${Date.now()}`;
-    await k8sClient.createNamespace(namespace);
-    // install operator or create expensive resource
-  });
-
-  test.afterAll(async ({ k8sClient }) => {
-    await k8sClient.deleteNamespace(namespace);
-  });
-
-  test("verify operator installed", async ({ page }) => {
-    /* ... */
-  });
-  test("create operand", async ({ page }) => {
-    /* ... */
-  });
-});
-```
-
-Use when: multiple read-only tests share the same resource and creating it per-test would be too slow.
-
-### Strategy C: API-Created Resources
-
-Use `KubernetesClient` in `test.beforeAll` to create resources via API (faster than UI creation), then run UI-only assertions in tests.
-
----
-
-## Page Object Pattern
-
-- Extend `BasePage` (provides `robustClick()`, `waitForLoadingComplete()`, `goTo()`, `navigateToTab()`, `clickButtonByText()`, `switchPerspective()`)
-- Locators as `private readonly` properties. Use `getByTestId()` for `data-test` attributes, `locator()` for other selectors
-- Expose locators to specs via getter methods (e.g., `getPageHeading(): Locator`) — specs should not access private locators directly
-- Actions as `async` methods returning `Promise<void>`
-- Use `robustClick()` inside page objects for clicks intercepted by PatternFly overlays; specs use plain `.click()`
-- Locator priority: `getByTestId` > `getByRole` > `getByText` > `locator`
-
-e.g.
-
-```typescript
-// e2e/pages/cluster-settings.ts
-import type { Locator } from "@playwright/test";
-import BasePage from "./base-page";
-
-export class ClusterSettingsPage extends BasePage {
-  private readonly detailsTab = this.page.getByTestId("horizontal-link-Details");
-  private readonly pageHeading = this.page.getByTestId("cluster-settings-page-heading");
-  private readonly upstreamServerUrl = this.page.getByTestId("cv-upstream-server-url");
-
-  async navigateToDetails(): Promise<void> {
-    await this.goTo("/settings/cluster");
-    await this.detailsTab.waitFor({ state: "visible" });
-  }
-
-  getPageHeading(): Locator {
-    return this.pageHeading;
-  }
-
-  async clickUpstreamServerUrl(): Promise<void> {
-    await this.robustClick(this.upstreamServerUrl);
-  }
-}
-```
+Cypress per-test `retries: { runMode: N }` becomes Playwright `test.describe.configure({ retries: N })` or is left to the global config. Never use per-test retries to mask flaky selectors. Fix the root cause.
 
 ---
 
@@ -388,7 +286,7 @@ Gherkin's 4-file indirection collapses to 2 files:
 | Cypress source                                                      | Playwright target                                                  |
 | ------------------------------------------------------------------- | ------------------------------------------------------------------ |
 | `packages/integration-tests/support/selectors.ts`                   | `BasePage` utilities and page object locators                      |
-| `packages/integration-tests/support/login.ts`                       | Global setup `storageState` — no test-level code                   |
+| `packages/integration-tests/support/login.ts`                       | Global setup `storageState`. No test-level code                   |
 | `packages/integration-tests/support/nav.ts`                         | `navigate*` methods on page objects                                |
 | `packages/integration-tests/support/project.ts`                     | `KubernetesClient` namespace methods + `cleanup` fixture           |
 | `packages/integration-tests/views/list-page.ts`                     | `e2e/pages/list-page.ts` (page object class)                       |
@@ -411,128 +309,12 @@ For each Cypress file being migrated:
 - [ ] Read the entire Cypress test file and all imported views/constants/support
 - [ ] Document each `it` block's intent in plain language
 - [ ] Search existing page objects in `e2e/pages/` for reusable methods
-- [ ] Identify test isolation strategy (A, B, or C)
-- [ ] Add `data-test` attributes to React components that only have legacy test attributes (`data-test-id`, etc.)
+- [ ] Identify test isolation strategy (A, B, or C, see `e2e-context.md`)
+- [ ] Add `data-test` attributes to React components that only have legacy test attributes
 - [ ] Create/extend page objects with `getByTestId()` locators and methods
 - [ ] Write the spec file using project template
 - [ ] Replace all `cy.wait()` with condition-based waits
 - [ ] Replace all `cy.exec('oc ...')` with KubernetesClient calls
-- [ ] Run `npx tsc --noEmit` — zero errors
-- [ ] Run tests with `PLAYWRIGHT_RETRIES=0` — passing
+- [ ] Run `cd frontend && npx tsc --noEmit -p e2e/tsconfig.json`. Zero errors
+- [ ] Run tests with `--retries=0`. Passing
 - [ ] Verify no orphaned resources after test run
-
-## Playwright MCP and Self-Signed Certificates
-
-OpenShift clusters use self-signed certificates. Both `browser_navigate` (Playwright MCP) and `navigate_page` (Chrome DevTools MCP) will fail with `ERR_CERT_AUTHORITY_INVALID`.
-
-**Workaround:** Use `browser_run_code_unsafe` to create a new browser context with `ignoreHTTPSErrors: true`:
-
-```javascript
-async (page) => {
-  const browser = page.context().browser();
-  const ctx = await browser.newContext({ ignoreHTTPSErrors: true });
-  const p = await ctx.newPage();
-  await p.goto('https://console-openshift-console.apps.<cluster>/');
-  // ... interact with p for selector verification
-}
-```
-
-The MCP's tracked page stays on `about:blank` — use the `p` reference from the new context for all interactions. Login via the OAuth form if needed (fill `#inputUsername`, `#inputPassword`, submit).
-
----
-
-## Playwright Auto-Awaiting
-
-Playwright action methods (`fill()`, `click()`, `check()`, `uncheck()`, `selectOption()`, `type()`, `press()`) **auto-wait for the element to be actionable** (visible, enabled, stable). You do NOT need an explicit `waitFor()` before calling these actions. This includes `robustClick()` in page objects — it also auto-waits.
-
-> **ESLint enforcement:** The `no-restricted-syntax` rule in `e2e/.eslintrc.cjs` warns on all `.waitFor()` calls. Legitimate uses must have `// eslint-disable-next-line no-restricted-syntax`. This catches redundant `waitFor()` at lint time — `yarn eslint` will flag new violations.
-
-
-```typescript
-// WRONG — redundant waitFor before an action
-await input.waitFor({ state: 'visible' });
-await input.fill('text');
-
-// WRONG — redundant waitFor before robustClick
-await action.waitFor({ state: 'visible', timeout: 10_000 });
-await this.robustClick(action);
-
-// RIGHT — actions auto-wait for actionability
-await input.fill('text');
-await this.robustClick(action);
-
-// RIGHT — if you need a custom timeout, pass it to the action
-await input.fill('text', { timeout: 10_000 });
-await action.click({ timeout: 10_000 });
-```
-
-Only use explicit `waitFor()` when you need to wait for an element **without acting on it** — e.g., confirming navigation completed, or waiting for loading indicators to disappear:
-
-```typescript
-// OK — waiting for a state transition, not an action
-await page.getByTestId('loading-indicator').waitFor({ state: 'detached' });
-
-// OK — confirming the editor loaded before reading its content (not an action on the element)
-await page.getByTestId('code-editor').waitFor({ state: 'visible' });
-```
-
-Similarly, `waitForLoadingComplete()` should not be called at the end of page object methods like `selectProject()`. The caller's next action will auto-wait for whatever element it needs.
-
----
-
-## Adding `data-test` Attributes
-
-When migrating selectors, **always check the React source** for existing `data-test` attributes before creating locators:
-
-1. **If `data-test` already exists** on the element → use `getByTestId('value')` directly.
-2. **If only a legacy attribute exists** (`data-test-id`, `data-test-rows`, `data-test-dropdown-menu`, `data-test-action`, etc.) → add `data-test="value"` to the React component source alongside the existing legacy attribute, then use `getByTestId('value')`.
-3. **Never use legacy attribute selectors** like `page.locator('[data-test-rows="..."]')` or `page.locator('[data-test-dropdown-menu="..."]')` when `data-test` exists or can be added.
-
-```typescript
-// WRONG — using legacy selector directly
-private readonly resourceRows = this.page.locator('[data-test-rows="resource-row"]');
-
-// RIGHT — data-test="resource-row" already exists on the same element
-private readonly resourceRows = this.page.getByTestId('resource-row');
-```
-
----
-
-## k8sClient Cleanup
-
-`KubernetesClient.deleteNamespace()`, `KubernetesClient.deleteCustomResource()`, and `KubernetesClient.deleteClusterCustomResource()` catch errors and call `isNotFound(err)` to silently swallow 404 "not found" responses. Do NOT wrap these cleanup calls in try/catch blocks.
-
-```typescript
-// WRONG — unnecessary error handling
-test.afterAll(async ({ k8sClient }) => {
-  try { await k8sClient.deleteNamespace(namespace); } catch { /* may already be deleted */ }
-});
-
-// RIGHT — k8sClient handles 404 silently
-test.afterAll(async ({ k8sClient }) => {
-  await k8sClient.deleteNamespace(namespace);
-});
-```
-
----
-
-## Page Object Naming
-
-- Do NOT prefix methods or locators with `legacy`. If a locator targets an older DOM structure that will be replaced, name it for what it does, not its age (e.g., `filterByNameInput` not `legacyFilterByName`).
-- Common actions (navigate to form, click create dropdown item, filter + select) should be page object methods, not inline locator chains in spec files.
-
----
-
-## Things to NEVER Do
-
-- **Never import `test` or `expect` from `@playwright/test`** — import from `e2e/fixtures`
-- **Never transliterate** — `cy.get(x).click()` → `page.locator(x).click()` is not a migration. Understand intent, use idiomatic Playwright APIs
-- **Never use `page.waitForTimeout()`** as a replacement for `cy.wait()`. Find the condition to wait for
-- **Never add `waitFor()` before an action** — `fill()`, `click()`, `check()`, etc. already auto-wait for actionability
-- **Never use legacy test attribute selectors** (`[data-test-rows="..."]`, `[data-test-id="..."]`, `[data-test-dropdown-menu="..."]`) — add `data-test` to the React source and use `getByTestId()`
-- **Never wrap k8sClient cleanup in try/catch** — `deleteNamespace`, `deleteCustomResource`, and `deleteClusterCustomResource` already swallow 404s
-- **Never prefix methods with `legacy`** — name for what it does, not its age
-- **Never put locators in spec files** when a page object exists or should exist
-- **Never rely on test order** — each `test()` must work independently.
-- **Never skip cleanup** — every created resource must be tracked with `cleanup.track*()`
-- **Never use shell commands** (`execSync`, `child_process`) when `KubernetesClient` has a method
diff --git a/.claude/skills/debug-test/SKILL.md b/.claude/skills/debug-test/SKILL.md
index 88288325e38..3d57b455492 100644
--- a/.claude/skills/debug-test/SKILL.md
+++ b/.claude/skills/debug-test/SKILL.md
@@ -2,7 +2,7 @@
 name: debug-test
 description: Debug and fix failing Playwright e2e tests with MCP-assisted diagnosis. Use when user says "playwright test failing", "fix e2e test", "debug spec", or provides a failing .spec.ts file, e2e directory, or Playwright tag.
 argument-hint: "<path/to/file.spec.ts | directory/ | @tag>"
-allowed-tools: Read, Write, Edit, Bash(find *), Bash(grep *), Bash(ls *), Bash(npx tsc *), Bash(npx playwright *), Bash(git diff *), Bash(git status), mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_click, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_run_code_unsafe, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_close, mcp__plugin_playwright_playwright__browser_type, mcp__plugin_playwright_playwright__browser_wait_for, mcp__plugin_playwright_playwright__browser_network_requests, AskUserQuestion
+allowed-tools: Read, Write, Edit, Agent, Bash(find *), Bash(grep *), Bash(ls *), Bash(npx tsc *), Bash(npx playwright *), Bash(git diff *), Bash(git status), mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_click, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_run_code_unsafe, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_close, mcp__plugin_playwright_playwright__browser_type, mcp__plugin_playwright_playwright__browser_wait_for, mcp__plugin_playwright_playwright__browser_network_requests, AskUserQuestion
 ---
 
 # Debug Test
@@ -12,7 +12,7 @@ Debug and fix failing Playwright tests using MCP as the primary diagnostic tool.
 ## Before Starting
 
 1. Check that `frontend/e2e/.env` exists. If missing, copy `frontend/e2e/.env.example` to `frontend/e2e/.env` and tell the user to fill in their cluster values before continuing.
-2. Read `.claude/migration-context.md` for the Console architecture, selector mappings, and migration rules. That file is the single source of truth for how Playwright tests should be structured.
+2. Read `.claude/e2e-context.md` for project conventions, patterns, and rules — page objects, selectors, fixtures, cleanup, waits, and things to never do. That file is the single source of truth for how Playwright tests should be structured.
 
 ## Input
 
@@ -87,6 +87,34 @@ Debug Summary: <target>
     - <file>: <reason>
 ```
 
+### Phase 5: What We Learned
+
+After the fix is validated (Phase 4 passes), evaluate whether the root cause reveals a gap in the shared knowledge files. Most failures are one-off test bugs (wrong selector, missing await) and don't need documentation changes. Only flag patterns that would prevent future tests from hitting the same class of problem.
+
+1. **Classify the root cause.** Ask: "Would reading e2e-context.md, migration-context.md, or the skill instructions have prevented this failure?" If yes, there's a gap.
+
+2. **Check for pattern, not incident.** A gap is worth documenting when:
+   - The fix relies on behavior not mentioned anywhere (e.g., PF component wrapping, API propagation delays, fixture lifecycle quirks)
+   - The existing guidance actively led the agent astray (e.g., "use getByTestId" without warning about wrapper divs)
+   - The same class of failure is likely to recur in other tests
+
+   Skip if: the fix was a typo, a missing import, a stale selector, or a test-specific logic error.
+
+3. **Propose the change.** If a gap exists, present:
+   ```text
+   Documentation improvement:
+     File: .claude/e2e-context.md (or migration-context.md, or skill SKILL.md)
+     Section: <existing section name>
+     What to add: <1-3 sentence description of the pattern>
+     Why: <what went wrong and how this prevents it>
+   ```
+
+4. **Ask the user.** Do not apply changes without approval. Present the proposal and wait for confirmation.
+
+5. **Apply if approved.** Spawn a subagent (haiku) with specific edit instructions: the target file, the section, and the exact content to add. The subagent must only edit the approved file and section. After the subagent returns, verify the change matches the proposal. If it edited files outside the approved target, revert.
+
+**Skip this phase entirely** if no tests were fixed (all passed on first run or all were skipped).
+
 ## Troubleshooting
 
 ### Playwright MCP not connected
diff --git a/.claude/skills/gen-e2e-test/SKILL.md b/.claude/skills/gen-e2e-test/SKILL.md
new file mode 100644
index 00000000000..cec9219bdf8
--- /dev/null
+++ b/.claude/skills/gen-e2e-test/SKILL.md
@@ -0,0 +1,137 @@
+---
+name: gen-e2e-test
+description: Generate Playwright e2e tests for OpenShift Console features. Creates spec files and page objects following the project's established patterns and conventions. Use this skill whenever the user wants to create, write, or add e2e tests, asks to cover a feature with e2e, describes a UI workflow to test, says "I need to test this feature", "add test coverage for X", or invokes /gen-e2e-test explicitly.
+when_to_use: |
+  TRIGGER on: "create e2e test", "write e2e test", "generate e2e", "add playwright test", "new e2e spec", "write a spec for", "add e2e coverage", "I need to test this feature", "cover this with e2e", "test this workflow", or explicit /gen-e2e-test invocations. Also trigger when user describes a UI workflow to test or asks to add test coverage for a feature.
+  DO NOT trigger for: migrating Cypress tests (use migrate-cypress), fixing or debugging existing .spec.ts files (use debug-test), writing unit tests (use gen-rtl-test), running existing test suites.
+model: opus
+argument-hint: "<feature description> [--project=<name>] [--analyze]"
+allowed-tools: Read, Write, Edit, Bash(find *), Bash(grep *), Bash(ls *), Bash(npx tsc *), Bash(npx playwright *), Bash(git diff *), Bash(git status), mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_click, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_run_code_unsafe, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_close, mcp__plugin_playwright_playwright__browser_type, mcp__plugin_playwright_playwright__browser_wait_for, mcp__plugin_playwright_playwright__browser_network_requests, AskUserQuestion
+---
+
+# Generate Playwright E2E Test
+
+Create idiomatic Playwright e2e tests for OpenShift Console features following the project's established patterns.
+
+## Before Starting
+
+1. Check that `frontend/e2e/.env` exists. If missing and `--analyze` is not specified, copy `frontend/e2e/.env.example` to `frontend/e2e/.env` and ask the user to fill in their cluster values. During `--analyze`, report the missing file without creating it.
+2. Read `.claude/e2e-context.md` for project conventions, patterns, and rules. That file is the single source of truth for how Playwright tests should be structured.
+3. Read `frontend/e2e/fixtures/index.ts` and trace its imports to discover all available fixtures.
+
+## Input
+
+- `/gen-e2e-test <description>`: generate test for the described feature/workflow
+- `/gen-e2e-test <description> --project=<name>`: specify the Playwright project (default: inferred from feature area)
+- `/gen-e2e-test <description> --analyze`: produce a test plan without generating code
+
+### Examples
+
+```shell
+/gen-e2e-test "ConfigMap CRUD operations in admin perspective"
+/gen-e2e-test "verify topology view shows deployments" --project=topology
+/gen-e2e-test "developer user creates a project and deploys from git" --project=dev-console-developer
+```
+
+## Workflow
+
+### Phase 1: Scope
+
+1. Understand the feature/workflow to test from the user's description
+2. Identify the Playwright project and output directory (see `e2e-context.md` Project Structure)
+3. Identify admin vs developer persona
+4. Determine test isolation strategy: self-contained (A), shared resources (B), or API-created (C)
+5. Determine if tests can run in parallel or must be serial:
+   - **Parallel**: tests are independent, each creates its own namespace, no shared mutable state
+   - **Serial** (default): tests share a namespace, modify global settings, or depend on order
+6. Document each test's intent in plain language
+7. Produce a test plan:
+   ```
+   Test Plan: <feature>
+     Project: <playwright-project>
+     Output: e2e/tests/<project>/<name>.spec.ts
+     Persona: admin | developer
+     Isolation: Strategy A | B | C
+     Execution: serial | parallel
+
+     Tests:
+     1. <test name>: <intent>
+     2. <test name>: <intent>
+
+     Page objects:
+     - Reuse: <existing page objects>
+     - Create: <new page objects needed>
+
+     Resources:
+     - <namespace, deployment, configmap, etc.>
+   ```
+
+**Stop here if `--analyze` was specified.** Ask the user to review and confirm before proceeding.
+
+### Phase 2: Discover
+
+1. Search existing page objects: `find frontend/e2e/pages -name "*.ts"`
+2. Read relevant page objects to understand available methods and locators
+3. Read `frontend/e2e/fixtures/index.ts` to understand available fixtures
+4. Read `frontend/e2e/clients/kubernetes-client.ts` for available K8s API methods
+5. If the feature involves React components, read the component source to find existing `data-test` attributes
+6. If Playwright MCP is available:
+   - Resize viewport to 1920x1080
+   - Navigate to target pages in the live UI
+   - Snapshot accessibility tree to discover selectors and `data-test` attributes
+   - Verify selectors with non-submitting interactions (click navigation elements, type in search fields)
+   - Do not submit forms, create resources, or perform state-changing actions during discovery. Ask the user before login or credential entry
+
+   If MCP is unavailable or no cluster is reachable, log a warning: "Playwright MCP not available. Selectors based on React source only. Run `/debug-test` after deployment to verify." Proceed to Phase 3.
+
+### Phase 3: Implement
+
+1. **Add `data-test` attributes** to React components if needed. When a component only has legacy test attributes (`data-test-id`, etc.), add `data-test` alongside the legacy attribute (see `e2e-context.md` Test Selectors)
+
+2. **Create/extend page objects** if needed:
+   - Follow the BasePage pattern from `e2e-context.md`
+   - `private readonly` locator properties using `getByTestId()` or `locator()`
+   - Getter methods to expose locators (`getX(): Locator`)
+   - Action methods returning `Promise<void>`
+   - Use `robustClick()` for clicks inside page objects
+   - Do NOT add `waitFor()` before action methods. Playwright auto-waits
+
+3. **Write the spec file:**
+   - `import { test, expect } from '../../fixtures'` (adjust relative path based on test depth)
+   - Tags are optional. Only add them if they enable filtering beyond the directory structure (see `e2e-context.md` Tags section)
+   - Apply the chosen isolation strategy and execution mode
+   - Use `test.step()` for multi-phase workflows within a single test
+   - Track all created resources with `cleanup.track*()` or use `test.afterAll` for shared resources
+   - Name tests by user intent, not implementation
+
+4. **Validate code** (run from `frontend/`):
+   - `cd frontend && npx tsc --noEmit -p e2e/tsconfig.json`: zero type errors
+   - `cd frontend && yarn eslint <generated-files>`: fix lint errors
+
+### Phase 4: Verify
+
+1. Run (from `frontend/`): `cd frontend && npx playwright test --project=<project> <spec-file> --retries=0`
+   - For developer tests: `--project=<project>-developer`
+   - Note: `e2e/.env` may set `WEB_CONSOLE_URL` to a remote cluster. If running against localhost, verify `.env` or override with `WEB_CONSOLE_URL=http://localhost:9000`
+2. Debug failures using Playwright MCP if available (navigate → snapshot → console → network). Fix and re-run.
+3. If a test still fails after 3 fix attempts, stop trying and ask the user if they want to run `/debug-test <spec-file>` for deeper MCP-assisted diagnosis.
+4. Run 2 additional times to confirm stability
+5. Verify no orphaned resources after test run
+6. Output summary:
+   ```
+   Generation complete: e2e/tests/<project>/<name>.spec.ts
+     Tests created: N
+     Page objects created: [list]
+     Page objects reused: [list]
+     Files written: [list]
+     Validation: passed
+   ```
+
+## Rules
+
+- Always read `e2e-context.md` before writing any code
+- Discover available fixtures and page objects before creating new ones
+- Use Playwright MCP to verify selectors when available
+- Follow the project's existing patterns. Don't invent new conventions
+- Golden path first. Only add edge case tests when explicitly asked
+- **DO NOT commit.** The user handles git operations
diff --git a/.claude/skills/migrate-cypress/SKILL.md b/.claude/skills/migrate-cypress/SKILL.md
index 2de3585009f..e4b6fde0125 100644
--- a/.claude/skills/migrate-cypress/SKILL.md
+++ b/.claude/skills/migrate-cypress/SKILL.md
@@ -1,8 +1,8 @@
 ---
 name: migrate-cypress
-description: Migrate a Cypress test file (.cy.ts) or Gherkin feature file (.feature) to Playwright following Console's architecture. This is the ONLY skill for Cypress-to-Playwright conversion work, you can perform full migration, analysis-only (--analyze), or dry-run (--dry-run) modes.
+description: Migrate a Cypress test file (.cy.ts) or Gherkin feature file (.feature) to Playwright following Console's architecture. This is the ONLY skill for Cypress-to-Playwright conversion work, supporting full migration, analysis-only (--analyze), or dry-run (--dry-run) modes. Use this skill whenever the user wants to convert, port, rewrite, or migrate Cypress or Gherkin tests to Playwright, mentions "old cypress tests", "remaining e2e tests", or provides a .cy.ts or .feature file path in a migration context.
 when_to_use: |
-  TRIGGER on: "migrate", "convert cypress", "port to playwright", file paths ending in .cy.ts or .feature in a migration context, requests to rewrite Gherkin scenarios as Playwright specs, or explicit /migrate-cypress invocations. Also trigger when user mentions converting "old cypress tests", "remaining e2e tests", or moving test suites from Cypress to Playwright.
+  TRIGGER on: "migrate cypress", "migrate e2e", "migrate test", "convert cypress", "port to playwright", "rewrite in playwright", "convert these old tests", file paths ending in .cy.ts or .feature in a migration context, requests to rewrite Gherkin scenarios as Playwright specs, or explicit /migrate-cypress invocations. Also trigger when user mentions converting "old cypress tests", "remaining e2e tests", or moving test suites from Cypress to Playwright.
   DO NOT trigger for: writing new Playwright tests from scratch (no Cypress source), fixing or debugging existing .spec.ts files (use debug-test instead), running test suites, editing test infrastructure (base-page.ts, fixtures, KubernetesClient), or questions about Playwright API without migration intent.
 model: opus
 argument-hint: "<path/to/file.cy.ts or .feature> [--analyze] [--dry-run]"
@@ -16,7 +16,8 @@ Translate Cypress E2E tests into idiomatic Playwright code following Console's l
 ## Before Starting
 
 1. Check that `frontend/e2e/.env` exists. If missing, copy `frontend/e2e/.env.example` to `frontend/e2e/.env` and tell the user to fill in their cluster values before continuing.
-2. Read `.claude/migration-context.md` for the complete API translation tables, structural transformation rules, Console selector mappings, and migration checklist. That file is the single source of truth for all translation context.
+2. Read `.claude/e2e-context.md` for project conventions, patterns, and rules, page objects, selectors, fixtures, cleanup, waits, and things to never do. That file is the single source of truth for how Playwright tests should be structured.
+3. Read `.claude/migration-context.md` for the Cypress → Playwright API translation tables, structural transformation rules, Gherkin collapse mappings, and migration checklist.
 
 ## Input
 
@@ -69,7 +70,7 @@ Expected output: a structured plan listing each test's intent, the Playwright co
 1. Resize viewport to 1920×1080
 2. Navigate to target pages in the live UI
 3. Snapshot accessibility tree to discover `data-test` attributes and element roles
-4. Verify interactive elements work (click, type)
+4. Verify selectors with non-submitting interactions (click navigation elements, type in search fields). Do not submit forms or perform create/update/delete actions during discovery. Ask the user before login or credential entry
 5. Update migration plan with verified selectors
 
 If MCP is unavailable or no cluster is reachable, log a warning: "Playwright MCP not available — selectors translated literally. They may be stale. Run `/debug-test` after deployment to verify." Proceed to Phase 3.
@@ -107,7 +108,7 @@ Example:
    ```
 2. Write the spec file following project template:
    - `import { test, expect } from '../../fixtures'`
-   - `test.describe` with tags (e.g. `{ tag: ['@smoke'] }`)
+   - Tags are optional. Only add them if they enable filtering beyond the directory structure (see `e2e-context.md` Tags section)
    - Admin tests go in `e2e/tests/<package>/`, developer tests in `e2e/tests/<package>/developer/`
    - Self-contained: create → assert → cleanup in each `test()`
    - Use `test.step()` for logical grouping when a test has 3+ distinct phases
@@ -120,9 +121,11 @@ Example:
 ### Phase 4: Validation
 
 1. Run with `npx playwright test --project=<package> <output-file> --retries=0`. The project name matches the package directory under `e2e/tests/` (e.g. `--project=helm`, `--project=console`). For developer tests, use `--project=<package>-developer`. Add `--ui` only if the user requests interactive debugging. Note: `e2e/.env` may override `WEB_CONSOLE_URL` with a remote cluster URL. If running against localhost, ensure the user has updated `e2e/.env` or override with `WEB_CONSOLE_URL=http://localhost:9000`.
-2. Debug failures using Playwright MCP (navigate → snapshot → console → network)
-3. Verify no orphaned resources after run
-4. Produce migration summary:
+2. If the first run passes, run 2 additional times with `--retries=0` to catch intermittent failures. A migrated test that passes once but fails on subsequent runs is flaky and must be fixed before the migration is complete.
+3. Debug failures using Playwright MCP (navigate → snapshot → console → network). Fix and re-run.
+4. If a test still fails after 3 fix attempts, stop trying and ask the user if they want to run `/debug-test <spec-file>` for deeper MCP-assisted diagnosis.
+5. Verify no orphaned resources after run
+6. Produce migration summary:
    ```
    Migration complete: <source-file> → <output-file>
      Tests migrated: N
@@ -142,6 +145,16 @@ Example:
    The "Assertions" column shows `<cypress count> → <playwright count>`. If a Playwright test has fewer assertions than its Cypress counterpart, flag it with `⚠` and investigate — assertions may have been silently dropped.
 5. If validation passes, delete the original Cypress test file. Also check imported view and support files — if they are no longer imported by any other Cypress test, delete them too.
 
+## Flakiness Prevention
+
+Migration is the biggest source of flaky tests. Cypress and Playwright have fundamentally different execution models, and patterns that are stable in Cypress can be intermittent in Playwright. Watch for these during migration:
+
+- **Cypress retries assertions implicitly.** `cy.get(s).should('be.visible')` retries for up to 4 seconds by default. Playwright's `expect(locator).toBeVisible()` also retries, but with a different timeout (5s default). If the Cypress test relied on a long implicit wait, pass an explicit timeout: `await expect(locator).toBeVisible({ timeout: 30_000 })`.
+- **Cypress `cy.wait()` masks timing issues.** A `cy.wait(3000)` in Cypress often hides a race condition. Don't replace it with `page.waitForTimeout(3000)`. Instead, find what the wait is actually waiting for (a network response, a DOM element, a state change) and wait for that condition explicitly.
+- **Cypress shared state hides flakes.** With `testIsolation: false`, sequential `it` blocks share cookies, DOM, and navigation state. A test that passes in Cypress because the previous `it` left the page in the right state will fail intermittently in Playwright if the navigation or setup is incomplete. When merging `it` blocks into `test.step()`, make each step's preconditions explicit.
+- **PatternFly overlays intercept clicks.** Cypress `click({ force: true })` bypasses overlay checks. In Playwright, use `robustClick()` in page objects. This retries with scroll-into-view and falls back to force-click, which is more reliable than a single forced click.
+- **Resource creation races.** Cypress `cy.exec('oc create ...')` is synchronous within the test. `k8sClient.createNamespace()` is async. If the test navigates to a resource page immediately after creation, add an explicit wait for the resource to be ready: `await k8sClient.waitForNamespaceReady(ns)`.
+
 ## Key Translation Rules
 
 - **Never transliterate** — understand intent, use idiomatic Playwright APIs
@@ -172,5 +185,5 @@ Compare assertion count with the original Cypress test. If the migrated test has
 
 - Always read the Cypress source before writing any code
 - Use Playwright MCP to verify selectors against the live UI
-- Follow `.claude/migration-context.md` for API translation tables
+- Follow `.claude/e2e-context.md` for Playwright patterns and `.claude/migration-context.md` for Cypress translation tables
 - **DO NOT commit** — the user handles git operations