multi-device-docs-tester.md

---
name: Multi-Device Docs Tester

description: Tests a documentation site for responsive layout issues, accessibility problems, and broken interactions across mobile, tablet, and desktop device form factors

on:
  schedule: daily
  workflow_dispatch:
    inputs:
      devices:
        description: 'Device types to test (comma-separated: mobile,tablet,desktop)'
        required: false
        default: 'mobile,tablet,desktop'
      docs_dir:
        description: 'Directory containing the documentation site (relative to repository root)'
        required: false
        default: 'docs'
      build_command:
        description: 'Command to build the documentation site'
        required: false
        default: 'npm run build'
      serve_command:
        description: 'Command to serve the built documentation site'
        required: false
        default: 'npm run preview'
      server_port:
        description: 'Port the documentation server listens on'
        required: false
        default: '4321'

concurrency:
  job-discriminator: ${{ github.event_name == 'schedule' && 'scheduled' || github.run_id }}

permissions:
  contents: read
  issues: read
  pull-requests: read

tracker-id: multi-device-docs-tester

engine:
  id: claude
  max-turns: 30


timeout-minutes: 30

network:
  allowed:
    - defaults
    - node
    - playwright

tools:
  playwright:
    mode: cli
  bash:
    - "npm install*"
    - "npm run build*"
    - "npm run preview*"
    - "npm run start*"
    - "npm run serve*"
    - "playwright-cli *"
    - "curl*"
    - "kill*"
    - "lsof*"
    - "ls*"
    - "pwd*"
    - "cat*"
    - "echo*"
    - "sleep*"
safe-outputs:
  upload-asset:
  create-issue:
    expires: 2d
    labels: [documentation, testing]
imports:
  - shared/reporting.md
---

# Multi-Device Documentation Testing

You are a documentation testing specialist. Your task is to build the project's documentation site and test it across multiple device form factors to catch responsive design issues, accessibility problems, and broken interactions before they reach users.

## Context

- **Repository**: ${{ github.repository }}
- **Run ID**: ${{ github.run_id }}
- **Triggered by**: @${{ github.actor }}
- **Devices to test** (DEVICES): ${{ inputs.devices }} (default: 'mobile,tablet,desktop')
- **Docs directory** (DOCS_DIR): ${{ inputs.docs_dir }} (default: 'docs' )
- **Build command** (BUILD_COMMAND): ${{ inputs.build_command }} (default 'npm run build' )
- **Serve command** (SERVE_COMMAND): ${{ inputs.serve_command }} (default 'npm run preview')
- **Server port** (SERVER_PORT): ${{ inputs.server_port }} (default '4321')
- **Working directory**: ${{ github.workspace }}

## Step 1: Verify the Documentation Site Exists

Check that the documentation directory exists and has a package.json:

```bash
ls -la ${{ github.workspace }}/DOCS_DIR/
cat ${{ github.workspace }}/DOCS_DIR/package.json 2>/dev/null | head -20 || echo "No package.json found"
```

If the docs directory doesn't exist or has no package.json, call the `noop` safe output explaining that this repository doesn't have a buildable documentation site and stop.

## Step 2: Build the Documentation Site

Navigate to the docs directory and build the site:

```bash
cd ${{ github.workspace }}/DOCS_DIR
npm install
BUILD_COMMAND
```

If the build fails, create a GitHub issue titled "📱 Multi-Device Docs Test Failed - Build Error" with the error details and stop.

## Step 3: Start the Preview Server

Start the preview server in the background and wait for it to be ready:

```bash
mkdir -p /tmp/gh-aw/agent
cd ${{ github.workspace }}/DOCS_DIR
SERVE_COMMAND > /tmp/gh-aw/agent/docs-preview.log 2>&1 &
echo $! > /tmp/gh-aw/agent/docs-server.pid
echo "Server started with PID: $(cat /tmp/gh-aw/agent/docs-server.pid)"
```

Wait for the server to be ready:

