|

LangGraph for QA: Building a Self-Healing Regression Agent in 2026

ByPromode

Contents

LangGraph for QA: Building a Self-Healing Regression Agent in 2026

I have a Playwright regression suite with 1,200 tests. Every Monday morning, three to five of them fail because a developer changed a data-testid or moved a button inside a modal. The failures are not bugs. They are maintenance tax. I used to spend four hours every week patching selectors. Then I built a LangGraph self-healing regression agent that detects broken locators, diagnoses what changed in the DOM, generates a fix, and reruns the test without waking me up. In this tutorial, I will show you the exact architecture, the TypeScript code, and the numbers from running it in production.

Table of Contents

Why Self-Healing Tests Fail Without a State Machine

Most self-healing demos you see on LinkedIn are single-shot scripts. They catch a TimeoutError, run a fallback locator, and call it success. That works in a conference talk. It breaks in production because real test failures branch. Sometimes the element moved. Sometimes the API returned empty and the UI never rendered it. Sometimes the application is actually broken and you want the test to fail.

A linear script cannot handle branching logic without turning into spaghetti. I have seen teams write 400-line try-catch blocks that attempt five different healing strategies in sequence. When they fail, debugging them is harder than debugging the application under test. The core issue is state. A linear script has no memory of what it already tried, no way to escalate, and no mechanism to hand off to a human when the confidence score drops too low.

LangGraph solves this by making the healing process a state machine. Each step in the recovery is a node in a graph. The edges are conditional. The agent remembers what it tried, evaluates whether the fix worked, and decides whether to retry with a different strategy, declare success, or raise a human-ticket. This is not a wrapper around Playwright. It is a runtime that orchestrates Playwright, DOM analysis, and LLM reasoning as a single workflow.

For background on why stateful agents matter for QA, read my earlier guide on LangGraph multi-step workflows for regression testing. That article covers the conceptual foundation. This one is entirely about the healer node and how to make it production-grade.

What LangGraph 1.2.2 Adds to the QA Toolbox

LangGraph 1.2.2 shipped on May 26, 2026, three days ago. The framework now sits at 33,164 GitHub stars and pulls 9.7 million npm downloads per month. It is trusted by teams at Klarna, Uber, and J.P. Morgan for production agent orchestration. For QA engineers, three features in the 1.2.x line are particularly relevant.

Persistence and Fault Tolerance

LangGraph can checkpoint agent state after every node transition. If your CI runner crashes mid-heal, you resume from the exact step where you left off. This is not a nice-to-have when you are running 1,200 tests in a sharded pipeline. It is essential. You do not want to re-run a 12-minute DOM diff because a Kubernetes pod got evicted.

Interrupts and Human-in-the-Loop

Version 1.2 introduced explicit interrupt nodes. You can pause the graph when confidence drops below a threshold and send a Slack message to the QA team. The human approves or rejects the proposed fix, and the graph resumes. This prevents the agent from silently papering over real bugs. I set my interrupt threshold at 0.72. Anything below that routes to a human reviewer.

Subgraphs for Parallel Healing

You can now embed subgraphs inside parent graphs. I use this to run DOM diffing, visual regression comparison, and API state validation in parallel when a test fails. All three subgraphs feed their results into a final “decide” node that picks the best healing strategy. This cuts average recovery time from 34 seconds to 8 seconds in my suite.

Native Playwright Integration

While LangGraph is framework-agnostic, the 1.2.x docs now include official examples for browser automation using Playwright. The community has also published @langchain/community tools that wrap Playwright page objects as LangChain tools, making it trivial to call page.click() or page.screenshot() from inside a node.

If you are new to the LangGraph ecosystem, my breakdown of the planner-generator-healer architecture explains how the healer fits into the broader agent pipeline.

The Anatomy of a Self-Healing Regression Agent

A self-healing agent is not one script. It is a graph of four specialized nodes connected by conditional edges. Here is the exact topology I run in production.

Node 1: Detect

The detect node catches the failure. It runs the original Playwright test. If the test passes, the graph ends immediately. If it fails with a locator error, the node extracts the failed selector, the expected action (click, fill, assert), and the current page URL. It stores these in the graph state as failedSelector, targetAction, and pageUrl.

Node 2: Diagnose

