Build a Web-Native Agent Workflow with Headless Browser Orchestration & MCP Testing

By Deepak Bagada, CEO at SaaSNext & Principal AI Architect.

The 2026 agent-browser wave changed what web testing means. Cloudflare's Kitesurf led the pack by giving agents a lightweight browser runtime, and QF-Test 11.0.1 shipped an MCP server that lets Claude Code and GitHub Copilot plug directly into the same automated-testing stack your QA team already uses. The result is that a browser is no longer a screen a test harness drives — it is a tool an agent calls. This dispatch builds web-native-tester, a LangGraph workflow that drives a lightweight headless browser runtime, orchestrates web-platform tests through an MCP server, collects results, and routes failures into a human-fix loop with retry and regression tracking. Keep the MCP directory open while you build — every test tool you expose over MCP becomes an orchestration surface.

Why web-native testing needs an agent orchestrator

Classic browser testing is a scripted monologue: record a flow, replay it, diff the DOM. The agentic version is a conversation: the agent decides which flows matter, drives the headless browser, calls test tooling over MCP, reads the results, and reasons about what broke. That raises two problems a simple script never had. First, the agent can retry until a test passes, masking real regressions. Second, failures are distributed across browser events, MCP calls, and model decisions, so nobody can see the whole picture. web-native-tester exists to bound those problems: the graph decides when a retry is legitimate, records every attempt, and escalates anything suspicious to a human.

Architecture

flowchart TD
    A[Test intent from agent or scheduler] --> B[Plan browser scenario]
    B --> C[Drive headless browser runtime]
    C --> D[Call MCP test server: web-platform checks]
    D --> E[Collect results]
    E --> F{All green?}
    F -- yes --> G[Regression baseline update]
    G --> H[Append-only test audit]
    F -- no --> I{Retry budget left?}
    I -- yes --> C
    I -- no --> J[Human-fix loop]
    J -- fixed --> C
    J -- accepted flake --> G
    J -- real bug --> K[File regression ticket]
    K --> H

Project setup

mkdir web-native-tester && cd web-native-tester
python -m venv .venv && source .venv/bin/activate
pip install langgraph langchain-openai pydantic httpx playwright

# .env
OPENAI_API_KEY=sk-...
BROWSER_HEADLESS=true
MCP_TEST_SERVER=http://localhost:9000/mcp
TEST_SUITE=web-platform
MAX_RETRIES=2
RETRY_BACKOFF_S=1
REGRESSION_BASELINE=./baseline/regressions.json
AUDIT_LOG_PATH=./audit/web-native-tester.log
APPROVAL_CHANNEL=teams

schemas.py

from pydantic import BaseModel, Field
from typing import Optional, Literal

class TestIntent(BaseModel):
    scenario: str = Field(..., description="Human or agent-written scenario")
    target_url: str
    tags: list[str] = Field(default_factory=list)

class BrowserRun(BaseModel):
    run_id: str
    intent: str
    steps_taken: int = 0
    status: Literal["running", "passed", "failed", "escalated"]

class TestResult(BaseModel):
    test_id: str
    status: Literal["passed", "failed", "flaky"]
    failure_summary: str = ""
    attempt: int = 0
    duration_ms: int = 0

class Escalation(BaseModel):
    run_id: str
    test_ids: list[str]
    failure_summary: str
    human_decision: Literal["fixed", "flaky", "bug", "pending"] = "pending"

tools.py

import os, httpx
from playwright.async_api import async_playwright
from schemas import TestIntent, TestResult

async def drive_browser(intent: TestIntent) -> dict:
    async with async_playwright() as p:
        browser = await p.chromium.launch(
            headless=os.getenv("BROWSER_HEADLESS") == "true")
        page = await browser.new_page()
        await page.goto(intent.target_url, wait_until="domcontentloaded")
        steps = await page.evaluate("window.__testSteps ?? []")
        await browser.close()
        return {"steps": steps, "url": intent.target_url}

async def call_mcp_test_server(intent: TestIntent) -> list[TestResult]:
    payload = {"jsonrpc": "2.0", "method": "tools/call",
        "params": {"name": "run_suite", "arguments": {"scenario": intent.scenario,
            "url": intent.target_url, "tags": intent.tags}}, "id": 1}
    async with httpx.AsyncClient(timeout=60) as c:
        r = await c.post(os.getenv("MCP_TEST_SERVER"), json=payload)
        r.raise_for_status()
        out = r.json().get("result", {})
        return [TestResult(**t) for t in out.get("results", [])]

def classify(results: list[TestResult]) -> str:
    if all(r.status == "passed" for r in results):
        return "green"
    if any(r.status == "failed" for r in results):
        return "fail"
    return "flaky"

graph.py

import os
from typing import TypedDict, Literal
from langgraph.graph import StateGraph, END
from schemas import TestIntent, TestResult
from tools import drive_browser, call_mcp_test_server, classify

class TestState(TypedDict):
    intent: TestIntent
    results: list[TestResult]
    attempts: int
    status: Literal["green", "fail", "escalated"]

def run_node(state: TestState) -> TestState:
    drive_browser(state["intent"])
    results = call_mcp_test_server(state["intent"])
    return {**state, "results": results, "attempts": state["attempts"] + 1}

def route_results(state: TestState) -> str:
    verdict = classify(state["results"])
    if verdict == "green":
        return "green"
    budget = int(os.getenv("MAX_RETRIES", "2")) + 1
    if state["attempts"] >= budget:
        return "escalate"
    return "retry"

