/playwright

name: playwright
description: >
  Playwright E2E testing patterns.
  Trigger: When writing Playwright E2E tests (Page Object Model, selectors, MCP exploration workflow). For Prowler-specific UI conventions under ui/tests, also use prowler-test-ui.
license: Apache-2.0
metadata:
  author: prowler-cloud
  version: "1.1"
  scope: [root, ui]
  auto_invoke: "Writing Playwright E2E tests"
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task

MCP Workflow (MANDATORY If Available)

**⚠️ If you have Playwright MCP tools, ALWAYS use them BEFORE creating any test:**

1. **Navigate** to target page 2. **Take snapshot** to see page structure and elements 3. **Interact** with forms/elements to verify exact user flow 4. **Take screenshots** to document expected states 5. **Verify page transitions** through complete flow (loading, success, error) 6. **Document actual selectors** from snapshots (use real refs and labels) 7. **Only after exploring** create test code with verified selectors

**If MCP NOT available:** Proceed with test creation based on docs and code analysis.

**Why This Matters:**

• ✅ Precise tests - exact steps needed, no assumptions
• ✅ Accurate selectors - real DOM structure, not imagined
• ✅ Real flow validation - verify journey actually works
• ✅ Avoid over-engineering - minimal tests for what exists
• ✅ Prevent flaky tests - real exploration = stable tests
• ❌ Never assume how UI "should" work

File Structure

tests/
├── base-page.ts              # Parent class for ALL pages
├── helpers.ts                # Shared utilities
└── {page-name}/
    ├── {page-name}-page.ts   # Page Object Model
    ├── {page-name}.spec.ts   # ALL tests here (NO separate files!)
    └── {page-name}.md        # Test documentation

**File Naming** (default; `ui/tests/auth/` is a deliberate exception with one spec per concern and one shared `auth.md`):

• ✅ `sign-up.spec.ts` (all sign-up tests)
• ✅ `sign-up-page.ts` (page object)
• ✅ `sign-up.md` (documentation)
• ❌ `sign-up-critical-path.spec.ts` (WRONG - no separate files)
• ❌ `sign-up-validation.spec.ts` (WRONG)

Selector Priority (REQUIRED)

// 1. BEST - getByRole for interactive elements
this.submitButton = page.getByRole("button", { name: "Submit" });
this.navLink = page.getByRole("link", { name: "Dashboard" });

// 2. BEST - getByLabel for form controls
this.emailInput = page.getByLabel("Email");
this.passwordInput = page.getByLabel("Password");

// 3. SPARINGLY - getByText for static content only
this.errorMessage = page.getByText("Invalid credentials");
this.pageTitle = page.getByText("Welcome");

// 4. LAST RESORT - getByTestId when above fail
this.customWidget = page.getByTestId("date-picker");

// ❌ AVOID fragile selectors
this.button = page.locator(".btn-primary");  // NO
this.input = page.locator("#email");         // NO

Scope Detection (ASK IF AMBIGUOUS)

| User Says | Action | |-----------|--------| | "a test", "one test", "new test", "add test" | Create ONE test() in existing spec | | "comprehensive tests", "all tests", "test suite", "generate tests" | Create full suite |

**Examples:**

• "Create a test for user sign-up" → ONE test only
• "Generate E2E tests for login page" → Full suite
• "Add a test to verify form validation" → ONE test to existing spec

Page Object Pattern

import { Page, Locator, expect } from "@playwright/test";

// BasePage - ALL pages extend this
export class BasePage {
  constructor(protected page: Page) {}

  async goto(path: string): Promise<void> {
    await this.page.goto(path);
    // NEVER waitForLoadState("networkidle"): flaky with polling/streams.
    // Subclasses implement verifyPageLoaded() with a web-first assertion.
  }

  // Common methods go here (see Refactoring Guidelines)
  async verifyElementVisible(element: Locator): Promise<void> {
    await expect(element).toBeVisible();
  }
}

// Page-specific implementation
export interface LoginData {
  email: string;
  password: string;
}

export class LoginPage extends BasePage {
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;

  constructor(page: Page) {
    super(page);
    this.emailInput = page.getByLabel("Email");
    this.passwordInput = page.getByLabel("Password");
    this.submitButton = page.getByRole("button", { name: "Sign in" });
  }

  async goto(): Promise<void> {
    await super.goto("/login");
  }

  async login(data: LoginData): Promise<void> {
    await this.emailInput.fill(data.email);
    await this.passwordInput.fill(data.password);
    await this.submitButton.click();
  }

  async verifyCriticalOutcome(): Promise<void> {
    await expect(this.page).toHaveURL("/dashboard");
  }
}

Page Object Reuse (CRITICAL)

**Always check existing page objects before creating new ones!**

// ✅ GOOD: Reuse existing page objects
import { SignInPage } from "../sign-in-base/sign-in-base-page";
import { HomePage } from "../home/home-page";

test("User can sign up and login", async ({ page }) => {
  const signUpPage = new SignUpPage(page);
  const signInPage = new SignInPage(page);  // REUSE
  const homePage = new HomePage(page);      // REUSE

  await signUpPage.signUp(userData);
  await homePage.verifyPageLoaded();  // REUSE method
  await homePage.signOut();           // REUSE method
  await signInPage.login(credentials); // REUSE method
});

// ❌ BAD: Recreating existing functionality
export class SignUpPage extends BasePage {
  async logout() { /* ... */ }  // ❌ HomePage already has this
  async login() { /* ... */ }   // ❌ SignInPage already has this
}

**Guidelines:**

• Check `tests/` for existing page objects first
• Import and reuse existing pages
• Create page objects only when page doesn't exist
• If test requires multiple pages, ensure all page objects exist (create if needed)

Refactoring Guidelines

Move to `BasePage` when

• ✅ Navigation helpers used by multiple pages (`w