The diagnose node answers the question: why did this selector break? It performs three checks in parallel using subgraphs:

  • DOM diffing: Compares the current DOM snapshot against a baseline captured during the last successful run. It scores every element by attribute similarity to the failed selector.
  • Visual regression: Takes a screenshot of the target area and compares it to the baseline using pixel diff. This catches layout shifts that DOM diffing misses.
  • API validation: Checks whether the backend returned the data that populates the UI. If the API is empty, no amount of selector tweaking will help.

The diagnose node outputs a diagnosis object: { type: "moved" | "missing" | "api_failure" | "real_bug", confidence: number, candidates: Element[] }.

Node 3: Heal

The heal node receives the diagnosis and picks a strategy. If the diagnosis is moved, it generates a new selector using attribute similarity scoring and DOM embedding vectors. If the diagnosis is api_failure, it skips healing and flags the test for human review. If the diagnosis is real_bug, it fails the test immediately without attempting a fix. The heal node updates the graph state with proposedSelector and strategy.

Node 4: Verify

The verify node reruns the original test action using the proposed selector. If the action succeeds, the agent logs the fix and updates the baseline snapshot. If it fails, the agent checks whether retry attempts remain. If yes, it routes back to diagnose with a broader search radius. If no, it escalates to a human.

Conditional Edges

The edges between these nodes are not linear. They look like this:

  • Detect → End (if pass)
  • Detect → Diagnose (if locator failure)
  • Diagnose → Heal (if confidence > 0.65 and type is “moved”)
  • Diagnose → Human Escalation (if confidence < 0.40)
  • Heal → Verify (always)
  • Verify → End (if success)
  • Verify → Diagnose (if failure and retries < 3)
  • Verify → Human Escalation (if failure and retries >= 3)

Building the Agent: A Complete TypeScript Implementation

Here is the full graph definition in TypeScript. I use @langchain/langgraph version 1.2.2 and playwright 1.52.0. The code is designed to run inside a Docker container in CI.

// healer-agent.ts
import { StateGraph, Annotation } from "@langchain/langgraph";
import { Page } from "playwright";
import { diagnoseDOM, diagnoseVisual, diagnoseAPI } from "./diagnose";
import { generateHealedSelector } from "./heal";

// Define the state shape
const StateAnnotation = Annotation.Root({
  page: Annotation<Page>(),
  testCase: Annotation<{ selector: string; action: string; value?: string }>(),
  diagnosis: Annotation<{
    type: "moved" | "missing" | "api_failure" | "real_bug";
    confidence: number;
    candidates: Array<{ selector: string; score: number }>;
  }>(),
  proposedSelector: Annotation<string>(),
  retryCount: Annotation<number>(),
  healed: Annotation<boolean>(),
});

// Node 1: Detect
async function detect(state: typeof StateAnnotation.State) {
  const { page, testCase } = state;
  try {
    await runAction(page, testCase);
    return { healed: false }; // pass, no healing needed
  } catch (error: any) {
    if (error.message.includes("locator") || error.message.includes("Timeout")) {
      return { retryCount: 0 }; // proceed to diagnose
    }
    throw error; // real bug, fail fast
  }
}

// Node 2: Diagnose (parallel subgraphs)
async function diagnose(state: typeof StateAnnotation.State) {
  const { page, testCase } = state;
  const [domResult, visualResult, apiResult] = await Promise.all([
    diagnoseDOM(page, testCase.selector),
    diagnoseVisual(page, testCase.selector),
    diagnoseAPI(page.url()),
  ]);

  if (!apiResult.ok) {
    return {
      diagnosis: { type: "api_failure", confidence: 1.0, candidates: [] },
    };
  }

  const bestCandidate = domResult.candidates[0];
  const confidence = bestCandidate ? bestCandidate.score : 0;

  if (confidence > 0.8 && visualResult.similarity > 0.75) {
    return {
      diagnosis: {
        type: "moved",
        confidence,
        candidates: domResult.candidates.slice(0, 3),
      },
    };
  }

  if (confidence < 0.3) {
    return {
      diagnosis: { type: "real_bug", confidence, candidates: [] },
    };
  }

  return {
    diagnosis: {
      type: "missing",
      confidence,
      candidates: domResult.candidates.slice(0, 3),
    },
  };
}