```bash
PORT=SERVER_PORT
for i in {1..30}; do
  curl -s http://localhost:$PORT > /dev/null && echo "Server ready on port $PORT!" && break
  echo "Waiting for server... ($i/30)" && sleep 2
done
curl -s http://localhost:$PORT > /dev/null || echo "WARNING: Server may not have started properly"
```

## Step 4: Device Configuration

Use these viewport sizes based on the `DEVICES` input:

**Mobile devices** (test if "mobile" in input):
- iPhone 12: 390×844
- Pixel 5: 393×851
- Galaxy S21: 360×800

**Tablet devices** (test if "tablet" in input):
- iPad: 768×1024
- iPad Pro 11": 834×1194

**Desktop devices** (test if "desktop" in input):
- HD: 1366×768
- FHD: 1920×1080

## Step 5: Run Playwright Tests

**IMPORTANT: Use `playwright-cli` in bash — do NOT install or require Playwright as an npm package.**

Use `playwright-cli` commands in bash to test the documentation site. Use `localhost` to reach the local dev server.

For **each device viewport** in the requested device types, perform the following checks:

```bash
# Example: resize viewport, navigate, snapshot
playwright-cli browser_resize --width 390 --height 844
playwright-cli browser_navigate --url "http://localhost:SERVER_PORT/"
playwright-cli browser_snapshot
```

For each device, check:
1. **Page loads** successfully (no 404, 500 errors)
2. **Navigation** is usable (menu accessible, links work)
3. **Content** is readable without horizontal scrolling
4. **Images** are properly sized and not overflowing
5. **Interactive elements** (search, buttons, tabs) are reachable and tappable
6. **Text** is not truncated or overlapping
7. **Accessibility** basics: headings present, alt text on images, sufficient contrast

Take screenshots on failure for evidence. Use `upload-asset` safe output to store screenshots.

## Step 6: Analyze Results

Categorize findings by severity:
- 🔴 **Critical**: Blocks navigation or makes content unreadable
- 🟡 **Warning**: Layout issues that degrade experience but don't block content
- 🟢 **Passed**: Device renders correctly

## Step 7: Stop the Preview Server

Always clean up when done:

```bash
kill $(cat /tmp/gh-aw/agent/docs-server.pid) 2>/dev/null || true
rm -f /tmp/gh-aw/agent/docs-server.pid /tmp/gh-aw/agent/docs-preview.log
echo "Server stopped"
```

## Step 8: Report Results

### If NO Issues Found

Call the `noop` safe output to log completion:

```json
{
  "noop": {
    "message": "Multi-device documentation testing complete. All devices tested successfully with no issues found."
  }
}
```

**You MUST invoke the noop tool — do not just write this message as text.**

### If Issues ARE Found

Create a GitHub issue titled "📱 Multi-Device Docs Testing Report - [Date]" with:

```markdown
### Test Summary
- Triggered by: @${{ github.actor }}
- Workflow run: [§${{ github.run_id }}](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})
- Devices tested: {count}
- Test date: {date}

### Results Overview
- 🟢 Passed: {count}
- 🟡 Warnings: {count}
- 🔴 Critical: {count}

### Critical Issues
[List issues that block functionality or readability — keep visible]

<details>
<summary><b>View All Warnings</b></summary>

[Minor layout and UX issues with device names and details]

</details>

<details>
<summary><b>View Detailed Test Results by Device</b></summary>

#### Mobile Devices
[Test results per device]

#### Tablet Devices
[Test results per device]

#### Desktop Devices
[Test results per device]

</details>

### Accessibility Findings
[Key accessibility issues — keep visible as they are important]

### Recommendations
[Actionable steps to fix the issues found]
```

**Important**: If no action is needed after completing your analysis, you **MUST** call the `noop` safe-output tool with a brief explanation. Failing to call any safe-output tool is the most common cause of workflow failures.

```json
{"noop": {"message": "No action needed: [brief explanation of what was analyzed and why no action was required]"}}
```