# Browser Observe

Observe, explore, and verify web application behavior using Playwright. Use this for:

- **Reconnaissance:** Understand how existing features look and work before making changes
- **Verification:** Confirm implementations work correctly from the user's perspective
- **Debugging:** Investigate issues, capture console errors, diagnose problems

## Arguments

- `$ARGUMENTS` - What to observe: page/feature to explore, issue to investigate, or behavior to verify

## Instructions

You are using Playwright to interact with the web application through a real browser. You can observe current state, test interactions, and capture evidence.

### Use Cases

**Observation/Reconnaissance:**

- "Observe the user settings page" → Navigate, screenshot, document current state
- "How does the login flow work?" → Walk through flow, capture each step

**Verification:**

- "Verify the new button works" → Click it, confirm behavior, check for errors
- "Test the edit functionality" → Perform edits, verify data updates

**Debugging:**

- "Why is the form not submitting?" → Interact, capture console errors, diagnose
- "Check for errors on dashboard" → Navigate, monitor console, report issues

### Step 1: Find the E2E Directory

Look for an e2e directory with Playwright. Common locations:

- `e2e/`
- `tests/e2e/`
- `projects/*/e2e/`

Check for `playwright.config.ts` to confirm.

### Step 2: Determine URLs

Check the e2e `.env.example` or `playwright.config.ts` for:

- Frontend URL (typically `localhost:3000` or `localhost:5173`)
- Backend/API URL (typically `localhost:3001`)

### Step 3: Create/Update Test File

Create or update a test file (e.g., `specs/browser-helper.spec.ts`):

```typescript
import { test, expect } from "@playwright/test";
// Or use project fixtures if available:
// import { expect, test } from '../fixtures/test-fixtures'

test.describe("Browser Helper", () => {
    test("[DESCRIBE WHAT YOU ARE DOING]", async ({ page }) => {
        const consoleErrors: string[] = [];
        const consoleLogs: string[] = [];

        page.on("console", (msg) => {
            const text = `[${msg.type()}] ${msg.text()}`;
            consoleLogs.push(text);
            if (msg.type() === "error") consoleErrors.push(text);
        });
        page.on("pageerror", (error) => {
            consoleErrors.push(`[pageerror] ${error.message}`);
        });

        // Navigate
        console.log("Navigating to [URL]...");
        await page.goto("[URL]");
        await page.waitForTimeout(500);

        // Screenshot - Initial State
        await page.screenshot({ path: "test-results/observe-01-initial.png", fullPage: true });
        console.log("Screenshot: observe-01-initial.png");

        // [ADD OBSERVATIONS/INTERACTIONS HERE]

        // Report
        console.log("\nConsole Logs (last 30):");
        consoleLogs.slice(-30).forEach((log) => console.log(`  ${log}`));
        if (consoleErrors.length > 0) {
            console.log("\nConsole Errors:");
            consoleErrors.forEach((err) => console.log(`  ${err}`));
        } else {
            console.log("\nNo console errors!");
        }

        expect(true).toBe(true);
    });
});
```

### Step 4: Run the Test

```bash
cd [E2E_DIRECTORY]
BASE_URL='[FRONTEND_URL]' API_URL='[API_URL]' pnpm playwright test [TEST_FILE] --reporter=list
```

Or if env vars are in `.env`:

```bash
pnpm playwright test [TEST_FILE] --reporter=list
```

### Step 5: Read Screenshots

Use the Read tool on PNG files in `test-results/observe-*.png`

### Step 6: Report Findings

**For Observation/Reconnaissance:**

- Describe what you see in each screenshot
- Document the current UI layout and elements
- Note user flow and interaction patterns
- Capture current behavior as baseline

**For Verification:**

- Confirm expected behavior occurred
- Note any unexpected results
- Report console errors if any
- State whether verification passed

**For Debugging:**

- Describe the issue observed
- Report console errors with context
- Identify potential root causes
- Suggest fixes if applicable

### Common Interactions

**Navigate and observe:**

```typescript
await page.goto("/some/page");
await page.waitForTimeout(500);
await page.screenshot({ path: "test-results/observe-01-page.png", fullPage: true });
```

**Click and observe result:**

```typescript
await page.getByText("Button Text").click();
await page.waitForTimeout(300);
await page.screenshot({ path: "test-results/observe-02-after-click.png", fullPage: true });
```

**Double-click to edit (DataGrid/spreadsheet):**

```typescript
const cell = page.getByText("Cell Value").first();
await cell.dblclick();
await page.waitForTimeout(300);
const input = page.locator("input:focus");
if (await input.isVisible({ timeout: 1000 }).catch(() => false)) {
    await input.fill("New Value");
    await input.press("Enter");
}
await page.screenshot({ path: "test-results/observe-03-after-edit.png", fullPage: true });
```

**Fill a form:**

```typescript
await page.locator('input[name="fieldName"]').fill("value");
await page.getByLabel("Field Label").fill("value");
```

**Select dropdown:**

```typescript
await page.getByRole("combobox").click();
await page.getByRole("option", { name: "Option Name" }).click();
```

**Walk through a user flow:**

```typescript
// Step 1: Start page
await page.goto("/start");
await page.screenshot({ path: "test-results/flow-01-start.png", fullPage: true });

// Step 2: Click action
await page.getByText("Next").click();
await page.waitForTimeout(500);
await page.screenshot({ path: "test-results/flow-02-step2.png", fullPage: true });

// Step 3: Fill form
await page.getByLabel("Name").fill("Test");
await page.screenshot({ path: "test-results/flow-03-filled.png", fullPage: true });

// Step 4: Submit
await page.getByText("Submit").click();
await page.waitForTimeout(1000);
await page.screenshot({ path: "test-results/flow-04-result.png", fullPage: true });
```

**Check focused element:**

```typescript
const focused = await page.evaluate(() => ({
    tag: document.activeElement?.tagName,
    type: (document.activeElement as HTMLInputElement)?.type,
    class: document.activeElement?.className,
}));
console.log("Focused:", JSON.stringify(focused));
```

### DO NOT

- Ask for confirmation before running
- Skip taking screenshots
- Save screenshots and other results in the /.claude folder
- Forget to read and report on screenshots

### DO

- only use /e2e/test-results folder for screenshots and other results