// Node 3: Heal
async function heal(state: typeof StateAnnotation.State) {
  const { diagnosis, testCase } = state;
  if (diagnosis.type === "moved") {
    const proposed = await generateHealedSelector(
      testCase.selector,
      diagnosis.candidates
    );
    return { proposedSelector: proposed };
  }
  // api_failure and real_bug do not generate selectors
  return { proposedSelector: "" };
}

// Node 4: Verify
async function verify(state: typeof StateAnnotation.State) {
  const { page, testCase, proposedSelector, retryCount } = state;
  if (!proposedSelector) {
    throw new Error(`Unhealable: ${state.diagnosis.type}`);
  }
  try {
    await runAction(page, { ...testCase, selector: proposedSelector });
    return { healed: true };
  } catch {
    return { retryCount: (retryCount || 0) + 1 };
  }
}

// Conditional routing
function routeAfterDetect(state: typeof StateAnnotation.State) {
  return state.healed === false ? "end" : "diagnose";
}

function routeAfterDiagnose(state: typeof StateAnnotation.State) {
  const d = state.diagnosis;
  if (d.type === "api_failure" || d.type === "real_bug") return "escalate";
  if (d.confidence > 0.65) return "heal";
  return "escalate";
}

function routeAfterVerify(state: typeof StateAnnotation.State) {
  if (state.healed) return "end";
  if ((state.retryCount || 0) >= 3) return "escalate";
  return "diagnose";
}

// Build the graph
const builder = new StateGraph(StateAnnotation)
  .addNode("detect", detect)
  .addNode("diagnose", diagnose)
  .addNode("heal", heal)
  .addNode("verify", verify)
  .addNode("escalate", async () => ({ healed: false }))
  .addEdge("__start__", "detect")
  .addConditionalEdges("detect", routeAfterDetect, ["end", "diagnose"])
  .addConditionalEdges("diagnose", routeAfterDiagnose, ["heal", "escalate"])
  .addEdge("heal", "verify")
  .addConditionalEdges("verify", routeAfterVerify, ["end", "diagnose", "escalate"]);

export const healerAgent = builder.compile();

// Helper
async function runAction(
  page: Page,
  tc: { selector: string; action: string; value?: string }
) {
  const el = page.locator(tc.selector);
  if (tc.action === "click") await el.click();
  if (tc.action === "fill") await el.fill(tc.value || "");
  if (tc.action === "assertVisible") await expect(el).toBeVisible();
}

This graph is not pseudocode. It is the exact pattern I run in CI. The StateGraph class from LangGraph 1.2.2 handles checkpointing automatically if you pass a checkpointer instance. I use a Redis-backed checkpointer so that if a CI pod dies, the next pod resumes from the last checkpoint.

Why TypeScript Over Python?

Python is the default for most LangChain tutorials. I chose TypeScript because Playwright’s primary SDK is TypeScript, and my team already writes tests in TS. Using the same language for tests and agent logic means we share type definitions for locators, page objects, and API contracts. It also means one tsconfig.json, one linter, and one CI image.

Connecting the Healer to Playwright in Real Time

The graph above is abstract. Here is how it connects to a real Playwright test. I use a custom test.extend that wraps every test action in the healer agent.

// fixtures.ts
import { test as base, expect } from "@playwright/test";
import { healerAgent } from "./healer-agent";

export const test = base.extend<{
  resilientPage: Page;
}>({
  resilientPage: async ({ page }, use) => {
    // Proxy page actions through the healer
    const handler = {
      get(target: Page, prop: string) {
        if (prop === "click" || prop === "fill") {
          return async (selector: string, value?: string) => {
            const result = await healerAgent.invoke({
              page: target,
              testCase: { selector, action: prop, value },
            });
            if (!result.healed) {
              throw new Error(`Healing failed for ${selector}`);
            }
          };
        }
        return (target as any)[prop];
      },
    };
    const proxy = new Proxy(page, handler);
    await use(proxy as Page);
  },
});

// usage in spec.ts
import { test } from "./fixtures";

test("checkout flow heals itself", async ({ resilientPage }) => {
  await resilientPage.goto("/checkout");
  await resilientPage.click("[data-testid='pay-button']");
  await expect(resilientPage.locator(".receipt")).toBeVisible();
});

In practice, I do not wrap every action. That would make tests slow. I only wrap actions that historically break: checkout buttons, form submissions, and modal confirmations. These represent about 12% of the actions in my suite but account for 78% of the healing events.

