Initial: pi-skill — 68 skills, 43 extensions, 11 themes for Pi
This commit is contained in:
Kunthawat Greethong
182
skills/qa-automation/qa-scroll/SKILL.md
Normal file
182
skills/qa-automation/qa-scroll/SKILL.md
Normal file
@@ -0,0 +1,182 @@
|
||||
---
|
||||
name: qa-scroll
|
||||
description: >
|
||||
QA test skill for verifying scroll-based media feeds — video autoplay, scroll navigation,
|
||||
mute/unmute, and playback progression. Uses the CDP + agent-device dual-driver architecture.
|
||||
Works with any React Native app using expo-video or similar video player libraries.
|
||||
Invoke when user says "test scroll feed", "test video playback", "QA the feed",
|
||||
"verify video autoplay", "run scroll tests", "test media player", or any task
|
||||
requiring scroll-based media feed verification.
|
||||
allowed-tools: Bash(agent-device:*) Bash(agent-browser:*) Bash(xcrun:*) Bash(node:*) Bash(curl:*) Bash(npx:*) Read
|
||||
---
|
||||
|
||||
# qa-scroll
|
||||
|
||||
QA test skill for verifying scroll-based media feeds — **video autoplay**, **scroll navigation**, **mute/unmute toggle**, and **playback progression**. Uses the dual-driver architecture (CDP + agent-device) to test media feeds in native mobile apps.
|
||||
|
||||
## What It Tests
|
||||
|
||||
| Test | Method | Assertion |
|
||||
|------|--------|-----------|
|
||||
| First video autoplays | CDP player state query | `player.playing === true`, `currentTime > 0` |
|
||||
| Video progress advances | CDP currentTime check after delay | `currentTime` increased between checks |
|
||||
| Scroll to next video | CDP scroll hook or agent-device swipe | New video starts playing |
|
||||
| Mute toggle | CDP `player.muted = !player.muted` | Mute state flips |
|
||||
| Unmute toggle | CDP `player.muted = !player.muted` | Mute state flips back |
|
||||
| Scroll continuity | Multiple swipes | Each new video autoplays |
|
||||
| Final route check | CDP `cdp_get_route` | Still on the feed screen |
|
||||
|
||||
## Setup Guard (Automatic)
|
||||
|
||||
The skill includes a **setup guard** that runs before every test. It checks and auto-fixes:
|
||||
|
||||
| Check | What it does if missing |
|
||||
|-------|------------------------|
|
||||
| iOS Simulator booted | Boots it or auto-detects a booted one |
|
||||
| Dev server running | Starts it in background, waits up to 60s |
|
||||
| App in foreground | Launches via `xcrun simctl launch` |
|
||||
| CDP target available | Polls `/json` endpoint for up to 30s |
|
||||
| CDP connection functional | Sends `eval 1+1`, retries 3x |
|
||||
| Navigation module ID valid | Auto-scans Metro modules with caching |
|
||||
| Error overlay | Suppresses LogBox errors via CDP |
|
||||
|
||||
## Configuration
|
||||
|
||||
Before running, set your app-specific values in `qa.config.sh` or `qa.config.local.sh`:
|
||||
|
||||
```bash
|
||||
# Required
|
||||
export APP_BUNDLE_ID="com.yourapp.dev"
|
||||
export PROJECT_DIR="/path/to/your/project"
|
||||
|
||||
# Video player (for expo-video apps)
|
||||
export VIDEO_PLAYER_CLASS="VideoPlayer" # Class to look for
|
||||
export GLOBAL_PLAYERS_VAR="__qaVideoPlayers" # Global tracking variable
|
||||
|
||||
# Screen names (for CDP navigation)
|
||||
export SCREEN_EXPLORE="ExploreScreen" # Your feed screen name
|
||||
|
||||
# Optional: if your app has a feed scroll hook
|
||||
export GLOBAL_FEED_VAR="__qaFeedState" # Feed state debug hook name
|
||||
```
|
||||
|
||||
## Test Result States
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| **passed** | Assertion verified via CDP |
|
||||
| **failed** | Assertion verified but wrong |
|
||||
| **skipped** | CDP query inconclusive — cannot determine pass/fail |
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
CDP (Hermes Runtime) agent-device (Simulator)
|
||||
┌──────────────────────┐ ┌──────────────────────┐
|
||||
│ navigate to tab │ │ swipe up (scroll) │
|
||||
│ install debug hook │ │ tap center (fallback) │
|
||||
│ query player state │ │ screenshot capture │
|
||||
│ .playing │ │ appstate check │
|
||||
│ .muted │ │ │
|
||||
│ .currentTime │ │ │
|
||||
│ toggle mute via CDP │ │ │
|
||||
│ dismiss error overlay│ │ │
|
||||
└──────────────────────┘ └──────────────────────┘
|
||||
```
|
||||
|
||||
### Why CDP, not agent-browser?
|
||||
|
||||
`agent-browser` uses Playwright's CDP protocol which sends `Target.setDiscoverTargets` — a method Hermes doesn't support. Native apps don't have a DOM to interact with. Raw CDP via WebSocket to Hermes is the correct approach for JS runtime queries in React Native apps.
|
||||
|
||||
### Why agent-device, not agent-browser?
|
||||
|
||||
`agent-device` is purpose-built for iOS/Android simulator control — screenshots, swipe gestures, accessibility snapshots. `agent-browser` is for web pages. Native apps render native views, not web views.
|
||||
|
||||
## Usage
|
||||
|
||||
### Run the example test
|
||||
```bash
|
||||
bash .pi/skills/qa-automation/qa-scroll/run.sh
|
||||
```
|
||||
|
||||
### Run a specific flow
|
||||
```bash
|
||||
bash .pi/skills/qa-automation/qa-scroll/flows/example-scroll-test.sh
|
||||
```
|
||||
|
||||
### View results
|
||||
- Screenshots: `/tmp/qa-tests/screenshots/<test-name>/`
|
||||
- Report JSON: `/tmp/qa-tests/<test-name>-report.json`
|
||||
|
||||
## Customizing for Your App
|
||||
|
||||
### Step 1: Configure video player detection
|
||||
|
||||
The debug hook patches `VideoPlayer.prototype.play()` to track instances. If your app uses a different video player:
|
||||
|
||||
```bash
|
||||
# In qa.config.sh:
|
||||
export VIDEO_PLAYER_CLASS="MyVideoPlayer" # Your player class name
|
||||
```
|
||||
|
||||
The hook scans Metro modules looking for `module.default.VideoPlayer` or `module.VideoPlayer`. Adjust the scan in `scroll-helpers.sh` if your player is exported differently.
|
||||
|
||||
### Step 2: Configure feed scrolling
|
||||
|
||||
If your app exposes a scroll-to-next function via a debug hook:
|
||||
|
||||
```bash
|
||||
# In your app code (dev builds only):
|
||||
globalThis.__qaFeedState = {
|
||||
currentIndex: 0,
|
||||
scrollToNext: () => { /* scroll logic */ },
|
||||
scrollToIndex: (i) => { /* scroll to index */ },
|
||||
getData: () => { /* return feed data array */ },
|
||||
getItem: (i) => { /* return item at index */ }
|
||||
};
|
||||
```
|
||||
|
||||
If no hook is available, the skill falls back to `agent-device swipe` gestures.
|
||||
|
||||
### Step 3: Create your test flow
|
||||
|
||||
Copy `flows/example-scroll-test.sh` and customize the steps for your app's feed structure.
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
qa-scroll/
|
||||
├── SKILL.md # This file
|
||||
├── lib/
|
||||
│ ├── setup-guard.sh # Prerequisites checker + auto-fixer
|
||||
│ └── scroll-helpers.sh # Video state, mute control, feed interaction
|
||||
├── flows/
|
||||
│ └── example-scroll-test.sh # Example test (customize for your app)
|
||||
└── run.sh # Runner with JSON report output
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Setup guard failed"
|
||||
Check the specific `[SETUP]` line that shows `FAILED`. Common causes:
|
||||
- Simulator not installed or wrong UDID
|
||||
- Dev server port in use by another process
|
||||
- App not installed (build and install first)
|
||||
|
||||
### "No CDP target found"
|
||||
The app needs to be connected to the dev server. After a fresh install, launch the app and wait for the connection.
|
||||
|
||||
### "VideoPlayer class not found"
|
||||
The module scan didn't find your video player class. Check:
|
||||
- Is the video player library installed? (`expo-video`, `react-native-video`, etc.)
|
||||
- Does the class name match `VIDEO_PLAYER_CLASS` in config?
|
||||
- Try widening the scan range: `export MODULE_SCAN_END=10000`
|
||||
|
||||
### Tests show "skipped"
|
||||
CDP couldn't read player state. The debug hook may not have captured any players yet. Common causes:
|
||||
- No video content loaded (API returned empty feed)
|
||||
- Players created before hook was installed (hook captures on `play()` call)
|
||||
- Video library doesn't use the expected class structure
|
||||
|
||||
### Error overlay appears
|
||||
The setup guard suppresses LogBox, but errors during CDP eval may trigger new overlays. The test automatically checks for and dismisses overlays before screenshots.
|
||||
Reference in New Issue
Block a user