218 lines
5.8 KiB
Markdown
218 lines
5.8 KiB
Markdown
---
|
|
name: qa-web
|
|
description: >
|
|
QA test skill for web applications using agent-browser. Tests forms, navigation,
|
|
responsive layouts, state persistence via cookies/localStorage, and visual regression.
|
|
The web counterpart to agent-device — together they cover native + web testing.
|
|
Invoke when user says "test the web app", "test localhost", "QA the website",
|
|
"test the form", "verify responsive layout", "run web tests", "test browser",
|
|
or any task requiring automated web application testing.
|
|
allowed-tools: Bash(agent-browser:*) Bash(node:*) Bash(curl:*) Read
|
|
---
|
|
|
|
# qa-web
|
|
|
|
Web application QA testing using **agent-browser**. The web counterpart to agent-device — together they provide full coverage for apps with both native and web versions.
|
|
|
|
## When to Use
|
|
|
|
| Scenario | Tool |
|
|
|----------|------|
|
|
| Test native iOS/Android app | agent-device + CDP |
|
|
| Test web app / localhost | **agent-browser** (this skill) |
|
|
| Test React Native Web | **agent-browser** (this skill) |
|
|
| Test responsive layouts | **agent-browser** (this skill) |
|
|
| Test forms and navigation | **agent-browser** (this skill) |
|
|
|
|
## Core Workflow
|
|
|
|
Every web test follows the same pattern as native tests:
|
|
|
|
1. **Navigate**: `agent-browser open <url>`
|
|
2. **Snapshot**: `agent-browser snapshot -i` (get element refs)
|
|
3. **Interact**: Use refs to click, fill, select
|
|
4. **Re-snapshot**: After navigation/DOM changes, get fresh refs
|
|
5. **Assert**: Verify URL, text, element state
|
|
|
|
```bash
|
|
agent-browser open http://localhost:3000/login
|
|
agent-browser snapshot -i
|
|
# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Sign In"
|
|
|
|
agent-browser fill @e1 "user@example.com"
|
|
agent-browser fill @e2 "password123"
|
|
agent-browser click @e3
|
|
agent-browser wait --load networkidle
|
|
agent-browser snapshot -i # Check result
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Set web-specific values in `qa.config.sh`:
|
|
|
|
```bash
|
|
export WEB_BASE_URL="http://localhost:3000" # Your web app URL
|
|
export WEB_SESSION="qa" # Browser session name
|
|
export WEB_VIEWPORT_WIDTH=1280 # Default viewport
|
|
export WEB_VIEWPORT_HEIGHT=720
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Run example web test
|
|
```bash
|
|
bash .pi/skills/qa-automation/qa-web/run.sh
|
|
```
|
|
|
|
### Run with headed browser (see what's happening)
|
|
```bash
|
|
export WEB_HEADED=true
|
|
bash .pi/skills/qa-automation/qa-web/flows/example-web-test.sh
|
|
```
|
|
|
|
## Helper Library — web-helpers.sh
|
|
|
|
Source this in your web test scripts for consistent patterns:
|
|
|
|
```bash
|
|
source .pi/skills/qa-automation/qa-web/lib/web-helpers.sh
|
|
```
|
|
|
|
### Available Functions
|
|
|
|
| Function | Purpose |
|
|
|----------|---------|
|
|
| `web_open "url"` | Navigate to URL |
|
|
| `web_snapshot` | Get interactive element refs |
|
|
| `web_click "ref_or_selector"` | Click element |
|
|
| `web_fill "ref" "text"` | Fill input field |
|
|
| `web_select "ref" "value"` | Select dropdown option |
|
|
| `web_wait "selector_or_ms"` | Wait for element/time |
|
|
| `web_screenshot "name"` | Screenshot with naming convention |
|
|
| `web_get_text "ref"` | Get element text |
|
|
| `web_get_url` | Get current URL |
|
|
| `web_get_title` | Get page title |
|
|
| `web_is_visible "ref"` | Check element visibility |
|
|
| `web_assert_url "pattern"` | Assert URL matches pattern |
|
|
| `web_assert_title "text"` | Assert page title |
|
|
| `web_assert_text "text"` | Assert text visible on page |
|
|
| `web_scroll "direction" [px]` | Scroll page |
|
|
| `web_save_state "file"` | Save cookies/storage |
|
|
| `web_load_state "file"` | Restore saved state |
|
|
|
|
## Test Patterns
|
|
|
|
### Form Testing
|
|
|
|
```bash
|
|
source web-helpers.sh
|
|
|
|
web_open "$WEB_BASE_URL/signup"
|
|
web_snapshot
|
|
|
|
web_fill @e1 "Jane Doe"
|
|
web_fill @e2 "jane@example.com"
|
|
web_fill @e3 "password123"
|
|
web_select @e4 "California"
|
|
web_click @e5 # Submit
|
|
web_wait --load networkidle
|
|
|
|
web_assert_url "**/dashboard"
|
|
web_assert_text "Welcome, Jane"
|
|
web_screenshot "signup-success"
|
|
```
|
|
|
|
### Navigation Testing
|
|
|
|
```bash
|
|
web_open "$WEB_BASE_URL"
|
|
web_snapshot
|
|
|
|
# Click nav links
|
|
web_click @e3 # "About" link
|
|
web_assert_url "**/about"
|
|
web_screenshot "about-page"
|
|
|
|
# Go back
|
|
agent-browser back
|
|
web_assert_url "**/"
|
|
```
|
|
|
|
### Responsive Testing
|
|
|
|
```bash
|
|
# Desktop
|
|
agent-browser set viewport 1440 900
|
|
web_open "$WEB_BASE_URL"
|
|
web_screenshot "desktop-home"
|
|
|
|
# Tablet
|
|
agent-browser set viewport 768 1024
|
|
web_screenshot "tablet-home"
|
|
|
|
# Mobile
|
|
agent-browser set viewport 375 812
|
|
web_screenshot "mobile-home"
|
|
```
|
|
|
|
### State Persistence (Cookies/Storage)
|
|
|
|
```bash
|
|
# Login and save state
|
|
web_open "$WEB_BASE_URL/login"
|
|
web_fill @e1 "user@example.com"
|
|
web_fill @e2 "password"
|
|
web_click @e3
|
|
web_wait --load networkidle
|
|
web_save_state "/tmp/qa-auth-state.json"
|
|
|
|
# Reuse in future tests
|
|
web_load_state "/tmp/qa-auth-state.json"
|
|
web_open "$WEB_BASE_URL/dashboard"
|
|
web_assert_text "Welcome" # Still logged in
|
|
```
|
|
|
|
### Accessibility Testing
|
|
|
|
```bash
|
|
web_open "$WEB_BASE_URL"
|
|
agent-browser snapshot # Full a11y tree
|
|
agent-browser screenshot --full /tmp/qa-full-page.png
|
|
```
|
|
|
|
## File Structure
|
|
|
|
```
|
|
qa-web/
|
|
├── SKILL.md # This file
|
|
├── lib/
|
|
│ └── web-helpers.sh # Web test helper functions
|
|
├── flows/
|
|
│ └── example-web-test.sh # Example test
|
|
└── run.sh # Runner
|
|
```
|
|
|
|
## Integration with Native Tests
|
|
|
|
For apps with both native and web versions, use both tools in the same test run:
|
|
|
|
```bash
|
|
# Test native app
|
|
bash .pi/skills/qa-automation/qa-scroll/run.sh
|
|
|
|
# Test web app
|
|
bash .pi/skills/qa-automation/qa-web/run.sh
|
|
|
|
# Both results in /tmp/qa-tests/
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
| Problem | Solution |
|
|
|---------|----------|
|
|
| "agent-browser: command not found" | Install: `npm install -g agent-browser` |
|
|
| Browser launches but page is blank | Check URL and dev server: `curl $WEB_BASE_URL` |
|
|
| Refs invalidated after click | Always re-snapshot after navigation/DOM changes |
|
|
| Can't access localhost | agent-browser runs locally — it CAN access localhost (unlike web_remote) |
|
|
| Headed mode not showing | Set `export WEB_HEADED=true` before running |
|