starter-workflows/agentic/daily-multi-device-docs-tester.md

name, description, on, permissions, tracker-id, engine, timeout-minutes, network, tools, safe-outputs, imports

name	description	on	permissions	tracker-id	engine	timeout-minutes	network	tools	safe-outputs	imports
Multi-Device Docs Tester	Tests a documentation site for responsive layout issues, accessibility problems, and broken interactions across mobile, tablet, and desktop device form factors	schedule workflow_dispatch daily inputs devices docs_dir build_command serve_command server_port description required default Device types to test (comma-separated: mobile,tablet,desktop) false mobile,tablet,desktop description required default Directory containing the documentation site (relative to repository root) false docs description required default Command to build the documentation site false npm run build description required default Command to serve the built documentation site false npm run preview description required default Port the documentation server listens on false 4321	contents issues pull-requests read read read	daily-multi-device-docs-tester	id max-turns claude 30	30	allowed defaults node	playwright bash version v1.56.1 npm install* npm run build* npm run preview* npm run start* npm run serve* npx playwright* curl* kill* lsof* ls* pwd* cat* echo* sleep*	upload-asset create-issue expires labels 2d documentation testing	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:

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:

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:

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

Wait for the server to be ready:

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 via MCP tools only — do NOT install or require Playwright as an npm package.

Use Playwright MCP tools (e.g., mcp__playwright__browser_navigate, mcp__playwright__browser_run_code, mcp__playwright__browser_snapshot) to test the documentation site.

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

// Example: set viewport, navigate, snapshot
mcp__playwright__browser_run_code({
  code: `async (page) => {
    await page.setViewportSize({ width: 390, height: 844 });
    await page.goto('http://localhost:SERVER_PORT/');
    return { url: page.url(), title: await page.title() };
  }`
})

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:

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

Step 8: Report Results

If NO Issues Found

Call the noop safe output to log completion:

{
  "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:

### 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.

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