How to Capture Visual QA Evidence with AI Agents

bash
# Baseline — current production
curl -G "https://screenshotapi.to/api/v1/screenshot" \
  -d "url=https://example.com/pricing" \
  -d "type=png" \
  -d "fullPage=true" \
  -H "x-api-key: sk_live_your_key_here" \
  --output before.png

# After — the preview deployment
curl -G "https://screenshotapi.to/api/v1/screenshot" \
  -d "url=https://pr-482.preview.example.com/pricing" \
  -d "type=png" \
  -d "fullPage=true" \
  -H "x-api-key: sk_live_your_key_here" \
  --output after.png

javascript
import fs from 'node:fs/promises';

async function captureQA(url, outPath, { fullPage = true, width, height } = {}) {
  const params = new URLSearchParams({ url, type: 'png', fullPage: String(fullPage) });
  if (width) params.set('width', String(width));
  if (height) params.set('height', String(height));

  const res = await fetch(
    `https://screenshotapi.to/api/v1/screenshot?${params}`,
    { headers: { 'x-api-key': process.env.SCREENSHOT_API_KEY } }
  );

  if (!res.ok) {
    const { message, fix } = await res.json();
    throw new Error(`Capture failed: ${message}${fix ? ` — ${fix}` : ''}`);
  }

  await fs.writeFile(outPath, Buffer.from(await res.arrayBuffer()));
  return {
    id: res.headers.get('x-screenshot-id'),
    cache: res.headers.get('x-cache'),
    creditsRemaining: Number(res.headers.get('x-credits-remaining')),
  };
}

// Before and after, saved as artifacts
await captureQA('https://example.com/pricing', 'before.png');
const after = await captureQA('https://pr-482.preview.example.com/pricing', 'after.png');
console.log(`Saved after.png (${after.id}), ${after.creditsRemaining} credits left`);

bash
# Desktop
curl -G "https://screenshotapi.to/api/v1/screenshot" \
  -d "url=https://pr-482.preview.example.com" \
  -d "width=1440" \
  -d "height=900" \
  -d "fullPage=true" \
  -H "x-api-key: sk_live_your_key_here" \
  --output desktop.png

# Mobile
curl -G "https://screenshotapi.to/api/v1/screenshot" \
  -d "url=https://pr-482.preview.example.com" \
  -d "width=390" \
  -d "height=844" \
  -d "devicePixelRatio=2" \
  -d "fullPage=true" \
  -H "x-api-key: sk_live_your_key_here" \
  --output mobile.png

python
import requests

API = "https://screenshotapi.to/api/v1/screenshot"
HEADERS = {"x-api-key": "sk_live_your_key_here"}
URL = "https://pr-482.preview.example.com"

viewports = {
    "desktop.png": {"width": 1440, "height": 900},
    "mobile.png": {"width": 390, "height": 844, "devicePixelRatio": 2},
}

for out, vp in viewports.items():
    res = requests.get(API, params={"url": URL, "type": "png", "fullPage": "true", **vp}, headers=HEADERS)
    res.raise_for_status()
    with open(out, "wb") as f:
        f.write(res.content)
    print(out, res.headers.get("x-cache"), res.headers.get("x-credits-remaining"))

text
Goal: capture visual QA evidence for the preview deployment.

1. Capture the preview URL at desktop (width=1440, height=900) and mobile (width=390, height=844, devicePixelRatio=2).
2. Always use fullPage=true so the whole page is in frame.
3. Save each capture as a named artifact (e.g. desktop.png, mobile.png) and attach them to the review.
4. Inspect and report: visible differences vs. the baseline, clipping or content cut off, layout overflow, broken or missing images, and unreadable or overlapping text.
5. If a capture returns a 500, read the "fix" field and retry once (e.g. waitUntil=networkidle0 or stealthMode=true).
6. Do NOT capture unauthorized, private-network, or localhost URLs with the hosted API. For local-only UI, use a local browser tool instead.

json
{
  "name": "capture_qa_screenshot",
  "description": "Capture a full-page screenshot of a public or preview URL as visual QA evidence. Use only for deployed/preview URLs, never localhost or private networks.",
  "parameters": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "Public or preview URL to capture (https://...)."
      },
      "viewport": {
        "type": "string",
        "enum": ["desktop", "mobile"],
        "description": "desktop = 1440x900; mobile = 390x844 @2x.",
        "default": "desktop"
      },
      "fullPage": {
        "type": "boolean",
        "description": "Capture the entire scrollable page.",
        "default": true
      }
    },
    "required": ["url"]
  }
}

yaml
name: Visual QA evidence
on: pull_request

jobs:
  capture:
    runs-on: ubuntu-latest
    steps:
      - name: Capture preview screenshots
        env:
          SCREENSHOT_API_KEY: ${{ secrets.SCREENSHOT_API_KEY }}
          PREVIEW_URL: ${{ steps.deploy.outputs.preview-url }}
        run: |
          curl -G "https://screenshotapi.to/api/v1/screenshot" \
            -d "url=${PREVIEW_URL}" -d "fullPage=true" -d "width=1440" -d "height=900" \
            -H "x-api-key: ${SCREENSHOT_API_KEY}" --fail --output desktop.png
          curl -G "https://screenshotapi.to/api/v1/screenshot" \
            -d "url=${PREVIEW_URL}" -d "fullPage=true" -d "width=390" -d "height=844" -d "devicePixelRatio=2" \
            -H "x-api-key: ${SCREENSHOT_API_KEY}" --fail --output mobile.png

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: visual-qa
          path: |
            desktop.png
            mobile.png

json
{
  "error": "render_failed",
  "message": "Navigation timed out before the page settled.",
  "fix": "Retry with waitUntil=networkidle0, or add stealthMode=true if the site blocks bots."
}