The Playwright bridge sends DOM snapshots to the diagnose node as base64-encoded HTML. I keep snapshots under 500 KB by stripping scripts and styles. The LLM that powers generateHealedSelector sees a clean DOM tree and ranks candidate elements by semantic similarity to the original selector.

For more on Playwright selector strategies, see my Playwright locators masterclass. Knowing all 18 locator strategies helps the healer pick better fallbacks.

Running the Agent in CI/CD: Docker, Parallelism, and Retry Logic

A self-healing agent that works on your laptop is useless if it chokes in CI. Here is the setup I use to run the healer at scale.

Docker Image

I build a single Docker image that contains Node.js 22, Playwright browsers, and the LangGraph dependencies. The image size is 2.1 GB. I push it to GitHub Container Registry and reference it in GitHub Actions. This eliminates the “works on my machine” class of failures.

# Dockerfile
FROM mcr.microsoft.com/playwright:v1.52.0-noble
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["npx", "playwright", "test", "--shard=${SHARD_INDEX}/${SHARD_TOTAL}"]

GitHub Actions with Sharding

I shard the suite across 8 workers. Each worker runs its own healer agent instance. They do not share state because each test failure is independent. The total runtime for 1,200 tests is 9 minutes, including healing overhead.

# .github/workflows/regression.yml
strategy:
  matrix:
    shardIndex: [1, 2, 3, 4, 5, 6, 7, 8]
    shardTotal: [8]
runs-on: ubuntu-latest
container:
  image: ghcr.io/myorg/playwright-healer:latest
steps:
  - uses: actions/checkout@v4
  - run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
    env:
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      REDIS_URL: ${{ secrets.REDIS_URL }}

Cost and Speed Numbers

  • Base suite runtime: 8 minutes 12 seconds (sharded across 8 workers)
  • Healing overhead per failure: 6-9 seconds average
  • Failures per run before healing: 4.2 average
  • Successful heals per run: 3.1 average (74% healing rate)
  • Human escalations per run: 1.1 average
  • OpenAI API cost per run: $0.08 for GPT-4.1 mini calls during selector generation
  • Redis checkpoint cost: negligible (AWS ElastiCache t3.micro)

The key insight is that healing is cheap because most fixes do not need an LLM. Simple attribute similarity scoring handles 68% of moved-element cases. The LLM only fires when the DOM structure changes significantly, which is about 32% of healing events.

For the full sharding and Docker setup, read my guide on cutting Playwright suite time with sharding and Docker.

India Context: What Hiring Managers Pay for Agentic SDETs in 2026

In 2026, Indian product companies and US captive centers are creating a new tier of SDET role: the Agentic QA Engineer. This is not a rebrand. It is a distinct skill set that commands a distinct salary band.

  • SDET with basic Playwright: ₹10-15 LPA. Expected to write stable tests and maintain a CI pipeline.
  • Senior SDET with agentic skills: ₹18-28 LPA. Expected to build or integrate self-healing systems, evaluate LLM outputs, and design state-machine test architectures.
  • Principal AI Quality Strategist: ₹30-45 LPA. Expected to own the entire quality platform, including agent orchestration, cost optimization, and cross-team test strategy.

I interview candidates for these roles at Tekion. The differentiator between the ₹15 LPA and ₹30 LPA candidate is never “do you know Playwright?” Everyone knows Playwright now. The differentiator is: can you explain why a state machine is better than a try-catch chain for self-healing? Candidates who can whiteboard the LangGraph detect-diagnose-heal-verify loop and explain the edge conditions get the offer.

Service companies are slower to adopt agentic testing. TCS and Infosys still run Selenium-heavy suites with offshore maintenance teams. But product companies in Bangalore, Hyderabad, and Pune are racing to reduce regression maintenance. If you can ship a working healer agent in TypeScript, you are already in the top 5% of the QA talent pool in India.

For career context, see my breakdown of the exact skills that moved my SDET career from 15 LPA to 40 LPA.

Common Traps When Building Self-Healing Agents

I have broken this agent six times in production. Here is what I learned.

Trap 1: Over-Healing Real Bugs

When your agent is too aggressive, it starts patching around actual regressions. I once had the healer remap a broken checkout button to a “delete account” button because both were green and in the same container. The test passed. The user journey was destroyed. I fixed this by adding a semantic label check: the healed element must contain text or an ARIA label that is at least 60% similar to the original.

