fluffychat/.github/instructions/playwright-testing.instructions.md

applyTo
lib/pangea/**,lib/pages/**,lib/widgets/**

Playwright Testing — Flutter Web Client

How to interact with the Pangea Chat Flutter web app using the Playwright MCP tools.

Critical: Flutter Web Uses CanvasKit

Flutter web renders to a <canvas> element, not DOM nodes. Standard Playwright selectors (page.getByText(), page.locator()) will not find Flutter widgets. You must:

1. Enable accessibility — Click the "Enable accessibility" button that Flutter overlays on the page. This activates the semantics tree, which exposes widget labels to Playwright's accessibility snapshot.
2. Use browser_snapshot — After enabling accessibility, use browser_snapshot to see the semantic tree. This returns ARIA labels and roles that map to Flutter widget Semantics / Tooltip / button labels.
3. Use browser_click with ref — Click elements by their ref from the snapshot, not by CSS selectors.
4. Use browser_type with ref — Type into text fields by their ref from the snapshot.
5. Use browser_take_screenshot — When the semantic tree is insufficient (e.g. visual layout issues, canvas rendering bugs), take a screenshot to see what's actually on screen.

Enable Accessibility (First Step After Navigation)

Flutter's "Enable accessibility" button is placed off-screen by default and is often unreachable via normal click due to scroll/viewport issues. Use browser_run_code to force-enable it via JavaScript:

async (page) => {
  // Flutter places the semantics placeholder off-screen. Force-click it via JS.
  await page.evaluate(() => {
    const btn = document.querySelector('flt-semantics-placeholder')
      || document.querySelector('[aria-label="Enable accessibility"]');
    if (btn) btn.click();
  });
}

Then wait 2–3 seconds and take a snapshot — you should now see Flutter widget labels.

Do not try to find and click the button via browser_snapshot + browser_click — the button is intentionally positioned outside the viewport and Playwright cannot scroll to it reliably.

Login Flow

Prerequisites

• Flutter web app running locally (e.g. flutter run -d chrome on some port)
• Staging test credentials from client/.env (see matrix-auth.instructions.md)

Step-by-Step Login

1. Navigate to the app URL (e.g. http://localhost:<port>)
2. Enable accessibility (see above)
3. Snapshot — you should see "Start" and "Login to my account" buttons
4. Click "Login to my account" → navigates to /home/login
5. Snapshot — you should see "Sign in with Apple", "Sign in with Google", "Email" options
6. Click "Email" → navigates to /home/login/email
7. Snapshot — you should see "Username or Email" and "Password" text fields, and a "Login" button
8. Type the username (just the localpart, e.g. wykuji, not the full @wykuji:staging.pangea.chat) into the username field
9. Type the password into the password field
10. Click "Login" button
11. Wait 5–10 seconds for sync to complete
12. Snapshot — you should now be on the chat list (/rooms)

Navigate to a Room

After login, navigate to a specific room by URL:

http://localhost:<port>/#/rooms/<room_id>

Or find the room in the chat list via snapshot and click it.

Route Map

Route	What You'll See
/#/home	Landing page: logo, "Start", "Login to my account"
/#/home/login	Login options: Apple, Google, Email
/#/home/login/email	Username + Password form
/#/rooms	Chat list (requires auth)
/#/rooms/<room_id>	Chat room with message input

Interacting With Chat

Once in a room:

1. Snapshot to find the text input field and other UI elements
2. Type a message into the input field
3. Wait for writing assistance to trigger (debounce ~1.5s after typing stops)
4. Snapshot to see the assistance ring, highlighted text, and any span cards
5. Click highlighted text to open the span card
6. Screenshot to visually inspect the ring segments, highlight colors, and span card layout

What to Look For

Element	Semantic Label / Visual Cue
Text input	Input field in the bottom bar
Assistance ring	Pangea logo icon with colored ring segments
Send button	Right-most button in input bar
Span card	Overlay popup with category title, bot face, choices
Highlighted text	Background color behind matched text in the input

Tips

• Snapshots are better than screenshots for finding interactive elements and their ref IDs.
• Screenshots are better than snapshots for verifying visual styling (colors, layout, animations).
• Wait between actions — Flutter web can be slow, especially during initial load and sync. Use browser_wait_for with 2–5 second delays after navigation or login.
• Hash routing — all Flutter routes use /#/ prefix. Direct navigation works.
• Session is ephemeral — the Playwright browser doesn't share the user's Chrome session. You must log in each time.

Limitations

• SSO login (Apple/Google) cannot be automated — use email/password login only.
• CanvasKit rendering means pixel-level visual assertions are screenshot-based, not DOM-based.
• Some widgets may not have semantic labels — file a bug if a key interaction point is invisible to the accessibility snapshot.
• Animations (ring spin, card transitions) won't appear in snapshots — use screenshots or video for those.