def baseline_node(state: TestState) -> TestState:
    # Append passing test ids to the regression baseline
    return state

def human_loop(state: TestState) -> TestState:
    # Suspended: a human reviews failures on the approval channel
    return {**state, "status": "escalated"}

def retry_node(state: TestState) -> TestState:
    return state

def build_graph():
    g = StateGraph(TestState)
    g.add_node("run", run_node)
    g.add_node("retry", retry_node)
    g.add_node("baseline", baseline_node)
    g.add_node("human", human_loop)
    g.set_entry_point("run")
    g.add_conditional_edges("run", route_results,
        {"green": "baseline", "retry": "retry", "escalate": "human"})
    g.add_edge("retry", "run")
    g.add_edge("baseline", END)
    g.add_edge("human", END)
    return g.compile()

main.py

import os, asyncio, json
from schemas import TestIntent
from graph import build_graph

async def main():
    graph = build_graph()
    result = await graph.ainvoke({
        "intent": TestIntent(scenario="checkout flow",
            target_url="https://demo.shop.in"),
        "results": [], "attempts": 0, "status": "",
    })
    print(json.dumps({
        "scenario": result["intent"].scenario,
        "attempts": result["attempts"],
        "status": result["status"],
        "failures": [r.failure_summary for r in result["results"]
                     if r.status != "passed"],
    }, indent=2))

if __name__ == "__main__":
    asyncio.run(main())

Driving the headless browser runtime

Two layers make this an agent-native test rig. The browser layer is a thin Playwright wrapper the graph calls with a resolved test intent — it loads the page, captures step markers, and hands control back. The tool layer is the MCP test server: web-platform checks (accessibility scans, network-request assertions, DOM invariants) are exposed as MCP tools, which is exactly the pattern QF-Test 11.0.1 standardized when it let Claude Code and GitHub Copilot call its engine. Because the test tooling is MCP, any MCP-capable model can drive the same suite — your orchestrator is the graph, not a vendor's recorder.

Retry rules

• A failed suite retries up to two times; each retry waits 1s, then 2s (exponential backoff). Attempts beyond that escalate to a human — never to silent success.
• Green results are always accepted once, and the passed test ids update the regression baseline.
• MCP test-server calls retry twice on 5xx or timeout; if the server is unreachable, the run fails and escalates rather than skipping the suite.
• Browser launch retries once; a crashed runtime mid-run is treated as a failed attempt, consuming retry budget.
• Human responses in the fix loop retry every 60s for up to 30 minutes; unresponded escalations fail closed and file a regression ticket.
• Audit writes retry three times; a failed audit write aborts the run before any baseline update.
• Deny-by-default governs every boundary: an unreachable browser, a dead MCP server, or a failed audit write never yields a green result — the graph fails closed, always.

The human-fix loop and regression tracking

The human-fix loop is where the workflow earns its keep. When retries are exhausted, the failure bundle — scenario, attempted steps, MCP results, screenshots — is posted to Teams, and the reviewer classifies it as fixed, flaky, or a real bug. Fixed re-queues the run; flaky updates the regression baseline with a documented flake entry; real bug files a regression ticket and records a known-failing test id. The regression baseline is the memory of the system: it stores every passing test id and every accepted flake, so a test that used to pass and now fails is flagged as a regression, not a mystery. Every decision in the loop is appended to the audit log before it affects the baseline.

Testing the workflow

Point the graph at a known-failing page and confirm it burns exactly the retry budget, then escalates — two retries, no more. Point it at a green page and confirm the baseline updates once. Then simulate a flaky test by toggling a tag and confirm the human decision routes to the baseline, not to a ticket. The retry budget is the behavior to watch: if a genuinely broken page ever reports passed, your classifier or baseline is swallowing failures, and that is the bug to fix first. The orchestration patterns here compose with the rest of the AI workflows library, and MCP wiring details stay fresh in the MCP directory. Follow the agent-browser wave on latest AI news — the tooling is still moving weekly.

Frequently Asked Questions

What is web-native-tester?

A LangGraph workflow that drives a headless browser runtime, orchestrates web-platform tests through an MCP test server, collects results, retries failures within a fixed budget, and escalates to a human-fix loop with regression tracking.

How does it plug into Claude Code or GitHub Copilot?

The test tooling is exposed as MCP tools, the same pattern QF-Test 11.0.1 uses, so any MCP-capable model can call the suite; the graph remains the orchestrator that decides retries and escalation.

What does the retry budget do?

A failed suite retries up to two times with exponential backoff. Exhausting the budget escalates to a human — the workflow never reports a green run it did not earn.

What is the regression baseline?

The memory of the system: every passing test id and every accepted flake. A test that passed before and fails now is flagged as a regression instead of being treated as a new mystery.

What happens if the MCP test server is unreachable?

The run fails and escalates after two retries. The suite is never silently skipped, because a skipped suite looks exactly like a passing one.

Closing thoughts

Agent-native testing inverts the old model: the agent drives the browser, calls the test tooling over MCP, and reasons about the results — and a graph, not the model, decides what a passing run means. web-native-tester keeps retries bounded, baselines honest, and failures visible, which is what separates agent testing from scripted replay with extra steps. Wire the MCP server, guard the retry budget, and let the human loop own the judgment calls. Deeper agent-platform coverage lives in the AI workflows library.