Diff-Driven QA

QA — Validate Frontend and Backend Changes

Read the diff, classify what changed, and run the right validation path: browser QA for frontend/browser changes, API validation for backend surface changes, repo-native validation for backend-internal changes, and both for mixed changes.

<!-- NOTE: .agents/skills/qa/SKILL.md is the repository canonical source.
     Keep both synchronized copies in sync with it:
     1. skyvern/cli/skills/qa/SKILL.md  (bundled with the pip package)
     2. skyvern/cli/mcp_tools/prompts.py (QA_TEST_CONTENT for the MCP prompt) -->

You changed code. This skill is diff-driven first: it reads what changed, understands the affected behavior, and validates that behavior with the right tools. It is not a generic website crawler, and it should not invent random API checks that are unrelated to the diff.

Quick Start

/qa                              # Diff-based: choose the right validation path automatically
/qa http://localhost:3000        # Same, explicit frontend URL
/qa -- validate the workflow filters API

How It Works

1. Read the code changes from git diff
2. Read the changed files to understand behavior, routes, schemas, and UI
3. Classify the diff as frontend/browser, backend API, backend-internal, or mixed
4. Run the right validation flow
5. Report pass/fail with concrete evidence

Step 1: Understand the Changes

Get the diff

# What files changed?
git diff --name-only HEAD~1     # vs last commit (if changes are committed)
git diff --name-only            # vs working tree (if uncommitted)

# Full diff for context
git diff HEAD~1                 # or git diff for uncommitted

Pick whichever diff has content. If both are empty, there is nothing diff-driven to QA.

Read the changed files

Read the full contents of every changed file that affects behavior:

• Frontend files: .tsx, .jsx, .ts, .js, .css, .html
• Backend/API files: routes, controllers, request/response schemas, serializers, handlers
• Backend-internal files: services, workers, business logic, validators, data-layer code
• Tests that changed alongside the implementation

Look for:

• route paths and page entry points
• component names, visible text, forms, buttons, error states
• API endpoints, request params, response fields, auth requirements
• validation logic, branching behavior, feature flags, empty states
• tests that describe the expected behavior

Step 2: Classify the Diff

Use these rules:

• If both frontend/browser and backend changed, treat it as Mixed.
• If only backend internals changed, do not invent unrelated browser tests or random API calls.
• If a backend change might affect the public contract, inspect routes, schemas, and tests before choosing backend-internal.
• If the diff is mostly documentation or comments, keep QA lightweight and report that no behavioral validation was warranted.

Step 3: Choose the Validation Strategy

Frontend/browser mode

Use browser automation against the dev server. Validate the specific UI changes plus 1-2 adjacent regression checks.

Backend API mode

Use the repo's documented local startup and auth instructions, start the backend if needed, identify the changed endpoint(s), and run targeted HTTP requests to validate the changed contract.

Backend-internal mode

Run the repo's fast verification commands first, then targeted unit/integration/scenario tests for the changed logic. Only start the backend and do live API calls if the change affects exposed behavior.

Mixed mode

Validate the backend first, then run frontend/browser QA against the flow that depends on it. If the backend contract is broken, frontend results are not trustworthy.

Step 4A: Frontend/Browser QA

Find the dev server

If the user provided a URL, use it. Otherwise auto-detect common local ports:

5173, 3000, 3001, 8080, 8000, 4200

If none respond, start the most direct repo-documented local command for the changed surface. If the diff needs both frontend and backend running together and the repo provides a combined frontend/backend dev script, prefer that. Only ask the user to start something manually if the repo has no documented command or startup fails.

Connect to a browser

Try these in order:

Option A: Local browser (fastest)

skyvern_browser_session_create(local=true, headless=false, timeout=15)

Use local=true so the browser can reach localhost.

Option B: Local browser via tunnel

If local session creation fails because the MCP server is remote, the cloud browser cannot reach localhost. Tell the user to run:

# Terminal 1: Launch a local browser with CDP exposed
skyvern browser serve --port 9222

# Terminal 2: Tunnel it to the internet
ngrok http 9222

Then connect:

skyvern_browser_session_connect(cdp_url="wss://<ngrok-subdomain>.ngrok-free.app/devtools/browser/<id>")

The user can get the browser ID from the skyvern browser serve output or by calling the ngrok URL's /json endpoint.

Option C: Cloud browser

skyvern_browser_session_create(timeout=15)

Only works for publicly reachable URLs. localhost URLs will not work here.

Generate frontend/browser test cases

For each changed frontend file, create targeted checks. Examples:

Test 1: Settings page renders the new "Retry failed run" button
  - Navigate to /settings/runs
  - Assert: button with text "Retry failed run" exists
  - Click it
  - Assert: success toast appears

Test 2: Adjacent regression
  - Verify the existing "Delete run" action still works or is still visible

Be specific. Do not write "verify the page works."

Run the frontend/browser tests

For each test case:

skyvern_navigate(url="http://localhost:<port>/<route>")