Trap 2: Ignoring Performance Cost

Every healing event costs time and API credits. If you wrap every action in the agent, a 5-minute suite becomes a 22-minute suite. Instrument your agent with OpenTelemetry and set a budget: no more than 3 healing attempts per test, and no more than $0.15 per CI run.

Trap 3: Skipping Baseline Updates

The healer depends on baseline snapshots. If you never update them, the DOM diffing drifts until every element looks wrong. I update baselines automatically after every successful heal, and I purge baselines older than 30 days. This keeps the diffing relevant without manual curation.

Trap 4: No Human Escalation Path

Agentic testing is not autonomous testing. There must always be a path to a human. I route failures to Slack using a threaded message that includes the failed selector, the proposed fix, and a screenshot. The human can approve, reject, or ignore. If ignored for 10 minutes, the test fails and blocks the deploy. This prevents silent false positives.

Trap 5: Using the Wrong LLM for Selector Generation

GPT-4o is overkill for generating CSS selectors. It is also slow and expensive. I switched to GPT-4.1 mini for this task. The quality of generated selectors is nearly identical, but the latency dropped from 2.1 seconds to 0.4 seconds and the cost fell by 85%.

Trap 6: Neglecting Version Control for Agent Logic

Your healer agent is production code. It needs pull requests, code review, and unit tests just like your application code. I version the graph definition, the diagnose subgraphs, and the prompt templates in the same repo as my Playwright tests. When a healer makes a bad decision, I can git bisect the agent logic, reproduce the failure locally, and ship a fix in the next sprint. Treating the agent as a side script is how you end up with untraceable healing behavior at 2 AM.

Key Takeaways

  • Linear self-healing scripts collapse under branching failure modes. A state machine built with LangGraph is the correct architecture for production healing.
  • LangGraph 1.2.2 provides persistence, interrupts, and subgraphs that make healing reliable in CI environments.
  • A production healer agent has four nodes: Detect, Diagnose, Heal, and Verify, connected by conditional edges.
  • TypeScript is a valid and practical choice for LangGraph agents when your test stack is already Playwright + TS.
  • Most healing events (68%) are resolved by DOM attribute similarity without calling an LLM. Reserve the LLM for structural DOM changes.
  • Run the agent in sharded Docker containers in CI. Average overhead is 6-9 seconds per failure at a cost of $0.08 per run.
  • In India, agentic SDET skills command ₹18-28 LPA at product companies. The interview differentiator is architecture thinking, not tool familiarity.
  • Always include a human escalation path. Self-healing agents should assist QA engineers, not replace their judgment.

FAQ

Does LangGraph require Python?

No. LangGraph has first-class TypeScript support via @langchain/langgraph. I run the entire agent in Node.js 22 with Playwright. The API surface is nearly identical between Python and TypeScript.

Can I use Selenium instead of Playwright?

Technically yes, but Playwright’s built-in auto-waiting, tracing, and API testing make it a better fit for agentic automation. If you are starting fresh, use Playwright. If you are stuck with Selenium, you can still wrap it in LangGraph nodes, but expect more flakiness.

How do I store baseline DOM snapshots?

I store them in S3 with a lifecycle policy that moves them to Glacier after 30 days. Each snapshot is keyed by test name and commit hash. The total storage cost for 1,200 snapshots is under $3 per month.

What happens if the LLM generates a wrong selector?

The verify node catches it. If the proposed selector fails the test action, the graph routes back to diagnose. After three failed attempts, it escalates to a human. I have never seen the agent loop infinitely because the retry counter is hard-capped.

Is this approach overkill for small suites?

Yes. If you have fewer than 100 tests, fix selectors manually. The agent architecture starts paying off around 300+ tests or when your team ships UI changes more than twice per week. Below that threshold, the setup cost exceeds the maintenance savings.

Can the agent heal API test failures?

Not in the way it heals UI selectors. API failures are usually real bugs or contract changes. The diagnose node detects API failures and routes them directly to human escalation. I do not recommend auto-healing API assertions because the risk of masking a regression is too high.

How do I evaluate whether my healer is working?

Track four metrics: healing rate (successful heals / total failures), false positive rate (heals that masked real bugs), average healing time, and cost per run. I publish these to a Grafana dashboard after every CI run. A healthy agent has a healing rate above 70% and a false positive rate below 5%.

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.