473ffbaf24
* "docs: writing assistance redesign design spec (#5655) Add comprehensive design doc for the WA redesign: - AssistanceRing replaces StartIGCButton (segmented ring around Pangea icon) - Background highlights with category colors (not red/orange error tones) - Simplified match lifecycle: open → viewed → accepted (no ignore) - Persistent span card with smooth transitions between matches - Send always available, no gate on unresolved matches Remove superseded design docs (SPAN_CARD_REDESIGN_FINALIZED.md, SPAN_CARD_REDESIGN_Q_AND_A.md, choreographer.instructions.md)." * feat: replace ignored status with viewed status, initial updates to span card * resolve merge conflicts * rebuild input bar on active match update to fix span hightlighting * cleanup * allow opening span cards for closed matches * no gate on sending, update underline colors * animate span card transitions * initial updates to add segmented IGC progress ring * update segment colors / opacities based on match statuses * use same widget for igc loading and fetched * more segment animation changes * fix scrolling and wrap in span card * better disabled color * close span card on assistance state change * remove print statements * update design doc * cleanup --------- Co-authored-by: ggurdin <ggurdin@gmail.com>
114 lines
5.4 KiB
Markdown
114 lines
5.4 KiB
Markdown
---
|
||
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:**
|
||
|
||
```js
|
||
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](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.
|