Health gate after navigation:

In extension mode, use this health gate. Do not call skyvern_evaluate. Before each skyvern_navigate to a route under test, call skyvern_get_errors(clear=True), skyvern_console_messages(clear=True), skyvern_handle_dialog(clear=True), and skyvern_network_requests(clear=True); discard what they return.

skyvern_tab_list()
skyvern_get_errors()
skyvern_console_messages(level="error")
skyvern_get_html(selector="body")
skyvern_find(by="role", value="alert")
skyvern_find(by="role", value="dialog")
skyvern_handle_dialog()

PASS requires the active tab URL to match the expected route, with no unexpected login redirect. The body must contain the expected page content, not only scripts or an empty app container. Require no unexpected error text, visible alerts, visible dialogs, JavaScript errors, console errors, or JavaScript dialog events. skyvern_handle_dialog reads dialog history; JavaScript dialogs are auto-dismissed by default. If a call fails or evidence is incomplete, record FAIL and stop this test. Do not treat missing evidence as PASS.

Outside extension mode, use this health gate:

skyvern_evaluate(expression="(() => {
  const errors = [];
  const body = document.body?.innerText || '';
  if (body.includes('Something went wrong')) errors.push('error_message');
  if (body.includes('Cannot read properties')) errors.push('js_error_in_ui');
  if (/\\bundefined\\b/.test(body) && !/\\bif\\b|\\btypeof\\b|\\bdocument|tutorial|example/i.test(body) && body.length < 5000) errors.push('undefined_text');
  if (body.includes('connection refused')) errors.push('connection_refused');
  if (/sign.?in|log.?in|auth/i.test(window.location.pathname)) errors.push('auth_redirect');
  if (document.querySelector('[role=\"alert\"]')) errors.push('alert_element');
  if (!document.querySelector('main, [role=\"main\"], nav, header, h1, h2, [class*=\"layout\" i], [class*=\"page\" i], [class*=\"app\" i]'))
    errors.push('blank_page');
  return JSON.stringify({ pass: errors.length === 0, errors });
})()")

In extension mode, use skyvern_find, skyvern_get_html, skyvern_get_value, or skyvern_tab_list for assertions.

skyvern_find(by="role", value="button")
skyvern_get_html(selector="h1")
skyvern_tab_list()

Outside extension mode, prefer deterministic DOM assertions:

skyvern_evaluate(expression="!!document.querySelector('button')")
skyvern_evaluate(expression="document.querySelector('h1')?.textContent?.trim()")
skyvern_evaluate(expression="window.location.pathname")

Use interaction tools when needed:

skyvern_act(prompt="Click the 'Retry failed run' button")
skyvern_act(prompt="Fill the email field with 'test@example.com' and click Submit")
skyvern_validate(prompt="The page shows the success toast and the form is no longer loading")
skyvern_screenshot()

In extension mode, call skyvern_network_requests() and inspect captured requests for failures or HTTP status codes of 400 or greater. If capture is unavailable or incomplete, report the network check as unverified. Outside extension mode, check for failed network requests once per page:

skyvern_evaluate(expression="(() => {
  const entries = performance.getEntriesByType('resource').filter(e => e.responseStatus >= 400);
  return JSON.stringify({ failed: entries.map(e => ({ url: e.name, status: e.responseStatus })).slice(0, 5) });
})()")

Step 4B: Backend API QA

Gather repo-local context first

Before starting the server or sending requests, read the repo's local instructions:

• README, AGENTS.md, CLAUDE.md, Makefile, package.json, pyproject.toml
• existing test files for the changed endpoints
• any docs that describe auth, local ports, or startup commands

Do not guess the startup command if the repo already documents one.

Start the backend if needed

If the backend is not already responding on the expected local port:

1. Start it with the most direct repo-documented local command for the changed surface. If the validation needs both frontend and backend and the repo documents a combined dev environment command, prefer that over inventing separate startup steps.
2. Wait for readiness
3. Confirm the API is reachable before sending validation requests

If the repo requires background processes, start them in the background and keep notes on how you did it.

Identify the changed API surface

Use the diff to answer:

• Which endpoints changed?
• Which request parameters, headers, or bodies changed?
• Which response fields or status codes changed?
• Did auth requirements change?
• Is there a create/update/delete side effect that needs follow-up verification?

Do not stop at the route file. Read the full handler, schema, and any changed tests.

Generate backend API test cases

For each changed endpoint, create targeted checks:

• Happy path with valid parameters
• Empty result or not-found path where applicable
• Invalid input or validation error path
• Combined filters or sorting behavior when relevant
• Follow-up read after mutation endpoints

Examples:

Test 1: GET /api/runs returns the new field in the response body
Test 2: GET /api/runs?status=missing returns an empty list, not a 500
Test 3: POST /api/runs rejects invalid payload with a 4xx validation error
Test 4: PATCH /api/runs/:id updates the record and a follow-up GET shows the change