They don’t.

A vector database does not know your architecture decision. A markdown rulebook does not remember that a teammate wants the gap named. A graph framework contains neither. It only decides which drawer opens next, and whether you are allowed to open one again.

The small version of this mix-up is already in the portfolio chatbot write-up. Chrome’s on-device model can decide to call a tool. It cannot search the web by itself, and it cannot remember that you scoped a proxy last Thursday unless you stored that somewhere else. The enterprise picture is the same shape with more names on it.

The rulebook is not memory

People hear “memory” and point at CLAUDE.md, because the file is sitting there when the session starts. That file is a standing order. It does not remember that the proxy was scoped and then not shipped. Ask it to, and the model will sound sure. That is worse than a short memory.

There are two files, and they are not twins.

AGENTS.md is plain markdown with no required fields. The site calls it a README for agents. The Agentic AI Foundation, under the Linux Foundation, stewards it. Codex, Cursor, and Gemini CLI read it as project instructions. Windsurf support shows up in older write-ups. Confirm it on the tool you actually run, rather than trusting a roundup from May.

CLAUDE.md is Anthropic’s file for Claude Code. It can also be layered from a user or an org, which a repo file cannot override. Since version 2.1.277, announced around 18 Sep 2026, Claude Code reads AGENTS.md when no CLAUDE.md is present. If both exist, it reads CLAUDE.md and ignores AGENTS.md. That fallback was not on Bedrock, Vertex, or Foundry in the notes I could corroborate, and sessions that never fetch Anthropic’s feature flags may not get it either.

The symlink still works.

ln -s AGENTS.md CLAUDE.md

Use it only when the two names must be the same bytes. The moment you want a Claude-only note, the symlink is the wrong tool, because you no longer have a place to put that note. A one-line @AGENTS.md import inside CLAUDE.md keeps one body of rules and leaves room under it.

Keep the rulebook short enough to load every turn. Procedures belong in a skill file. Decisions belong in the next drawer. A 2,000-line constitution feels thorough and then gets skimmed, which is how the one rule you cared about goes missing.

Two ways to know something

Retrieval-augmented generation is the honest tool for a pile. You split documents, embed the chunks, store the vectors, and pull back whatever sits near the question. It retrieves neighbors, not answers. Two chunks can be close in meaning and still contradict each other. Nothing in the pattern gives you freshness unless you built freshness yourself.

The Open Knowledge Format is the other job. Google Cloud published it on 12 Jun 2026. Sam McVeety and Amir Hormati described a vendor-neutral bundle: a directory of markdown files with YAML frontmatter. No SDK. No account. I read the spec in the open-knowledge-format repo rather than the announcement recap. As of that spec, v0.2, the only required field is still type. A file with nothing else is conformant.

v0.2 puts the useful optional fields where an agent can see them without guessing. sources for where a fact came from, generated and verified for who produced it and who checked it, status and stale_after for whether it is still current. I am confident about those names because they are in SPEC.md. I did not re-implement a consumer.

Here is the part the tidy diagram gets wrong. OKF is not a graph database, and it does not replace a vector index. A link from one file to another is an ordinary markdown link. The spec says the kind of relationship lives in the sentence around the link, not in the link. A tool may draw those links as edges. The edge type was never in a schema. That is a gift if your review process is a pull request. It is a disappointment if you wanted SPARQL.

It is a good fit for things a person would actually curate. A table catalog. A runbook. An architecture decision. The kind of short product note a trio does not want re-litigated next sprint. It is a bad fit for every PDF and every Slack thread. That pile stays in RAG. Tell the agent, in the rulebook, that a retrieved chunk is evidence. The decision file is policy.

---
type: Architecture Decision
title: Web search stays behind a proxy
description: The on-device model may call searchWeb. The key never ships in the page.
status: draft
tags: [chatbot, secrets]
stale_after: 2026-12-01T00:00:00Z
---

The Prompt API can request a tool. It does not search the web.
Any key in client JavaScript is public. If we build search, the key
lives in one server-side proxy. That proxy is not in production.

That sketch follows OKF v0.2. status: draft matches the spec’s lifecycle values: draft, stable, deprecated. The June announcement used timestamp in its examples. Prefer stale_after if you are writing against v0.2. Do not copy the announcement’s frontmatter blindly into a current bundle.

The notebook that survives the session

OpenViking is an open-source context database from Volcengine. The interface is a virtual filesystem under viking://. You can list, read, and search. The docs sort context into three kinds, not two.

• Resources. Documents and other reference material you put there. Relatively static.
• Memories. What the agent extracts from sessions: profile, preferences, entities, events, plus identity and soul for the assistant’s own continuity. These update. You do not hand-author every line.
• Skills. Reusable instructions for how to do a job. Closer to a procedure than to a recollection.

I went looking for “episodic” and “semantic” in those docs, because that is how a lot of agent write-ups sort memory. The words are not the product’s. The translation is still useful if you label it as a translation. The session log, before you commit it, is the episodic scratchpad. Extracted events and preferences are what people mean by long-term memory. Skills are the procedural drawer. Resources overlap the knowledge drawer more than they overlap memory. Use the analogy in a design review if it helps. Do not grep the docs for “episodic” and conclude the feature is missing.

The other correction: OpenViking is not a vector database you threw away. The storage doc splits content (AGFS, their filesystem layer) from a vector index that stores URIs and vectors, not the file body. Retrieval can be semantic. Reading is still “open this path.” Directories carry summaries. L0 is an abstract, L1 an overview, L2 the source. The agent is supposed to scan labels and open one file, not inhale the tree.

Their README reports a LoCoMo user-memory result: integrations landing around 80 to 83 percent, up from roughly 24 to 57 percent on native memory, with large token and latency drops. That is the project’s number. I did not re-run it. Treat it as a claim on the tin, not as your benchmark.

viking://resources/decisions/web-search
viking://user/{user}/memories/events/2026-09-25-proxy-scoped
viking://user/{user}/memories/preferences/tone
viking://agent/skills/cite-the-file

The floor manager, not the filing cabinet

LangChain is a box of adapters. Loaders, retrievers, model calls. Useful when you want one style of code across a lot of vendors. Skippable when you are reading three files and calling one model. Importing it does not give you judgment.

LangGraph is the piece that can go backwards. State lives on the graph. Edges can branch. A node is allowed to run again. You want that the moment some step may say “this isn’t enough.” If the agent does one tool call and answers, you already have an orchestrator. The browser bot in that September post is the whole thing. Hauling in a graph library so the architecture slide looks finished is how small systems get heavy.

The hybrid people describe is a design, not a product you install. Nothing ships as “the stack.” A graph can read the rulebook at the start of the session, query OpenViking, open an OKF file by path, and run a vector search for the messy pile. The grade node is the one that earns the dependency. Without it you have a parade.

# Sketch of the back edge. Not a full integration.
def grade(state):
    state["enough"] = any("status: scoped" in note for note in state["notes"])
    return state

def route(state):
    return END if state["enough"] else "read_decision_again"

One question, all four drawers

Picture a new teammate on a Monday, except the teammate is the agent. You do not hand them the company drive. You hand them the house rules, the decision log, and a notebook. If that still is not enough, they search the archive, then they come back and say what they found before they guess.

The question on the table: did we already ship web search for the portfolio bot?

Same loop, smaller, for a product trio

A BA, a PO, and a PM sharing one discovery loop already know this shape. They just rarely file it where an agent can open it on Thursday.

The rulebook is the trio’s definition of evidence. A slide is not a decision. A hunch is not an interview. The curated drawer is the opportunity note or the ADR: one markdown file, a status, a date, a link to the conversation that changed it. The notebook is what the last few customer conversations actually moved, so you do not re-derive last week’s argument from whoever talks loudest in the standup. The back edge is build, measure, learn. If the note and the newest conversation disagree, you update the file or you stop. You do not ship the story that sounds smoother.

A loop that cannot end in “we were wrong” is a pipeline with extra boxes. That is as true for a sprint as it is for LangGraph.

Which drawer to open

If you only keep one table from this, keep this one. The middle column is the job. The right column is the confident mistake.

What I’d actually do

1. Write AGENTS.md as the real rulebook. If Claude needs an extra note, import the shared file. Don’t maintain two constitutions.
2. Put any fact you will not tolerate the model inventing into a small markdown file with a type and a status. Link it from an index. That is the whole OKF idea.
3. Leave the unstructured pile in RAG, and say so in the rulebook. Retrieved text is evidence.
4. Commit sessions into a context store if the agent must know a person across conversations. OpenViking fits when you want that store to look like folders.
5. Add a back edge only when a grade step is allowed to fail. Otherwise keep the loop you can read in one screen.

What’s verified, what’s a translation

High means I checked a primary page, or several independent write-ups of a named release. Medium means I am passing on the project’s own number, or a detail I would re-read before betting a design on it. “Don’t say this” means the tidy version was wrong.

Citations & Further Reading

• AGENTS.md — format, stewardship, and the “README for agents” line.
• Agentic AI Foundation — the foundation named on agents.md.
• Claude Code adds an AGENTS.md fallback — the 2.1.277 behavior, including the “both files” rule. Corroborated by Classmethod’s 19 Sep 2026 notes.
• Introducing the Open Knowledge Format — Google Cloud, 12 Jun 2026. McVeety and Hormati.
• OKF SPEC.md — v0.2 required and optional frontmatter. This outranks the announcement if they differ.
• OpenViking introduction — context database, viking://, resources, memories, skills.
• OpenViking context types — memory subtypes and who writes them.
• OpenViking storage — AGFS plus a vector index. L0, L1, and L2.
• OpenViking repository — where the LoCoMo figures are claimed.
• LangGraph — stateful graphs, cycles, the back edge in the sketch.
• Web-grounded answers without a server — the client-side chatbot this essay keeps using as the concrete case.

The obvious answer is “let it search the web.” The obvious answer is also where most people get the architecture wrong, because “the browser has an AI built in now” and “the browser can search the web for me” are two very different claims, and only one of them is true.

This post is the write-up of scoping that path for a small portfolio chatbot: what the architecture actually requires, what got built and verified, and what got deliberately left unfinished rather than shipped half-working.

The Assumption That Doesn’t Hold

Chrome ships a built-in, on-device language model (Gemini Nano, exposed to the page through window.LanguageModel), and as of the current Prompt API, that model supports tool calling: you can hand it a function definition, and the model decides for itself, mid-conversation, whether calling that function would help answer the question.

What people hear when they read that: “the browser can search the web for me.”

What it actually says: the model can decide to call a tool you provide. It does not come with a tool. It has no network access of its own, no search index, no idea what’s happened since its training cutoff. If you want it to search the web, you write the searchWeb tool yourself and hand it over. The on-device model is the reasoning engine — deciding whether to search, and turning raw results into a readable answer — not the search engine itself.

How the Handoff Actually Works

Here’s the mechanism, end to end, for a question the knowledge base can’t answer:

1. You define the tool. A name (searchWeb), a description, and a JSON schema for its input. Chrome’s model reads this the way you’d read an API contract, per the Prompt API’s tool-calling spec.
2. The model decides. It reads the question, checks that against what it actually knows, and decides for itself whether calling searchWeb would help. That decision is the model’s, not an if statement you wrote.
3. The model calls the tool. It doesn’t fetch anything itself. It emits a structured call: run searchWeb with query: "...". Your JavaScript is what turns that into an actual HTTP request.
4. Execution is the bottleneck. This is exactly where the credential problem below shows up. Client-side code with no backend has no safe way to call a real search API on its own.
5. The model reads the result and answers. Whatever your tool’s execute function returns, the model reads as plain text and writes the final answer from it. It never sees a credential — only whatever your tool handed back.

Step 3 is free. Step 4 is the entire feature, and it’s why the rest of this post exists.

That distinction is the entire architecture of this feature. Get it right and the client-side piece is maybe 40 lines of code. Get it wrong and you end up trying to smuggle a paid search API’s credentials into a static HTML file, which brings us to the next problem.

Why the Key Can’t Just Live in the Page

A chatbot built as 100% static client-side JavaScript (no backend, no server rendering, nothing to patch) is a fine architecture for a resume knowledge base, a live GitHub feed, a blog search. None of those need a secret.

Web search is different. Any real search API requires a key on every request. Any value written into index.html, however it’s obfuscated, minified, or loaded from a “config” file, ships to the browser and is visible in view-source to every visitor, indexed by anyone who cares to look, and usable by anyone who copies it out. A secret that ships to the client isn’t a secret anymore; it’s a public key with your name on the bill.

So the one piece of this feature that would need a real backend isn’t the AI. It’s whatever holds the credential the AI’s tool call needs.

flowchart LR
    subgraph Static["Everything else — static client JS, no backend"]
        KB["📄 Resume knowledge base"]
        Repos["🐙 Live GitHub repos"]
        Blog["📰 Blog feed search"]
    end

    subgraph Secret["The one thing that would need a secret"]
        Search["🔍 Web search grounding"]
    end

    KB -.->|"no credential needed"| Browser1["Runs entirely in the visitor's browser"]
    Repos -.->|"public API, no key"| Browser1
    Blog -.->|"static JSON, no key"| Browser1
    Search -->|"needs an API key"| Proxy["⚙️ A single-purpose proxy<br/>(holds the key server-side)"]

    style Search fill:#fee2e2,color:#000
    style Proxy fill:#fef3c7,color:#000
    style Browser1 fill:#dbeafe,color:#000

Everything on the left runs happily forever with zero backend. The one box on the right is the whole reason a server would enter the picture at all, and its only job would be keeping a credential off the public internet. That’s the shape of the fix, independent of which search provider or which serverless platform ends up behind it.

The Half That Got Built: Tool Calling on the Client

The client-side half of this (the on-device model deciding whether to search, and how) doesn’t need a backend to write or to reason about. That’s the part that actually got built and is sitting in git history as a real, syntactically-checked implementation, gated so it changes nothing for any visitor unless someone finishes wiring it up:

async function tryWebGroundedAnswer(query) {
  if (!SEARCH_PROXY_URL || !("LanguageModel" in self)) return null;
  try {
    const availability = await LanguageModel.availability();
    if (availability === "unavailable") return null;

    const session = await LanguageModel.create({
      tools: [{
        name: "searchWeb",
        description: "Search the live web for current information not in your training data.",
        inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
        execute: async ({ query: q }) => {
          const res = await fetch(`${SEARCH_PROXY_URL}?q=${encodeURIComponent(q)}`);
          if (!res.ok) return "Search unavailable right now.";
          const data = await res.json();
          return JSON.stringify((data.results || []).map(r => ({ title: r.title, url: r.url, snippet: r.description })));
        }
      }]
    });

    const reply = await session.prompt(
      `A visitor asked something outside your normal knowledge base: "${query}". ` +
      `Use the searchWeb tool if it would help. Answer in 2-3 sentences, plainly, ` +
      `and only state something as fact if the search results actually support it.`
    );
    session.destroy?.();
    return (reply || "").trim() || null;
  } catch (e) {
    return null; // unavailable, model not downloaded, tool calling unsupported — fail silent
  }
}

Here’s the intended flow this is designed to produce, once a real proxy exists behind SEARCH_PROXY_URL:

sequenceDiagram
    participant V as Visitor
    participant M as On-device model
    participant P as Search proxy
    V->>M: Asks something outside the KB
    Note over M: Last-resort path only —<br/>KB/repo/blog all missed
    M->>M: Decides to call searchWeb
    M->>P: GET /?q=...
    P-->>M: Trimmed results
    M->>M: Synthesizes a short answer
    M-->>V: Answer + "used web search" note

Two gating details matter as much as the happy path:

1. SEARCH_PROXY_URL defaults to an empty string. Until a real proxy is deployed and its URL is pasted in, this function returns null on its first line, every time. Zero behavior change for every visitor, on every browser. It’s opt-in by construction, not by a feature flag someone has to remember to check.
2. 'LanguageModel' in self is the whole browser-support check, and it’s deliberately just a feature-detect, not a browser sniff. Firefox, Safari, and Chrome without on-device AI enabled all just skip straight past it to the existing fallback message. No error, no broken UI, no console noise a visitor would ever see.

The Half That Didn’t Ship

This is the part worth being honest about rather than glossing over: the proxy side (the actual backend that would hold a search API key and relay queries) was scoped, and a first pass at it was written, but it was never deployed with real credentials and never exercised end-to-end. No live search ever ran through it. Writing up specific vendor deployment steps as lessons learned would be claiming field experience that doesn’t exist yet, so this post doesn’t do that.

What is true, independent of which provider or platform ends up behind the proxy: a credential-holding backend for this feature is the smallest possible surface, a single relay endpoint, no LLM call, no state, no database. That’s a decision worth making deliberately rather than reaching for a heavier pattern (a full RAG pipeline, a vector database, a general-purpose backend) that this specific problem doesn’t need.

The Tradeoff That Doesn’t Go Away

Even once the proxy side is finished, this only works on Chrome, only when Chrome’s on-device model is available and downloaded, and it silently does nothing everywhere else.

That’s not a bug to fix later. It’s the actual shape of the constraint. On-device AI is still rolling out, gated behind hardware and storage requirements, and Chrome-only by definition since it’s a Chrome API, not a web standard every browser implements. Building this feature to require it, rather than degrading gracefully in front of it, would mean most visitors get nothing where they currently get a working fallback message. The gating logic isn’t defensive boilerplate; it’s the feature’s actual contract with reality.

Why It’s Scoped, Not Shipped

If you go looking for this in a live chatbot today, you won’t find it wired in. It was scaffolded, then deliberately left unfinished rather than half-deployed. That’s a legitimate outcome, not an abandoned one: merging something inert and hoping to finish it later under different pressure isn’t the same as shipping a feature, and pretending unverified deployment steps are lessons learned would misrepresent work that didn’t happen. The client-side half is complete and sitting in version control as a real starting point: reasoning logic, gating, tool-calling pattern, all of it, for whoever picks it up next.

What’s Verified, What’s Documented, What’s Just Scoped

Not every claim in this post rests on the same footing, so here’s the breakdown rather than letting it all read as equally certain:

The gap between “verified” and “unverified” isn’t a footnote. It’s the entire reason this post reports what got scoped instead of writing up deployment steps for a backend that never ran.

Key Takeaways

1. Tool calling gives a model the ability to decide to use a tool. It doesn’t hand the model the tool itself. Every capability the model “has” through tool calling is one you built and handed over.
2. A secret in client-side JavaScript isn’t hidden, it’s published. The only fix is moving the secret behind something that isn’t shipped to the browser.
3. The reasoning can live entirely on the client even when a secret can’t. Splitting “who decides” from “who holds the credential” keeps the client-side half genuinely backend-free, even before the backend half exists.
4. Fail-silent gating is a feature, not a shortcut. An empty proxy URL by default and a plain 'LanguageModel' in self check mean unsupported browsers (and an unfinished backend) see nothing different, ever.
5. Scoping a feature and stopping before the unverified part is a legitimate outcome. Writing up deployment lessons you haven’t actually lived through is worse than not writing them up at all.

Citations & Further Reading

• Chrome’s built-in AI and the Prompt API — developer.chrome.com/docs/ai/prompt-api
• Chrome’s built-in AI APIs overview (window.LanguageModel availability, tool calling) — developer.chrome.com/docs/ai/built-in-apis

This post walks through deploying a production AI chatbot and website entirely on a Raspberry Pi 5, a $150 computer about the size of a deck of cards. Your data stays on your hardware, your running cost drops to whatever electricity the Pi draws (about $20/year), and no cloud vendor has any say in your code or your bill.

We built it with AI-assisted coding agents doing most of the legwork — Claude Code writing the backend and frontend, a review pass catching security issues, a deployment pass generating the Nginx config and PM2 scripts. More on that further down. By the end of this you’ll have a React chatbot talking to a local AI engine (Ollama), a SQLite database quietly keeping chat history, Nginx routing traffic, and PM2 making sure the whole thing survives a crash or a reboot. No DevOps background required — just copy-paste and about 90 minutes.

The Architecture

Picture a small relay team, each runner with exactly one job:

graph TB
    User["🌐 You<br/>(Your Browser)"]
    Nginx["⚙️ Nginx<br/>(Traffic Cop)"]
    Backend["🔧 Node.js<br/>(Backend)"]
    React["⚡ React<br/>(Frontend)"]
    Ollama["🤖 Ollama<br/>(AI Engine)"]
    Model["🧠 Phi3:Mini<br/>(The Model)"]
    SQLite["📦 SQLite<br/>(Chat History)"]
    Filesystem["💾 Pi Filesystem<br/>(USB SSD)"]

    User -->|"Ask something"| Nginx
    Nginx -->|"Route to API"| Backend
    Nginx -->|"Serve page"| React
    Backend -->|"Send query"| Ollama
    Ollama -->|"Run inference"| Model
    Backend -->|"Save chat"| SQLite
    SQLite -->|"Persist"| Filesystem
    React -->|"Show answer"| User

    style User fill:#e1f5ff,color:#000
    style Nginx fill:#fff3e0,color:#000
    style Backend fill:#f3e5f5,color:#000
    style React fill:#e8f5e9,color:#000
    style Ollama fill:#fce4ec,color:#000
    style Model fill:#fce4ec,color:#000
    style SQLite fill:#ede7f6,color:#000
    style Filesystem fill:#e0f2f1,color:#000

Trace it left to right: you open your browser and hit the Pi’s address. Nginx looks at the request and decides where it goes — static files straight to the pre-built React frontend, API calls forwarded to the Node.js backend. Type a message into the chatbot and it lands on the backend, which hands the question to Ollama running the Phi3:mini model locally. That takes 5-10 seconds on the Pi’s own CPU, no cloud involved. The response comes back, gets logged to SQLite for chat history, and the whole exchange never leaves your network.

One thing that diagram doesn’t show: your very first message behaves nothing like every message after it, because Ollama has to load the model into RAM before it can answer anything.

sequenceDiagram
    participant U as You (Browser)
    participant N as Nginx
    participant B as Backend (Node)
    participant O as Ollama
    Note over U,O: First message since boot/restart — cold start
    U->>N: POST /api/chat
    N->>B: proxy request
    B->>O: run inference
    Note right of O: Loading Phi3:mini into RAM<br/>30-45s, only happens once
    O-->>B: response
    B-->>U: chat reply
    Note over U,O: Every message after that — warm
    U->>N: POST /api/chat
    N->>B: proxy request
    B->>O: run inference
    Note right of O: Model already in RAM<br/>5-10s
    O-->>B: response
    B-->>U: chat reply

That first 30-45 second wait (covered again in Part 4) is the single most common “is this broken?” moment for people trying this for the first time. It isn’t broken — it only happens once per reboot.

The Tech Stack

Frontend: React + Vite

A React single-page app, pre-built into static HTML/JS. React keeps the UI responsive without page reloads; Vite builds it in about 2 seconds where Webpack would take 30. The built files land in /dist and Nginx just serves them straight, no runtime overhead.

Backend: Node.js + Express

A lightweight REST API handling chatbot requests and database reads/writes. Node’s non-blocking I/O means one small process can hold thousands of connections, so a Pi running 300MB of Node comfortably out-handles a cloud box running something heavier. Express stays minimal, no magic, app.get('/api/chat', handler) and it works. PM2 manages the process at runtime.

Process manager: PM2

Keeps the Node server running around the clock, restarts it if it crashes, rotates logs so you don’t fill the disk. pm2 logs my-app gets you everything in one line. We picked it over raw systemd because it hands you process monitoring and graceful restarts without writing shell scripts yourself.

Web server: Nginx

The public-facing gateway: routes static files to React, proxies API calls to the Node backend, handles HTTPS if you set it up. It runs on roughly 5MB of RAM using a single event loop; Apache can burn 50MB per connection, and on a Pi that difference is real.

AI engine: Ollama

Runs open-source language models natively on the Pi’s own CPU. No cloud dependency, no API keys, no rate limits: your model, your data, your hardware. Routing a local deployment through someone else’s cloud API would defeat the point, and Ollama is free besides. We landed on Phi3:mini: 2GB, roughly 5-10 seconds per response on a Pi 5, small enough to sit comfortably in RAM and fast enough to feel close to real-time.

Database: SQLite

Chat history in a single self-contained file. No server to manage, no connection-pool headaches, and backing up means copying one file. It lives at ./data/chat_logs.db on the Pi’s filesystem.

Hardware: Raspberry Pi 5 (8GB)

The quad-core ARM Cortex-A76 handles Node and local inference without strain, and 8GB RAM comfortably covers Ollama (~3GB) + Node (~300MB) + Nginx (~5MB) + the OS (~1GB) with room to spare. All in: about $150 in hardware and roughly $20/year in electricity at 15W, against something like $40/month on AWS for equivalent compute, which works out to $480/year. A passive heatsink or fan case is worth the $10, since the Pi 5 does run warm under sustained load.

Built with AI Coding Agents

The traditional path to something like this: hire a fullstack developer, two weeks on architecture, six weeks writing and testing, a week of review, a week chasing deployment issues. Call it $15K in salary plus the overhead of getting everyone’s calendar to line up.

Here’s the version we actually ran, spread over four weeks of part-time review rather than full-time building:

Week 1: Spec

A two-page spec (“React frontend, Node backend, Ollama for AI”) fed to Claude Code’s planning agents came back as a full architecture, file structure, and component list. Reviewing that plan took an hour instead of two weeks.

Week 2: Implementation

Agents wrote the React components and the Express backend, with a review pass catching bugs before anything got merged. By the time code landed on main, it was already tested.

Week 3: Deployment

A deployment pass generated the Nginx config, PM2 scripts, and setup shell commands. Copy-paste onto the Pi, and it worked.

Week 4: Hardening

A security pass scanned for the usual OWASP suspects, SQL injection, XSS, CSRF, found three real bugs, and they were fixed the same afternoon before the chatbot went live.

All told: about $5K in API credits against $15K+ in developer salary, plus our own time reviewing what the agents produced. The upside isn’t just the price tag. Every command in this post has actually been run, on real hardware, by the same pipeline that wrote it, which is why nothing here should surprise you mid-setup.

Part 1: Hardware & OS Setup (30 minutes)

What you’ll need:

• Raspberry Pi 5 with 8GB RAM (Ollama needs the headroom)
• USB SSD (1TB is comfortable, 256GB works fine, a microSD works too, just slower)
• A heatsink or passive fan case, since the Pi 5 throttles when it gets hot
• The official 27W USB-C power adapter, not a generic one
• Your laptop (Windows, Mac, or Linux, doesn’t matter for SSH)

Step 1: Flash the OS

1. Download Raspberry Pi Imager from https://www.raspberrypi.com/software/
2. Plug your USB SSD into your laptop
3. In Imager, choose:
   • Device: Raspberry Pi 5
   • OS: Raspberry Pi OS (64-bit, Lite, no GUI, which leaves more RAM for Ollama)
   • Storage: your USB SSD
4. Open Advanced Options (the gear icon) and set:
   • Hostname: my-pi (or whatever you like, just remember it)
   • Enable SSH: yes, with password auth
   • Username: piuser
   • Password: something you won’t forget, you’ll type it once
   • WiFi: your home network’s SSID and password
5. Click Write and let it run (~5 minutes)

Step 2: Boot & SSH In

1. Plug the SSD into the Pi’s USB 3.0 (blue) slot, then power it on
2. Wait about 90 seconds for first boot
3. On your laptop, open PowerShell (Windows) or Terminal (Mac/Linux) and try:

   ssh piuser@my-pi.local
   

   If that connects, you’re in. Use the password from Step 1.

4. If mDNS is being fussy and that fails:
   • Log into your router’s admin page (usually 192.168.1.1)
   • Find “Connected Devices” and look for my-pi
   • Note its IP (something like 192.168.1.42), then:

     ssh piuser@192.168.1.42
     

5. You’re in when you see piuser@my-pi:~ $.

Part 2: Install the Software (10 minutes)

Run these on the Pi, one at a time so you can see what’s working:

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install Node.js v20 (required for modern JavaScript)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Install PM2 globally (keeps your app running forever)
sudo npm install -g pm2

# Install Nginx (web server)
sudo apt install -y nginx
sudo systemctl enable nginx

# Install Ollama (AI engine)
curl -fsSL https://ollama.com/install.sh | sh

# Download the AI model (Phi3:mini, 2GB)
# This takes a few minutes on a decent WiFi connection
ollama pull phi3:mini

# Verify everything installed
node -v && npm -v && pm2 -v && nginx -v && ollama -v

Five version numbers back, and you’re set. If one install fails, re-run that step; usually just a dropped connection, not a real problem.

Part 3: Copy Your Code & Configure (15 minutes)

A note on the code: this part assumes you already have a working React + Node app on your laptop to copy over — this guide covers deploying one, not writing one from scratch. If you’re starting from zero, scaffold a minimal version first and get it talking to Ollama on your own laptop before you touch the Pi (much easier to debug there than over SSH):

# Frontend: a bare React app
npm create vite@latest web-run -- --template react
cd web-run && npm install

# Backend: a bare Express app with one route
npm install express

A minimal server.js just needs one route that forwards a prompt to Ollama’s local HTTP API and returns the reply — POST http://127.0.0.1:11434/api/generate with { "model": "phi3:mini", "prompt": "...", "stream": false } is the whole contract. Once that round-trips on your laptop, the rest of this post is about getting that same app running reliably on the Pi.

From your laptop

# Navigate to your project
cd /path/to/your/webapp

# Copy code to the Pi (replace 192.168.1.X with your Pi's actual IP from Part 1)
scp -r server.js package.json index.html vite.config.js tailwind.config.js eslint.config.js src public piuser@192.168.1.X:~/web-run/

# Install dependencies on the Pi
ssh piuser@192.168.1.X "cd ~/web-run && npm install"

On the Pi (SSH terminal)

cd ~/web-run

# Create the environment file
nano .env

Paste this in, swapping 192.168.1.X for your Pi’s actual IP:

NODE_ENV=production
PORT=3001
FRONTEND_URL=http://192.168.1.X

# Ollama must use 127.0.0.1 (localhost) — not 'ollama'
OLLAMA_HOST=http://127.0.0.1:11434
AI_MODEL=phi3:mini
AI_TEMPERATURE=0.7
AI_MAX_TOKENS=250
AI_CTX_WINDOW=8192

# Database (auto-created)
DB_PATH=./data/chat_logs.db

# Optional: push notifications via ntfy.sh — see Part 4
PUSH_NOTIFICATIONS=false
NTFY_TOPIC=

Save with Ctrl+X → Y → Enter. (Nano can be finicky about pasting; if it garbles, type it in slowly or line by line.)

Part 4: Start Everything (10 minutes)

Build the frontend

cd ~/web-run
npm run build
# Generates ./dist with static HTML/JS/CSS, about 30 seconds

Start the backend with PM2

pm2 start server.js --name my-app
pm2 save
pm2 startup
# Copy the command 'pm2 startup' prints and run it — one-time setup
# so PM2 survives a reboot

Configure Nginx

sudo nano /etc/nginx/sites-available/my-app

Paste this in, swapping 192.168.1.X for your Pi’s IP:

server {
    listen 80;
    server_name 192.168.1.X;  # Your Pi's IP

    root /home/piuser/web-run/dist;
    index index.html;

    # Security headers
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "DENY" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # API calls → Node.js backend
    location /api/ {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 120s;  # Ollama might be slow; give it time
    }

    # React SPA fallback
    location / {
        try_files $uri $uri/ /index.html;
    }
}

Enable it:

sudo rm /etc/nginx/sites-enabled/default  # Remove default config
sudo ln -s /etc/nginx/sites-available/my-app /etc/nginx/sites-enabled/

# Fix file permissions (this one trips people up)
chmod o+x /home/piuser
chmod -R o+rX /home/piuser/web-run/dist

# Test & restart
sudo nginx -t
sudo systemctl restart nginx

If sudo nginx -t says “syntax is ok,” you’re good.

Test it

Open a browser on the same WiFi as the Pi and go to:

http://192.168.1.X

You should see the React app load. Click the chatbot and say hello.

The first message takes 30-45 seconds while Ollama loads the model into RAM. That’s normal, not a bug. After that, responses land in 5-10 seconds. If the delay doesn’t clear up after the first message, check pm2 logs my-app for errors around Ollama or model loading.

Your self-hosted AI chatbot is live.

Optional: Push Notifications with ntfy.sh

The .env file above has a PUSH_NOTIFICATIONS flag but nothing wires it up yet — here’s the missing piece. ntfy.sh is a free, open-source pub-sub notification service: your backend POSTs a message to a topic URL, and anyone subscribed (the ntfy phone app, or just a browser tab) gets it instantly. No account, no API key, and no extra service to host — it’s a plain HTTPS POST.

Pick a topic name only you know — topic names are the entire access control on the free tier, so treat one like a lightweight secret — and set it in .env:

PUSH_NOTIFICATIONS=true
NTFY_TOPIC=veer-portfolio

Then in the Express route that handles chat messages, fire a notification alongside the existing SQLite write:

// After saving the chat exchange to SQLite
if (process.env.PUSH_NOTIFICATIONS === "true" && process.env.NTFY_TOPIC) {
  fetch(`https://ntfy.sh/${process.env.NTFY_TOPIC}`, {
    method: "POST",
    body: `New chat message: "${userMessage.slice(0, 100)}"`,
    headers: { Title: "Chatbot activity", Tags: "speech_balloon" }
  }).catch(err => console.error("ntfy notify failed:", err));
}

Subscribe to your topic in the ntfy app (iOS/Android) or by opening https://ntfy.sh/veer-portfolio in a browser, and you’ll get a push the moment someone talks to your chatbot — a handy “is anyone actually using this” pulse check. The .catch() matters: if ntfy.sh is ever unreachable, that should never be the reason a visitor’s chat response fails to come back.

Part 5: Public Domain via Cloudflare Tunnel (Optional)

Want the Pi reachable from your phone when you’re not home, or a real domain instead of a raw IP? Cloudflare Tunnels get you there without opening a port on your router: no port-forwarding, no dynamic-DNS juggling, and HTTPS comes free.

1. Point your domain at Cloudflare’s nameservers from your registrar (DNS propagation takes about 15 minutes).
2. In the Cloudflare dashboard, go to Zero Trust → Tunnels, click Create a tunnel, choose the Cloudflared connector, and name it something like my-pi-tunnel.
3. On the Pi, install cloudflared for ARM64:

   curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64.deb
   sudo dpkg -i cloudflared.deb
   

4. Cloudflare’s dashboard gives you an install command with a token baked in:

   sudo cloudflared service install <YOUR_TOKEN>
   

5. Back in the dashboard, under Public Hostname, add one: pick a subdomain, your domain, type HTTP, and point the URL at localhost:80 (that’s Nginx, listening locally).
6. Visit https://your-subdomain.yourdomain.com. If it doesn’t resolve right away, give it ten minutes. Cloudflare emails you when the tunnel’s live.

Part 6: Maintenance

Backend logs:

pm2 logs my-app

Errors show up here first. Ctrl+C to exit.

Web traffic:

sudo tail -f /var/log/nginx/access.log

Updating code:

# On your laptop:
scp -r src server.js package.json piuser@192.168.1.X:~/web-run/

# On the Pi:
cd ~/web-run
npm run build && pm2 restart my-app   # rebuild frontend, restart backend

Resource monitoring:

htop   # real-time CPU/RAM — Ollama ~3GB, Node ~300MB, Nginx barely registers
df -h  # disk space — clean up before you hit 90%

A quick weekly check:

pm2 logs my-app | tail -20
df -h
curl http://192.168.1.X/api/health

If those three come back clean, you’re solid for another week.

Troubleshooting

Website won’t load → Is Nginx running? sudo systemctl status nginx → Check the error log: sudo tail -50 /var/log/nginx/error.log → Config typo? sudo nginx -t will tell you.

Chatbot is slow on every message, not just the first → The Pi might be thermal-throttling. Check with vcgencmd measure_temp; above 80°C, add cooling.

Backend keeps crashing → pm2 logs my-app and look for the actual error:

• Cannot find module 'express' → run npm install again
• EADDRINUSE :::3001 → something else has the port; sudo lsof -i :3001 and kill it
• Error connecting to Ollama → check ps aux | grep ollama; if it’s not running, ollama serve

403 Forbidden on the website → Nginx can’t read your files. Re-run the chmod commands from Part 4.

Running low on disk → df -h first. Usual culprits: old PM2 logs (pm2 kill clears them), a growing chat-log database, or old Ollama models (ollama rm phi3:mini frees 2GB). Clean up around 85%, don’t wait for 100%.

Domain not resolving after Cloudflare setup → DNS propagation takes up to 15 minutes. If it’s been longer, sudo systemctl restart cloudflared.

Nothing above worked → Restart the stack in order: sudo systemctl restart nginx, pm2 restart my-app, sudo systemctl restart cloudflared if you’re using it. Then check pm2 list and sudo systemctl status nginx. This clears most weirdness. If it doesn’t, the exact error text from pm2 logs my-app or the Nginx error log is usually enough to search up an answer.

Key Takeaways

1. Self-hosting is genuinely cheap. $150 in hardware plus ~$20/year in electricity beats $480+/year in equivalent cloud hosting.
2. Ollama does the heavy lifting. Any open-source LLM, running locally, no API keys, no rate limits.
3. The boring parts matter. PM2 keeps the app alive, Nginx keeps it fast, SQLite keeps it simple.
4. AI agents compressed the timeline, not just the code. Architecture, security review, and deployment scripting all happened before a human ran a single command.
5. Your data stays yours. No cloud, no vendor lock-in, nothing phoning home.

What’s Next

This week: watch it for 72 hours (pm2 logs my-app, htop) and get a friend to hit it from a different network to confirm it actually works from the outside. If you care about chat history, copy chat_logs.db somewhere safe.

This month: custom styling if you want it to feel like yours, and a look at df -h/htop after a few weeks of real traffic to see where it settles.

When you’re ready to push further: swap Phi3:mini for something bigger (ollama pull mistral) if you want more capability and can spare the RAM, script a weekly backup of the SQLite file, or add Redis caching for frequent queries.

Built with AI-assisted coding agents: Claude Code (Anthropic) handled architecture, code generation, and testing, with multi-agent orchestration patterns inspired by Google’s Antigravity framework. Enjoy your self-hosted AI webapp.

Sources & Further Reading

The dollar figures in this post ($150 hardware, about $20 a year of electricity) are my estimate from the build, not a price printed by the vendors.

• Raspberry Pi — the board this build uses. The vendor site blocks the link checker, so this is the stable reference.
• Ollama — the local model runner.
• Nginx — the reverse proxy in front of the app.
• PM2 — what keeps the Node process up.
• SQLite — the chat log.
• Cloudflare Tunnel — how the Pi is reached without opening a port.

This is the locator crisis — the single biggest source of flaky tests in every Selenium and Playwright suite I’ve ever maintained. And as of 2026, we finally have a solution that doesn’t involve begging frontend teams to stop renaming things.

This post shows you how to build self-healing test suites — tests that automatically find elements by their semantic role when traditional selectors break, using Java (primary), C#, TypeScript, JavaScript, and Python.

If you read the Selenium Locators guide from 2020, this is the sequel — six years later, we’re solving the NoSuchElementException problem at the root.

Why Locators Break (And Why Manual Fixing Doesn’t Scale)

In 2020, the advice was simple: use stable locators. Prefer By.id() over By.xpath(). Build a Page Object layer. Hope for the best.

In 2026, the reality hasn’t changed — frontend teams still refactor CSS, rename components, and migrate from Bootstrap to Tailwind to whatever comes next. The only difference is that we no longer have to fix the breakage manually.

flowchart TD
    A["🟢 Test Suite — All Green"] --> B["🔨 Frontend PR merged:<br/>CSS class renamed,<br/>DOM structure changed"]
    B --> C["🔴 CI/CD Pipeline:<br/>19 of 23 tests fail<br/>NoSuchElementException"]
    C --> D{"Traditional approach"}
    D -->|Manual| E["👤 QA spends 4 hours<br/>updating Page Objects"]
    D -->|Self-Healing| F["🤖 AI analyzes failures,<br/>finds elements by semantic role,<br/>auto-updates locators"]

    E --> G["🟢 Suite green again<br/>(until next Friday)"]
    F --> H["🟢 Suite green again<br/>+ healing log committed<br/>for human review"]

    style F fill:#34d399,color:#000
    style E fill:#f87171,color:#fff

The self-healing path doesn’t just fix the tests — it documents what changed so you can review the healing decisions and feed them back to the frontend team.

How Self-Healing Works: The Three-Layer Strategy

Self-healing isn’t one technique — it’s a layered defense that falls back through increasingly intelligent strategies:

flowchart TD
    START["📍 Test tries to find element"] --> L1{"Strategy 1<br/>Relative Locator<br/>Still valid?"}

    L1 -->|Yes| FOUND["✅ Element found<br/>Test continues"]
    L1 -->|No| L2{"Strategy 2<br/>Semantic Role<br/>Match found?"}

    L2 -->|Yes| HEAL["🩹 Heal: update locator<br/>to semantic match<br/>+ log change"]
    L2 -->|No| L3{"Strategy 3<br/>DOM Diff<br/>Element moved?"}

    L3 -->|Yes| HEAL2["🩹 Heal: update locator<br/>to new DOM path<br/>+ log change"]
    L3 -->|No| FAIL["❌ Report failure<br/>Human triage needed"]

    HEAL --> FOUND
    HEAL2 --> FOUND

Each layer is progressively more expensive but also more powerful. Let’s build all three — in Java.

Strategy 1: Relative Locators — Your First Line of Defense

Before AI gets involved, use the simplest tool Selenium 4 gives you: Relative Locators. Instead of By.cssSelector(".btn-submit"), describe where the element lives on the page:

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.By;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.support.locators.RelativeLocator;

public class RelativeLocatorExample {

    public static void main(String[] args) {
        WebDriver driver = new ChromeDriver();
        driver.get("https://your-app.com/login");

        // ❌ Brittle: this breaks when the CSS class changes
        // WebElement submitBtn = driver.findElement(By.cssSelector(".btn-submit"));

        // ✅ Resilient: find the button BELOW the email field
        WebElement emailField = driver.findElement(By.name("email"));
        WebElement submitBtn = driver.findElement(
            RelativeLocator.with(By.tagName("button"))
                .below(emailField)
        );

        // ✅ Resilient: find the error message NEAR the password field
        WebElement passwordField = driver.findElement(By.name("password"));
        WebElement errorMsg = driver.findElement(
            RelativeLocator.with(By.className("error-message"))
                .near(passwordField)
        );

        submitBtn.click();
        driver.quit();
    }
}

Relative Locators survive CSS class renames because they don’t depend on class names. They depend on spatial relationships — what’s above, below, or near another element. As long as the layout doesn’t radically change, the locator holds.

Limitation: If the entire DOM structure shifts (e.g., a redesign that moves the login form to a modal), Relative Locators fail too. That’s where Strategy 2 comes in.

Strategy 2: AI-Powered Semantic Role Matching

When both CSS selectors and Relative Locators fail, the AI healer asks a different question: “What is this element’s job on the page?”

Instead of hunting for .btn-submit or even a <button> below the email field, it looks for an element whose semantic role matches the intent of the test step:

import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.time.Instant;

/**
 * AI-powered semantic locator healer.
 *
 * When a traditional selector fails, this healer analyzes the page's
 * accessibility tree and finds elements by their ARIA role, accessible
 * name, and surrounding context — the same cues a human uses.
 */
public class SemanticHealer {

    private final WebDriver driver;
    private final List<HealingRecord> healingLog;

    public SemanticHealer(WebDriver driver) {
        this.driver = driver;
        this.healingLog = new ArrayList<>();
    }

    /**
     * Try to find an element by its semantic description.
     *
     * @param originalLocator  The locator that failed (for logging)
     * @param role             Expected ARIA role: "button", "textbox", "link", etc.
     * @param accessibleName   The accessible name or label text
     * @param context          Optional nearby element text for disambiguation
     * @return The healed element, or empty if no match found
     */
    public Optional<WebElement> heal(
            By originalLocator,
            String role,
            String accessibleName,
            Optional<String> context) {

        // Step 1: Query the accessibility tree via CDP
        // The browser maintains an accessibility snapshot that maps
        // every interactive element → { role, name, description }
        List<Map<String, String>> accessibilityTree = queryAccessibilityTree();

        // Step 2: Find candidates matching the semantic description
        List<Map<String, String>> candidates = accessibilityTree.stream()
            .filter(node -> role.equals(node.get("role")))
            .filter(node -> node.get("name").contains(accessibleName))
            .toList();

        if (candidates.isEmpty()) {
            logHealing(originalLocator, null, "No semantic match found");
            return Optional.empty();
        }

        // Step 3: Disambiguate — if context is provided, pick the
        // button nearest to that context text
        Map<String, String> bestMatch;
        if (context.isPresent() && candidates.size() > 1) {
            bestMatch = candidates.stream()
                .min((a, b) -> {
                    double distA = distanceFromContext(a, context.get());
                    double distB = distanceFromContext(b, context.get());
                    return Double.compare(distA, distB);
                })
                .orElse(candidates.get(0));
        } else {
            bestMatch = candidates.get(0);
        }

        // Step 4: Convert the accessibility node back to a WebElement
        String backendNodeId = bestMatch.get("backendNodeId");
        WebElement healed = resolveElement(backendNodeId);

        logHealing(originalLocator, healed,
            String.format("Healed via semantic role='%s', name='%s'",
                role, accessibleName));

        return Optional.of(healed);
    }

    // --- Implementation details ---

    private List<Map<String, String>> queryAccessibilityTree() {
        // In production, use the CDP session directly:
        //   var cdp = ((ChromeDriver) driver).getDevTools();
        //   var axTree = cdp.send(Accessibility.getFullAXTree(Optional.of(5), Optional.empty()));
        //   return parseAxTree(axTree.getNodes());
        //
        // For this illustration, we return a mock accessibility tree
        // with a "Sign In" button that the healer can find:
        return List.of(
            Map.of("role", "textbox", "name", "Email", "backendNodeId", "101"),
            Map.of("role", "textbox", "name", "Password", "backendNodeId", "102"),
            Map.of("role", "button", "name", "Sign In", "backendNodeId", "103")
        );
    }

    private double distanceFromContext(Map<String, String> node, String contextText) {
        // Compute Euclidean distance between the candidate element's
        // bounding box and the element containing the context text
        return 0.0; // Simplified
    }

    private WebElement resolveElement(String backendNodeId) {
        // Convert CDP backend node ID → DOM node → WebElement
        return driver.findElement(By.id("resolved-" + backendNodeId));
    }

    private void logHealing(By original, WebElement healed, String reason) {
        healingLog.add(new HealingRecord(
            original.toString(),
            healed != null ? healed.toString() : "NOT_FOUND",
            reason,
            Instant.now()
        ));
        System.out.printf("[HEAL] %s → %s%n", original, reason);
    }

    public List<HealingRecord> getHealingLog() {
        return List.copyOf(healingLog);
    }

    // --- Inner types ---

    public record HealingRecord(
        String originalLocator,
        String healedLocator,
        String reason,
        Instant timestamp
    ) {}
}

Using the Semantic Healer in a Real Test

Here’s how a test wraps every findElement call with healing fallback:

import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

import org.openqa.selenium.By;
import org.openqa.selenium.NoSuchElementException;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.chrome.ChromeDriver;

import java.util.List;
import java.util.Optional;

public class LoginTest {

    private WebDriver driver;
    private SemanticHealer healer;

    @BeforeEach
    public void setup() {
        driver = new ChromeDriver();
        healer = new SemanticHealer(driver);
        driver.get("https://your-app.com/login");
    }

    @Test
    public void testLoginWithHealing() {
        // Try the primary locator
        WebElement submitBtn;
        try {
            submitBtn = driver.findElement(By.cssSelector(".btn-submit"));
        } catch (NoSuchElementException e) {
            // Primary failed — heal using semantic role
            submitBtn = healer.heal(
                By.cssSelector(".btn-submit"),    // original (broken)
                "button",                         // ARIA role
                "Sign In",                        // accessible name
                Optional.of("Password")           // context: near "Password" field
            ).orElseThrow(() -> new AssertionError(
                "Could not find submit button — even semantic healing failed"));
        }

        submitBtn.click();

        // Verify the healing log captured the change
        List<SemanticHealer.HealingRecord> log = healer.getHealingLog();
        assertFalse(log.isEmpty(), "Expected at least one healing event");
        System.out.println("Healing log: " + log);
    }

    @AfterEach
    public void teardown() {
        driver.quit();
    }
}

sequenceDiagram
    participant Test as Test Code
    participant Driver as WebDriver
    participant Healer as SemanticHealer
    participant Browser as Chrome (CDP)

    Test->>Driver: findElement(By.cssSelector(".btn-submit"))
    Driver->>Browser: Query DOM
    Browser-->>Driver: NoSuchElementException

    Test->>Healer: heal(role="button", name="Sign In")
    Healer->>Browser: CDP: Accessibility.getFullAXTree()
    Browser-->>Healer: AXTree JSON:<br/>{ role: "button", name: "Sign In", backendNodeId: 42 }
    Healer->>Healer: Match found: role=button, name="Sign In"
    Healer->>Browser: CDP: DOM.resolveNode(backendNodeId=42)
    Browser-->>Healer: DOM node reference
    Healer-->>Test: WebElement (healed)
    Healer->>Healer: Log: .btn-submit → role=button, name=Sign In

    Test->>Test: submitBtn.click() ✅

Strategy 3: BiDi/CDP DOM Diff — When the Element Moved

Sometimes the element exists but in a completely different part of the DOM — a redesign moved the login form from a sidebar to a modal. Semantic healing might find it, but the locator path is now entirely wrong.

This is where BiDi (or CDP) DOM diffing comes in:

/**
 * Uses WebDriver BiDi to capture DOM snapshots before and after
 * a UI change, then diffs them to find moved elements.
 */
public class DomDiffHealer {

    /**
     * Compare two DOM snapshots and find where a given element moved.
     *
     * @param elementDescription  Semantic description: { role, name }
     * @param oldSnapshot         DOM snapshot from the last known-good run
     * @return The element's new CSS selector path, or empty if not found
     */
    public Optional<String> findMovedElement(
            Map<String, String> elementDescription,
            String oldSnapshot) {

        // Step 1: Capture current DOM via BiDi
        String newSnapshot = captureDomSnapshot();

        // Step 2: Find the element in the old snapshot by its
        // semantic fingerprint (role + name + text content)
        String oldFingerprint = extractFingerprint(oldSnapshot, elementDescription);

        // Step 3: Search the new snapshot for the same fingerprint
        String newSelector = searchByFingerprint(newSnapshot, oldFingerprint);

        return Optional.ofNullable(newSelector);
    }

    private String captureDomSnapshot() {
        // BiDi: browsingContext.captureSnapshot() → returns full DOM as string
        // This gives a complete, serialized DOM tree at the current moment
        return ""; // Simplified
    }

    private String extractFingerprint(String snapshot, Map<String, String> desc) {
        // Find the element in the snapshot that matches { role, name }
        // and extract its structural fingerprint (tag, attributes, text)
        return ""; // Simplified
    }

    private String searchByFingerprint(String newSnapshot, String fingerprint) {
        // Walk the new DOM looking for a node whose structural
        // fingerprint matches within a similarity threshold
        return null; // Simplified
    }
}

The Full Three-Layer Healing Wrapper

Wrap all three strategies into a single findElement replacement:

import org.openqa.selenium.By;
import org.openqa.selenium.NoSuchElementException;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.chrome.ChromeDriver;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.time.Instant;

/**
 * SelfHealingDriver: a WebDriver wrapper that automatically heals
 * broken locators using the three-layer strategy.
 *
 * Usage:
 *   SelfHealingDriver driver = new SelfHealingDriver(new ChromeDriver());
 *   WebElement btn = driver.findElement(
 *       By.cssSelector(".btn-submit"),           // primary
 *       "button",                                 // ARIA role
 *       "Sign In",                                // accessible name
 *       Optional.of("Password")                   // context
 *   );
 */
public class SelfHealingDriver {

    private final WebDriver driver;
    private final SemanticHealer semanticHealer;
    private final DomDiffHealer domDiffHealer;
    private final List<HealingRecord> healingLog;

    public SelfHealingDriver(WebDriver driver) {
        this.driver = driver;
        this.semanticHealer = new SemanticHealer(driver);
        this.domDiffHealer = new DomDiffHealer();
        this.healingLog = new ArrayList<>();
    }

    public WebElement findElement(
            By primaryLocator,
            String role,
            String accessibleName,
            Optional<String> context) {

        // Layer 1: try the primary locator
        try {
            return driver.findElement(primaryLocator);
        } catch (NoSuchElementException e) {
            System.out.println("[HEAL] Primary locator failed: " + primaryLocator);
        }

        // Layer 2: semantic role matching via CDP accessibility tree
        Optional<WebElement> healed = semanticHealer.heal(
            primaryLocator, role, accessibleName, context);
        if (healed.isPresent()) {
            healingLog.add(new HealingRecord(primaryLocator.toString(),
                "role=" + role + ", name=" + accessibleName,
                "SEMANTIC", Instant.now()));
            return healed.get();
        }

        // Layer 3: BiDi DOM diff — has the element moved?
        Optional<String> newSelector = domDiffHealer.findMovedElement(
            Map.of("role", role, "name", accessibleName),
            getLastKnownGoodSnapshot()
        );
        if (newSelector.isPresent()) {
            healingLog.add(new HealingRecord(primaryLocator.toString(),
                newSelector.get(), "DOM_DIFF", Instant.now()));
            return driver.findElement(By.cssSelector(newSelector.get()));
        }

        // All strategies exhausted — fail with a clear message
        String msg = String.format(
            "Self-healing exhausted for %s (role=%s, name=%s). Manual triage required.",
            primaryLocator, role, accessibleName);
        throw new NoSuchElementException(msg);
    }

    public List<HealingRecord> getHealingLog() { return List.copyOf(healingLog); }

    private String getLastKnownGoodSnapshot() {
        // In CI/CD: fetch from artifact storage (S3, GCS, or GitHub Artifacts)
        return null;
    }

    // Delegate all standard WebDriver methods to the underlying driver
    public void get(String url) { driver.get(url); }
    public String getTitle() { return driver.getTitle(); }
    public void quit() { driver.quit(); }

    public record HealingRecord(
        String original, String healed, String strategy, Instant timestamp
    ) {}
}

CI/CD Integration: Commit the Healing Log

The final piece: when healing happens in CI/CD, commit the log as a build artifact so a human can review the AI’s decisions:

# .github/workflows/selenium-tests.yml
name: Self-Healing Selenium Tests
on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Run tests with self-healing
        run: mvn test -Dtest=LoginTest,CheckoutTest

      - name: Upload healing log
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: healing-log
          path: target/healing-log.json

      - name: Comment healing summary on PR
        if: always()
        run: |
          HEAL_COUNT=$(jq '. | length' target/healing-log.json)
          if [ "$HEAL_COUNT" -gt 0 ]; then
            echo "## 🤖 Self-Healing Report" >> $GITHUB_STEP_SUMMARY
            echo "**$HEAL_COUNT locator(s) healed.** Review the changes:" >> $GITHUB_STEP_SUMMARY
            jq -r '.[] | "- `\(.original)` → `\(.healed)` (\(.strategy))"' \
              target/healing-log.json >> $GITHUB_STEP_SUMMARY
          fi

After the run, your PR gets a summary like:

## 🤖 Self-Healing Report
**3 locator(s) healed. Review the changes:**
- `.btn-submit` → role=button, name=Sign In (SEMANTIC)
- `#checkout-form` → role=form, name=Checkout (SEMANTIC)
- `.cart-item-0` → li:nth-child(1)[data-testid=cart-item] (DOM_DIFF)

The healing log doubles as a change notification for the frontend team — they can see exactly which selectors broke and why.

Wiring it up: The SemanticHealer and SelfHealingDriver in this post store healing records in an in-memory ArrayList. To bridge to the CI/CD workflow above, add a writeHealingLog() method to your healer that serializes getHealingLog() to target/healing-log.json (Jackson or Gson), and call it from your @AfterAll / @AfterSuite teardown hook. That’s the last mile — everything else in the workflow is ready to go.

When to Use Each Strategy

flowchart TD
    START["📍 Element not found"] --> Q1{"Is there a stable<br/>element nearby?"}
    Q1 -->|Yes| REL["Strategy 1<br/>Relative Locator<br/>below() / near() / above()"]
    Q1 -->|No| Q2{"Does the element have<br/>a clear semantic role?<br/>(button, textbox, link)"}
    Q2 -->|Yes| SEM["Strategy 2<br/>AI Semantic Healing<br/>accessibility tree query"]
    Q2 -->|No| Q3{"Did the DOM structure<br/>change significantly?"}
    Q3 -->|Yes| DIFF["Strategy 3<br/>BiDi/CDP DOM Diff<br/>find by fingerprint"]
    Q3 -->|No| FAIL["❌ Manual triage<br/>Human reviews the page"]
    REL --> OK["✅ Healed"]
    SEM --> OK
    DIFF --> OK

Multi-Language Quick Reference

This post used Java examples. Here’s the equivalent syntax across C#, TypeScript, JavaScript, and Python:

Relative Locators

Accessibility Tree Query (CDP)

SelfHealingDriver Wrapper

CI/CD Healing Log Upload

Where Existing Posts Fit

Sources & Further Reading

1. Selenium Relative Locators — official docs for the above(), below(), near() API used in Strategy 1
2. Chrome DevTools Protocol — Accessibility Domain — the CDP API (Accessibility.getFullAXTree) that powers the semantic healer in Strategy 2
3. Selenium CDP (Chrome DevTools Protocol) — official guide to using CDP sessions from Selenium, the bridge between BiDi and Chrome’s native protocol
4. Angie Jones / mcp-selenium — the MCP server whose accessibility tree query inspired the semantic healing approach

What to Do Next

1. Add Relative Locators today. It’s a zero-dependency change — replace your 5 most brittle CSS selectors with RelativeLocator.with().below() / .near(). You’ll see immediate stability improvement in the next CI run.
2. Prototype the SemanticHealer. Take the Java class from this post, wire it up to your existing test suite’s findElement calls, and run it against a page where you’ve deliberately broken a CSS class. Watch the accessibility tree heal it in real time.
3. Set up the healing log in CI/CD. Even without the full three-layer healing engine, logging every NoSuchElementException with the page’s accessibility snapshot gives you data to build the healer with.
4. For Playwright users: The same pattern works — replace driver.findElement() with page.locator() and the CDP accessibility query is identical. The Playwright AI Codegen post covers the TypeScript/JS equivalent.
5. Subscribe to this blog’s feed.xml — next up: a practical guide to building an AI test oracle that judges “did the test actually pass?” by looking at screenshots, not assertions.

See also: AI-Driven Test Strategy: From Copilot to Multi-Agent Orchestration (Jun 2026) — the Phase 4 Cypress self-healing implementation that inspired the Java Selenium version in this post. · XPath for Test Automation (Jul 2026) — the story-mode article with §12 complex XPath & CSS for SDETs (SVG, computed indices, ARIA chains, iframe/shadow-DOM, modern CSS :has()/:is()/:where(), decision flowchart).

If Playwright MCP is like having an AI chauffeur drive your car, AI codegen is like the chauffeur writing you the driver’s manual — so you can replay the journey anytime, tweak the route, and commit it to CI/CD.

This post is the natural next step after the Selenium 2026 and Playwright MCP guides. No prior AI experience needed — just a working Playwright install.

What npx playwright codegen --ai Actually Does

Traditional playwright codegen (no --ai flag) records your clicks and keystrokes and translates them into Playwright scripts mechanically:

Click on button #checkout  →  await page.ClickAsync("#checkout")
Type "test@example.com"   →  await page.FillAsync("#email", "test@example.com")

It works, but it’s brittle. The selectors are whatever CSS path Playwright guesses at the moment of recording. Change the DOM, and the script breaks.

AI codegen (--ai flag, stable since Playwright v1.50) is fundamentally different:

flowchart TD
    A["📝 Natural Language<br/>'Log in with admin credentials<br/>and verify the dashboard shows<br/>3 active projects'"] --> B["🧠 Playwright AI Codegen Engine"]
    
    B --> C["🔍 Page Analysis<br/>(DOM tree + accessibility snapshot)"]
    B --> D["🧩 Step Planner<br/>(breaks intent into actions)"]
    
    C --> E["🎯 Intent-Based Locator Generator"]
    D --> E
    
    E --> F["📍 Locators:<br/>page.GetByRole('button', { name: 'Sign In' })<br/>page.GetByLabel('Email')<br/>page.GetByText('3 active projects')"]
    
    D --> G["📜 Script Generator<br/>(language-specific output)"]
    F --> G
    
    G --> H["💻 Generated Script<br/>await page.GetByLabel('Email').FillAsync('admin@test.com');<br/>await page.GetByRole('button', { name: 'Sign In' }).ClickAsync();<br/>await Expect(page.GetByTestId('project-count')).ToHaveTextAsync('3');"]

The engine doesn’t just record — it understands intent. Instead of generating page.Locator("#email-17abc"), it generates page.GetByLabel("Email") — a semantic locator that survives DOM reshuffles.

Step 1: Basic AI Codegen — From Sentence to Script

Open a terminal and run:

npx playwright codegen --ai https://your-app.com/login

A Chromium window opens alongside the Playwright Inspector. In the inspector, instead of clicking around, type what you want:

Log in with:
  - Email: admin@example.com
  - Password: SuperSecret123!
After login, verify the page title contains "Dashboard"
Click on "Projects" in the sidebar
Verify the project list has at least 5 items

Playwright watches the page, plans the steps, and generates:

// Generated by Playwright AI Codegen — C# / NUnit
using Microsoft.Playwright.NUnit;

public class LoginFlowTests : PageTest
{
    [Test]
    public async Task AdminLoginAndVerifyProjects()
    {
        await Page.GotoAsync("https://your-app.com/login");

        // Fill login form using semantic locators
        await Page.GetByLabel("Email").FillAsync("admin@example.com");
        await Page.GetByLabel("Password").FillAsync("SuperSecret123!");
        await Page.GetByRole(AriaRole.Button, new() { Name = "Sign In" }).ClickAsync();

        // Web-First assertion: auto-waits for title match
        await Expect(Page).ToHaveTitleAsync(new System.Text.RegularExpressions.Regex("Dashboard"));

        // Navigate to Projects
        await Page.GetByRole(AriaRole.Link, new() { Name = "Projects" }).ClickAsync();

        // Assert project list has at least 5 items
        var projectItems = Page.GetByTestId("project-list-item");
        await Expect(projectItems.First).ToBeVisibleAsync();
        
        var count = await projectItems.CountAsync();
        Assert.That(count, Is.GreaterThanOrEqualTo(5));
    }
}

sequenceDiagram
    participant You
    participant Codegen as Playwright AI Codegen
    participant Browser as Chromium Browser
    participant App as Your Web App

    You->>Codegen: "Log in with admin credentials,<br/>verify 3 active projects on dashboard"
    
    Codegen->>Browser: Navigate to /login
    Browser->>App: GET /login
    App-->>Browser: Login page HTML
    
    Codegen->>Codegen: Analyze DOM:<br/>- Find elements with labels "Email", "Password"<br/>- Find button with accessible name "Sign In"<br/>- Plan: Fill → Fill → Click → Assert
    
    Codegen->>Browser: Fill "Email" field
    Codegen->>Browser: Fill "Password" field
    Codegen->>Browser: Click "Sign In"
    Browser->>App: POST /login
    App-->>Browser: Redirect to /dashboard
    
    Codegen->>Codegen: Analyze new page:<br/>- Title contains "Dashboard"?<br/>- Find "3 active projects" text<br/>- Generate assertion
    
    Codegen-->>You: ✅ Script generated:<br/>page.GetByLabel("Email").FillAsync(...)<br/>page.GetByRole(button).ClickAsync()<br/>Expect(page).ToHaveTitleAsync(/Dashboard/)<br/>Expect(page.GetByTestId("project-count")).ToHaveTextAsync("3")

Multi-Language Output

AI codegen supports all Playwright languages. The same natural-language input generates idiomatic code for each:

Step 2: From Requirements Document to Full Test Suite

The real power of AI codegen emerges when you feed it a requirements document instead of one-off instructions. This is the workflow teased in the AI-Driven Test Strategy post — Phase 2 in practice.

The Requirements-to-Tests Pipeline

flowchart LR
    A["📄 Requirements Doc<br/>.md / .txt / Confluence"] --> B["✂️ Split into Scenarios<br/>(AI parses 'happy path',<br/>'edge case', 'error state')"]
    B --> C["🔀 For Each Scenario"]
    C --> D["🎬 playwright codegen --ai"]
    D --> E["📜 Generated Test File"]
    C --> F["🎬 playwright codegen --ai"]
    F --> G["📜 Generated Test File"]
    C --> H["🎬 playwright codegen --ai"]
    H --> I["📜 Generated Test File"]
    E --> J["🧪 Combined Test Suite"]
    G --> J
    I --> J
    J --> K["✅ Ready for CI/CD"]

Practical Example

Say you have this requirements snippet for an e-commerce checkout:

# Checkout Flow Requirements

## Happy Path
- User adds item to cart from product page
- User proceeds to checkout
- User enters valid shipping address
- User selects credit card payment
- User confirms order
- System displays order confirmation with order number
- System sends confirmation email

## Edge Cases
- User tries to checkout with empty cart → show "Cart is empty" message
- User enters invalid credit card → show inline validation error
- User's session expires during checkout → redirect to login, preserve cart

## Error States
- Payment gateway timeout → show "Payment processing, do not refresh" with retry
- Inventory goes out of stock between add-to-cart and checkout → show "Item unavailable" with alternatives

Feed each section separately to AI codegen for best results:

# Happy path
npx playwright codegen --ai https://your-store.com/product/123 \
  --prompt "Add the item to cart, proceed to checkout, fill valid shipping
  address, select credit card payment, confirm order, verify order
  confirmation appears with an order number."

# Edge case: empty cart
npx playwright codegen --ai https://your-store.com/checkout \
  --prompt "Navigate directly to /checkout with an empty cart. Verify
  the page shows 'Cart is empty' and the checkout button is disabled."

# Edge case: invalid credit card
npx playwright codegen --ai https://your-store.com/checkout \
  --prompt "Add an item to cart, go to checkout, enter credit card
  number '0000-0000-0000-0000', verify an inline error appears
  below the card field saying 'Invalid card number'."

# Error state: payment timeout
npx playwright codegen --ai https://your-store.com/checkout \
  --prompt "Complete checkout up to payment step, then simulate a
  payment gateway timeout (use the test card 4444-3333-2222-1111
  which triggers a timeout on this app). Verify 'Payment processing'
  message appears with a retry button."

AI codegen generates a separate test file per scenario. Combine them into a single test class, add a [Test] attribute per method, and you have a complete checkout test suite — generated from the requirements doc in under 10 minutes.

What AI Codegen Gets Right (and Wrong)

The human’s job shifts from writing code to reviewing code. You spend 80% less time typing and 100% more time thinking about what could go wrong.

Step 3: Refining AI-Generated Tests

AI codegen gives you an 80% solution. Here’s how to get to 95%.

Add Test Data Setup

AI codegen works against live pages. It doesn’t know how to seed your database. Add setup methods manually:

[SetUp]
public async Task Setup()
{
    // AI can't generate this — you know your data model
    await ApiClient.SeedAsync(new TestData
    {
        User = new User { Email = "admin@example.com", Role = "Admin" },
        Projects = Enumerable.Range(1, 5).Select(i => new Project { Name = $"Project {i}" }).ToList()
    });

    await Page.GotoAsync("https://your-app.com/login");
}

Replace Hardcoded Values with Test Parameters

AI codegen generates hardcoded values. Parameterize them:

// ❌ AI-generated: hardcoded values
await Page.GetByLabel("Email").FillAsync("admin@example.com");

// ✅ After human refinement: parameterized
[TestCase("admin@example.com", "SuperSecret123!", ExpectedResult = true)]
[TestCase("user@example.com", "wrong-password", ExpectedResult = false)]
public async Task<bool> LoginFlow(string email, string password)
{
    await Page.GetByLabel("Email").FillAsync(email);
    await Page.GetByLabel("Password").FillAsync(password);
    await Page.GetByRole(AriaRole.Button, new() { Name = "Sign In" }).ClickAsync();
    
    return await Page.GetByText("Dashboard").IsVisibleAsync();
}

Add Visual Regression Checks

AI codegen doesn’t generate visual assertions. Add them:

// After AI-generated checkout flow completes
await Expect(Page).ToHaveScreenshotAsync("checkout-confirmation.png", new()
{
    MaxDiffPixelRatio = 0.01f  // Allow 1% pixel difference
});

Step 4: AI Codegen + MCP — Two Sides of the Same Coin

AI codegen and Playwright MCP (from the previous guide) solve different problems:

The Combined Workflow

flowchart TD
    A["📄 Requirements Document"] --> B["🤖 AI Codegen<br/>Generate test scripts"]
    B --> C["👤 Human Review<br/>Add setup, parameterize,<br/>add visual checks"]
    C --> D["🧪 CI/CD Pipeline<br/>Run on every PR"]
    
    D --> E{"Test failed?"}
    E -->|Yes| F["🔍 Playwright MCP<br/>AI agent investigates<br/>Opens browser, inspects DOM,<br/>captures screenshots"]
    F --> G["📊 Diagnostic Report<br/>Root cause + suggested fix"]
    G --> C
    
    E -->|No| H["✅ PR Approved"]

AI codegen creates the tests, MCP debugs them when they fail. Together, they form a self-improving test pipeline — the Phase 4 vision from the AI-Driven Test Strategy post.

Step 5: CI/CD Integration — Generated Tests in Your Pipeline

AI-generated tests slot into any CI/CD pipeline. Here’s a GitHub Actions example:

name: AI-Generated E2E Tests
on:
  pull_request:
    branches: [main]

jobs:
  playwright-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0'
      
      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium
      
      - name: Run AI-generated test suite
        run: dotnet test tests/GeneratedE2E/ --filter "Category=Smoke"
      
      - name: Upload Playwright trace on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-trace
          path: test-results/

Key point: the generated tests use GetByRole, GetByLabel, and GetByTestId — locators that are resilient to DOM changes. Your CI/CD pipeline won’t break because a CSS class was renamed.

Where Existing Posts Fit

This post completes the 2026 Playwright trilogy:

When to Use AI Codegen vs. Alternatives

flowchart TD
    START["🤔 I need Playwright tests"] --> Q1{"Are the requirements<br/>well-documented?"}
    
    Q1 -->|"Yes — I have a spec,<br/>PRD, or Confluence page"| AI["🤖 AI Codegen<br/>Feed requirements →<br/>generate suite →<br/>human review"]
    
    Q1 -->|"No — I'm still<br/>figuring out the flow"| Q2{"Do I need to explore<br/>the app interactively?"}
    
    Q2 -->|Yes| MCP["🧠 Playwright MCP<br/>AI agent drives browser,<br/>you observe + learn"]
    
    Q2 -->|No| MANUAL["✍️ Traditional codegen<br/>Record clicks →<br/>refine selectors manually"]
    
    AI --> REVIEW["👤 Human Review<br/>Add data setup,<br/>parameterize,<br/>visual checks"]
    MCP --> DOC["📝 Document findings<br/>→ Feed to AI codegen<br/>for v2 of tests"]
    MANUAL --> REVIEW
    
    REVIEW --> CI["🧪 Commit to CI/CD"]

Sources & Further Reading

1. Playwright Codegen Documentation — official guide to the test generator, including --ai mode
2. Playwright .NET API Reference — C# API docs for the locator and assertion patterns used throughout
3. Model Context Protocol Specification — the MCP standard that enables the combined AI codegen + MCP debugging workflow in Step 4
4. Angie Jones / mcp-selenium — the original Selenium MCP server for comparison with Playwright’s native @playwright/mcp

What to Do Next

1. Try basic AI codegen right now. Run npx playwright codegen --ai against any public website and type “Log in, verify the page title contains Dashboard, then click the first item in the list.” Watch the semantic locators appear in real time.
2. Feed a real requirements doc. Take a Confluence page or PRD you already have, split it into scenarios, and feed each section to codegen --ai. You’ll have a test suite in under 30 minutes.
3. Combine with MCP for debugging. When an AI-generated test fails in CI, spin up Playwright MCP to investigate the failure interactively instead of staring at a trace file.
4. Compare to Selenium. Read the BiDi vs CDP comparison to understand why Playwright’s native CDP architecture enables AI codegen while Selenium’s WebDriver layer makes it harder.
5. Subscribe to this blog’s feed.xml — next up: self-healing test suites that automatically fix broken locators in CI/CD using the same intent-based AI that powers codegen.

See also: Playwright vs Selenium in 2026 (Jun 2026) — the speed, reliability, and ecosystem comparison that explains why Playwright leads on AI-native features like codegen. · XPath for Test Automation (Jul 2026) — the story-mode article with §12 complex XPath & CSS for SDETs (the locator patterns AI codegen generates that you should review before merging — SVG, computed indices, ARIA chains, iframe/shadow-DOM, modern CSS :has()/:is()/:where())..

This post compares the two approaches side-by-side for the three hardest interaction types: drag-and-drop, network interception, and AI-powered replay. If you read the Selenium 2026 guide and the Playwright MCP guide, this is the next step — going deeper into the protocol layer.

How BiDi and CDP Actually Work

Before comparing code, let’s understand what’s happening under the hood.

flowchart TD
    subgraph "Selenium + WebDriver BiDi"
        A1["🧪 Your Test Code"] -->|"WebDriver BiDi\n(WebSocket)"| B1["🔧 Selenium Server"]
        B1 -->|"BiDi → HTTP translation"| C1["🌐 Browser Driver\n(chromedriver / geckodriver)"]
        C1 -->|"DevTools Protocol"| D1["🖥️ Browser"]
    end

    subgraph "Playwright + Native CDP"
        A2["🧪 Your Test Code"] -->|"Native CDP\n(direct socket)"| D2["🖥️ Browser"]
    end

    style A1 fill:#0ea5c7,color:#fff
    style A2 fill:#34d399,color:#000

The critical difference: Selenium BiDi adds a translation layer. The browser speaks CDP natively, but Selenium wraps it in the WebDriver BiDi protocol — a WebSocket-based standard that all browser vendors agreed on. Playwright skips the translation and talks CDP directly.

The tradeoff: BiDi is simpler but less powerful. CDP is deeper but Chromium-only for the most advanced features.

Drag-and-Drop: From JavaScript Hacks to Protocol-Level Events

In the 2024 drag-and-drop guide, most methods relied on JavaScript fallbacks because Selenium’s Actions class couldn’t reliably trigger custom drag handlers. In 2026, both BiDi and CDP let you fire the raw dragstart, dragover, and drop events that the application is actually listening for.

Selenium BiDi: Dispatch Input Events

BiDi’s input domain lets you synthesize pointer events. You describe the interaction as a sequence of low-level actions:

using OpenQA.Selenium;
using OpenQA.Selenium.Chrome;

using IWebDriver driver = new ChromeDriver();
driver.Navigate().GoToUrl("https://your-app.com/kanban");

var source = driver.FindElement(By.CssSelector(".card[draggable='true']"));
var target = driver.FindElement(By.CssSelector(".column:nth-child(3)"));

// BiDi: use the BrowsingContext to dispatch low-level input events
var browsingContext = driver.GetBrowsingContext();

// Dispatch a pointer down on the source element
await browsingContext.DispatchPointerEventAsync(new()
{
    Type = PointerEventType.PointerDown,
    X = source.Location.X + source.Size.Width / 2,
    Y = source.Location.Y + source.Size.Height / 2
});

// Move the pointer toward the target (multiple small moves for smooth animation)
for (int i = 0; i < 10; i++)
{
    double progress = (i + 1) / 10.0;
    await browsingContext.DispatchPointerEventAsync(new()
    {
        Type = PointerEventType.PointerMove,
        X = source.Location.X + (int)((target.Location.X - source.Location.X) * progress),
        Y = source.Location.Y + (int)((target.Location.Y - source.Location.Y) * progress)
    });
    await Task.Delay(30); // Small delay between moves for natural feel
}

// Release on the target
await browsingContext.DispatchPointerEventAsync(new()
{
    Type = PointerEventType.PointerUp,
    X = target.Location.X + target.Size.Width / 2,
    Y = target.Location.Y + target.Size.Height / 2
});

The advantage: BiDi fires actual pointerdown/pointermove/pointerup events that the browser dispatches natively. No JavaScript injection. No DataTransfer hacks. The application’s dragstart listener fires as if a real user dragged the element.

Playwright CDP: Route and Simulate at the Protocol Level

Playwright can go even deeper — it can intercept and modify the HTML5 drag events before they reach the page:

using Microsoft.Playwright;

var playwright = await Playwright.CreateAsync();
var browser = await playwright.Chromium.LaunchAsync(new() { Headless = false });
var page = await browser.NewPageAsync();

// Playwright's DragAndDropAsync uses CDP under the hood:
// 1. Injects a DataTransfer into the drag event pipeline
// 2. Fires dragstart → dragover → drop → dragend natively
// 3. No JavaScript hacks, no coordinate math
await page.GotoAsync("https://your-app.com/kanban");
await page.DragAndDropAsync(".card[draggable='true']", ".column:nth-child(3)");

Playwright’s DragAndDropAsync is a single call. Under the hood it uses CDP to:

1. Inject a DataTransfer into the drag event pipeline
2. Fire dragstart with the correct payload
3. Fire dragover on each element the cursor passes over
4. Fire drop on the target
5. Fire dragend to clean up

sequenceDiagram
    participant Test as Your Test
    participant BiDi as Selenium BiDi
    participant CDP as Playwright CDP
    participant App as Web Application

    Note over Test,App: Selenium BiDi — explicit pointer events
    Test->>BiDi: DispatchPointerEvent (pointerdown)
    BiDi->>App: pointerdown → dragstart
    Test->>BiDi: DispatchPointerEvent ×10 (pointermove)
    BiDi->>App: pointermove ×10 → dragover ×10
    Test->>BiDi: DispatchPointerEvent (pointerup)
    BiDi->>App: pointerup → drop → dragend
    BiDi-->>Test: ✅ Element moved

    Note over Test,App: Playwright CDP — one call, engine handles details
    Test->>CDP: DragAndDropAsync(source, target)
    CDP->>App: Inject DataTransfer + fire dragstart
    CDP->>App: Calculate path + fire dragover on each element
    CDP->>App: Fire drop on target
    CDP->>App: Fire dragend
    CDP-->>Test: ✅ Element moved

Which Wins for Drag-and-Drop?

Winner: Playwright for simplicity. Selenium BiDi for debugging and Firefox support.

Network Interception: Watch, Modify, and Mock API Calls

Both BiDi and CDP let you intercept network requests mid-flight. This is the superpower that eliminates the need for separate API mocking tools in many cases.

Selenium BiDi: Network Event Subscription

var driver = new ChromeDriver();

// Subscribe to network events BEFORE navigating
var network = driver.Manage().Network;

network.NetworkRequestSent += (_, e) =>
{
    Console.WriteLine($"➡️ {e.RequestMethod} {e.RequestUrl}");
};

network.NetworkResponseReceived += (_, e) =>
{
    var status = e.ResponseStatusCode;
    var icon = status switch
    {
        >= 200 and < 300 => "✅",
        >= 400 and < 500 => "⚠️",
        >= 500 => "❌",
        _ => "ℹ️"
    };
    Console.WriteLine($"{icon} {status} ← {e.ResponseUrl}");
};

network.StartMonitoring();

driver.Navigate().GoToUrl("https://your-app.com/dashboard");

// After navigation, assert every API call succeeded
var failedCalls = network.GetReceivedResponses()
    .Where(r => r.ResponseStatusCode >= 400)
    .ToList();

Assert.IsEmpty(failedCalls, 
    $"Found {failedCalls.Count} failed API calls: " +
    string.Join(", ", failedCalls.Select(c => $"{c.ResponseStatusCode} {c.ResponseUrl}")));

BiDi’s network domain is event-driven: you subscribe to NetworkRequestSent and NetworkResponseReceived, and the browser pushes events to you in real time. No polling, no explicit waits.

Playwright CDP: Route Interception

Playwright’s page.RouteAsync() is more powerful — you can intercept, modify, or mock responses mid-flight:

var page = await browser.NewPageAsync();

// Intercept ALL API calls to /api/
await page.RouteAsync("**/api/**", async route =>
{
    var request = route.Request;

    // Option 1: Let it through but log
    Console.WriteLine($"📡 {request.Method} {request.Url}");

    // Option 2: Mock the response
    if (request.Url.Contains("/api/slow-endpoint"))
    {
        await route.FulfillAsync(new()
        {
            Status = 200,
            ContentType = "application/json",
            Body = """{ "mocked": true, "message": "This response was intercepted by CDP" }"""
        });
        return;
    }

    // Option 3: Let it pass through
    await route.ContinueAsync();
});

await page.GotoAsync("https://your-app.com/dashboard");

// The slow endpoint now returns instantly with mocked data

flowchart LR
    A["🌐 Browser<br/>makes API call"] --> B{"CDP Route<br/>Interceptor"}
    B -->|"Pass through"| C["🔗 Real Backend"]
    B -->|"Mock"| D["📦 Mock Response"]
    B -->|"Modify"| E["✏️ Modified Response"]
    C --> F["📄 Rendered in Page"]
    D --> F
    E --> F

Which Wins for Network Interception?

Winner: Playwright CDP for power and flexibility. Selenium BiDi for simple monitoring — the event subscription model is cleaner for “watch everything and report” scenarios.

AI-Powered Interaction Replay

This is the 2026 differentiator. Both BiDi and CDP can record a user session and replay it through an AI agent that adapts to UI changes.

How It Works

1. RECORD  →  User performs drag-and-drop manually in the browser
2. CAPTURE  →  BiDi/CDP records every event + DOM state at each step
3. DESCRIBE →  AI translates the recording into natural language:
              "Drag the card titled 'Fix login bug' from the 'Backlog'
               column to the 'In Progress' column"
4. REPLAY   →  AI agent executes the description, adapting to layout
               changes (the card moved 50px right? AI finds it by title)
5. HEAL     →  If replay fails, AI analyzes DOM diff and retries with
               an adjusted strategy

flowchart TD
    A["👤 User performs<br/>drag-and-drop manually"] --> B["📹 BiDi / CDP records<br/>every event + DOM snapshot"]
    B --> C["🧠 AI translates recording<br/>into natural language intent"]
    C --> D["🤖 AI agent replays intent<br/>via BiDi / CDP"]
    D --> E{"Did it work?"}
    E -->|Yes| F["✅ Test passed"]
    E -->|No| G["🔍 AI analyzes DOM diff<br/>finds element by semantic role"]
    G --> H["🔄 Retry with adjusted<br/>locator strategy"]
    H --> E

Selenium BiDi + AI Replay

// Step 1: Record a BiDi session
var driver = new ChromeDriver();
var recorder = new BiDiSessionRecorder(driver);

recorder.StartRecording();
driver.Navigate().GoToUrl("https://your-app.com/kanban");

// User performs the drag-and-drop manually (or via Actions)
// ... manual interaction happens here ...

recorder.StopRecording();
var sessionTrace = recorder.GetTrace(); // JSON: every event + timestamps + DOM snapshots

// Step 2: AI translates trace → natural language intent
var intent = await AITranslator.TraceToIntentAsync(sessionTrace);
// Output: "Drag the card with title 'Fix login bug' from column #1 to column #3"

// Step 3: Replay with self-healing
var replayer = new BiDiSessionReplayer(driver);
var result = await replayer.ReplayWithHealingAsync(intent);

if (result.Succeeded)
    Console.WriteLine($"✅ Replayed successfully after {result.Retries} retries");
else
    Console.WriteLine($"❌ Replay failed: {result.Error}");

Playwright CDP + AI Replay

Playwright’s deeper CDP access gives the AI agent more information for self-healing:

// Playwright records a HAR file + DOM snapshots automatically
var context = await browser.NewContextAsync(new()
{
    RecordHarPath = "session-trace.har",
    RecordHarMode = HarMode.Full
});

var page = await context.NewPageAsync();

// CDP: inject a visual marker that tracks element positions
await page.EvaluateAsync(@"() => {
    document.addEventListener('dragstart', e => {
        window.__dragSourceRect = e.target.getBoundingClientRect();
    });
    document.addEventListener('drop', e => {
        window.__dropTargetRect = e.target.getBoundingClientRect();
    });
}");

// User performs interaction...
await page.GotoAsync("https://your-app.com/kanban");
// ... manual drag-and-drop ...

// AI replay with CDP-enhanced healing
var healer = new CDPHealer(page);
await healer.ReplayFromHARAsync("session-trace.har", new()
{
    SemanticFallback = true,  // Find elements by ARIA role + text content
    VisualDiff = true,        // Compare screenshots to detect layout shifts
    MaxRetries = 3
});

When to Use Which

flowchart TD
    START["🤔 I need to automate<br/>a complex interaction"] --> Q1{"Does it involve<br/>drag-and-drop?"}

    Q1 -->|Yes| Q1a{"Do I need Firefox\nsupport?"}
    Q1a -->|Yes| BIDI["🔷 Selenium BiDi<br/>explicit pointer events"]
    Q1a -->|No| CDP1["🟢 Playwright CDP<br/>DragAndDropAsync()"]

    Q1 -->|No| Q2{"Do I need to mock\nor modify API\nresponses?"}
    Q2 -->|Yes| CDP2["🟢 Playwright CDP<br/>route.FulfillAsync()"]
    Q2 -->|No| Q3{"Is this for passive\nnetwork monitoring\nin CI/CD?"}
    Q3 -->|Yes| BIDI_MON["🔷 Selenium BiDi<br/>event subscription"]
    Q3 -->|No| Q4{"Do I need AI-powered\ninteraction replay\nwith self-healing?"}
    Q4 -->|Yes| CDP3["🟢 Playwright CDP<br/>HAR + visual diff"]
    Q4 -->|No| EITHER["🤷 Either works —<br/>pick your ecosystem"]

Rule of thumb:

• Playwright CDP for Chromium-first teams that want maximum power (mock, modify, replay with visual diff)
• Selenium BiDi for cross-browser teams that need Firefox and prefer explicit control over each event

Where Existing Posts Fit

Multi-Language Quick Reference

This post used C# examples. Here’s the equivalent syntax in Java, TypeScript, JavaScript, and Python for key BiDi and CDP operations:

Selenium BiDi — Drag-and-Drop

Selenium BiDi — Network Monitoring

Playwright CDP — Drag-and-Drop

Playwright CDP — Route Interception

Playwright — Browser Launch

TypeScript vs JavaScript: Playwright’s TypeScript API uses the same syntax as JavaScript for most operations — the difference is type safety (const browser: Browser). Both benefit from Playwright’s auto-complete in VS Code.

Sources & Further Reading

1. WebDriver BiDi W3C Specification — the W3C standard for bidirectional browser automation
2. Chrome DevTools Protocol Documentation — the CDP surface Playwright accesses natively and Selenium accesses via BiDi translation
3. Playwright CDP Session API — official docs for the CDP session used in drag-and-drop and network interception examples
4. Selenium WebDriver BiDi Guide — official BiDi documentation including network and input domains

What to Do Next

1. Try the drag-and-drop examples. Take any drag-based UI (Kanban, file upload, sortable list) and test both the BiDi pointer-event approach and Playwright’s DragAndDropAsync(). See which one handles your app’s custom drag handlers.
2. Set up network monitoring in CI. Subscribe to BiDi’s NetworkResponseReceived in your existing Selenium suite. One event handler, and you’ll catch every 500 error your UI tests were silently ignoring.
3. Experiment with AI replay. Record a manual drag-and-drop session in Playwright (HAR recording is built-in), then ask an LLM to describe what happened in natural language. You’ve just built a self-documenting test.
4. Subscribe to this blog’s feed.xml — next up: a deep-dive on self-healing locators and how AI can find elements by their semantic role when CSS selectors break.

See also: AI-Driven Test Strategy: From Copilot to Multi-Agent Orchestration (Jun 2026) — the overarching thesis on multi-agent QA systems, including the self-healing locator pattern referenced above. · Self-Healing Test Suites (Jul 2026) — full implementation: Java SemanticHealer, CDP accessibility tree, DOM diff, CI/CD healing log. · XPath for Test Automation (Jul 2026) — the story-mode article whose §12 maps the complex XPath & CSS patterns you ship selectors around (SVG namespace handling, computed indices, role/state ARIA chains, iframe/shadow-DOM piercing matrix, modern CSS Level 4 selectors, decision flowchart).

If Selenium + MCP is like handing one expert a remote control, Playwright + multi-agent is like giving a team of experts simultaneous access to the same browser session, each watching a different layer of your app from network calls to visual snapshots to accessibility violations.

This guide picks up where the Selenium post left off. No prior Playwright experience needed.

What Makes Playwright Different in 2026

Playwright was already faster than Selenium because it talks to the browser directly through the DevTools Protocol — no WebDriver middleman. In 2026, the gap is even wider:

The biggest beginner win: Playwright auto-waits. You never write Thread.Sleep(3000) or WebDriverWait. The engine pauses until the element is ready — clickable, visible, stable — and only then proceeds.

Architecture Overview

Here’s how the pieces fit together when you add MCP and multi-agent orchestration on top of Playwright:

flowchart TD
    A["👤 You (the tester)"] --> B["💬 Natural Language<br/>'Check the checkout flow<br/>and validate all API calls return 200'"]

    B --> C["🧠 Supervisor Agent<br/>(Claude / Copilot)"]

    C -->|MCP Protocol| D["🔌 Playwright MCP Server<br/>@playwright/mcp"]
    C -->|MCP Protocol| E["📡 API Validator Agent<br/>(parallel worker)"]

    D -->|Native CDP| F["🌐 Browser<br/>(Chromium / Firefox / WebKit)"]
    E -->|HTTP| G["🔗 Backend APIs"]

    F -->|Screenshots + DOM + HAR| D
    G -->|JSON responses| E

    D -->|"✅ UI: Checkout button clicked<br/>📸 Screenshot captured"| C
    E -->|"✅ API: /cart returned 200<br/>⚠️ /checkout returned 422"| C

    C -->|"📊 Combined Report:<br/>UI passed, API validation error at /checkout"| A

The Supervisor agent delegates to two workers simultaneously: the Playwright MCP server drives the browser while the API Validator watches every network call. If the UI looks right but an API returns an error, you catch it immediately — no separate API test suite needed.

Step 1: Install Playwright (60 Seconds)

Playwright bundles its own browser binaries. One command installs everything.

.NET / C#:

dotnet new nunit -n MyFirstPlaywrightTest
cd MyFirstPlaywrightTest
dotnet add package Microsoft.Playwright.NUnit
dotnet build
playwright install

Python:

pip install playwright
playwright install

JavaScript / Node.js:

npm init playwright@latest
# Select "TypeScript" or "JavaScript" when prompted

That’s it. No WebDriver binaries, no PATH configuration, no chromedriver.exe version mismatch. Playwright downloads the exact browser versions it expects into a local cache.

Step 2: Your First Test — Web-First Assertions

Create a test file. Here’s the C# version (Python and JS versions follow the same pattern):

using Microsoft.Playwright.NUnit;
using System.Threading.Tasks;

public class FirstTest : PageTest
{
    [Test]
    public async Task HelloPlaywright()
    {
        // Navigate — Playwright auto-waits for the page to load
        await Page.GotoAsync("https://www.google.com");

        // Type into the search box — auto-waits for the element to be visible
        await Page.FillAsync("textarea[name='q']", "Playwright MCP 2026");

        // Press Enter
        await Page.PressAsync("textarea[name='q']", "Enter");

        // Web-First Assertion: auto-retries until the title matches or times out
        await Expect(Page).ToHaveTitleAsync(new System.Text.RegularExpressions.Regex("Playwright"));
    }
}

sequenceDiagram
    participant Test as Your Test Code
    participant PW as Playwright Engine
    participant Browser as Chromium Browser

    Test->>PW: Page.GotoAsync("google.com")
    PW->>Browser: Navigate
    Browser-->>PW: Page loaded (DOMContentLoaded)
    PW-->>Test: Ready

    Test->>PW: Page.FillAsync("textarea[name='q']", "...")
    PW->>PW: Auto-wait: is the textarea visible? stable? enabled?
    PW->>Browser: Type text
    Browser-->>PW: Text filled
    PW-->>Test: Done

    Test->>PW: Expect(Page).ToHaveTitleAsync(/Playwright/)
    PW->>Browser: Get page title
    Browser-->>PW: "Playwright MCP 2026 - Google Search"
    PW->>PW: Assert: does title match /Playwright/?
    PW-->>Test: ✅ PASS

Key takeaway: you wrote zero wait logic. FillAsync waited for the element to be visible. Expect auto-retried until the condition was true. This is the Playwright baseline — no flaky tests, no manual timeout tuning.

Step 3: Web-First Assertions — Why You Never Write Thread.Sleep Again

In traditional Selenium, you spend 30% of your test code on waits:

// ❌ Old way: guess how long to wait
Thread.Sleep(3000);
var text = driver.FindElement(By.ClassName("success-message")).Text;
Assert.AreEqual("Order confirmed", text);

Playwright’s Web-First Assertions have built-in auto-retry. You describe the expected state, and Playwright polls the browser until that state is true (or a 5-second default timeout expires):

// ✅ Playwright way: describe the outcome, let the engine wait
await Expect(Page.Locator(".success-message")).ToHaveTextAsync("Order confirmed");

// More Web-First assertion examples:
await Expect(Page.Locator("button#submit")).ToBeEnabledAsync();
await Expect(Page.Locator(".error-banner")).ToBeVisibleAsync();
await Expect(Page.Locator(".cart-count")).ToContainTextAsync("3");
await Expect(Page.Locator("input#email")).ToHaveValueAsync("user@example.com");

Each assertion polls the browser every ~100ms for up to 5 seconds. If the condition becomes true at 300ms, it passes immediately — no wasted time.

Multi-Language Assertion Patterns

All three follow the same pattern: expect(locator).<condition>(expectedValue). The auto-retry logic is identical across languages.

Step 4: Playwright MCP Server — Let AI Drive the Browser

This is the step that makes Playwright feel like the future. MCP (Model Context Protocol) turns your AI agent into a browser operator.

How Playwright MCP Differs from Selenium MCP

In the Selenium 2026 guide, you set up selenium-mcp — a Python package that translates AI commands into WebDriver calls. Playwright MCP is simpler and faster:

• Zero-config install — one npm package, no Python dependency
• Native CDP — no WebDriver protocol overhead
• Full Playwright surface — network interception, HAR recording, mobile emulation, visual comparison, all exposed as MCP tools
• Auto-wait baked in — the AI says “click the login button” and Playwright handles timing

Setup (3 Minutes)

1. Install the Playwright MCP server:

npm install -g @playwright/mcp

2. Register it with Claude Desktop.

Open your Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the Playwright MCP entry:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"],
      "env": {
        "PLAYWRIGHT_HEADLESS": "false"
      }
    }
  }
}

3. Restart Claude Desktop. You’ll see a new tool icon for Playwright. 🔌

4. Start talking to your browser:

You:    "Go to https://the-internet.herokuapp.com/add_remove_elements/,
         click 'Add Element' three times, then click 'Delete' on the
         second button. How many buttons are left?"

Claude: [Opens Chromium, navigates, clicks Add Element ×3, clicks
         Delete on button #2]
        "There are 2 buttons remaining. Screenshot attached."

flowchart LR
    subgraph "Your Machine"
        A["💬 'Add 3 elements, delete the 2nd, count remaining'"] --> B["Claude Desktop"]
        B <-->|MCP| C["@playwright/mcp"]
        C <-->|Native CDP| D["Chromium Browser"]
        D --> E["🌐 Target Website"]
    end
    F["📸 Screenshot: 2 buttons remain"] --> B

What the Playwright MCP Server Exposes

The AI agent can call these tools directly — you don’t write the code:

Step 5: Multi-Agent Testing — Two Agents, One Test Run

This is where Playwright in 2026 surpasses everything else. Multi-agent testing means you run two or more AI agents in parallel, each watching a different layer of your application, coordinated by a single Supervisor.

The Supervisor-Worker Pattern

 ┌─────────────────────────────────────┐
 │         Supervisor Agent            │
 │  "Test the checkout flow and        │
 │   validate all API responses."      │
 └──────────┬──────────────┬───────────┘
            │              │
      ┌─────▼─────┐  ┌─────▼──────────┐
      │  Explorer │  │  API Validator  │
      │  Agent    │  │  Agent          │
      │ (Playwright│  │ (Network        │
      │  MCP)     │  │  Inspector)     │
      └─────┬─────┘  └─────┬──────────┘
            │              │
   Clicks buttons,    Intercepts every
   fills forms,       XHR/fetch call,
   takes screenshots  validates status
            │         codes + payloads
            │              │
      ┌─────▼──────────────▼─────┐
      │     Combined Report      │
      │  ✅ UI: All steps passed │
      │  ⚠️ API: /checkout 422  │
      └──────────────────────────┘

Here’s what happens step-by-step:

sequenceDiagram
    participant You
    participant Supervisor as Supervisor Agent
    participant Explorer as Explorer Agent<br/>(Playwright MCP)
    participant Validator as API Validator Agent
    participant Browser as Chromium Browser
    participant Backend as Backend APIs

    You->>Supervisor: "Test checkout flow, validate all APIs"

    Note over Supervisor: Splits work into two parallel tasks

    par Explorer drives the browser
        Supervisor->>Explorer: "Navigate to /cart, click Checkout, fill payment form, submit"
        Explorer->>Browser: Go to /cart
        Browser-->>Explorer: Page loaded
        Explorer->>Browser: Click "Checkout"
        Browser-->>Explorer: Navigation to /checkout
        Explorer->>Browser: Fill payment form + Submit
        Browser-->>Explorer: Order confirmation page
        Explorer-->>Supervisor: "✅ Checkout UI completed. Screenshot attached."
    and Validator inspects network
        Supervisor->>Validator: "Watch all network calls, flag any non-2xx response"
        Browser->>Backend: GET /api/cart
        Backend-->>Browser: 200 OK
        Validator-->>Validator: ✅ /api/cart → 200
        Browser->>Backend: POST /api/checkout
        Backend-->>Browser: 422 Unprocessable Entity
        Validator-->>Validator: ⚠️ /api/checkout → 422
        Browser->>Backend: POST /api/orders
        Backend-->>Browser: 201 Created
        Validator-->>Validator: ✅ /api/orders → 201
        Validator-->>Supervisor: "⚠️ 1 API error: POST /checkout returned 422"
    end

    Supervisor->>You: "📊 UI flow completed successfully, but POST /api/checkout returned 422 — possible validation error in payment payload. Review screenshot + network log."

Concrete Example: Running a Multi-Agent Test

You don’t need a custom framework to start. Here’s a practical three-step workflow using tools you already have:

Step 1 — Write a Playwright script that records everything:

using Microsoft.Playwright;
using System.Text.Json;

// Explorer Agent: navigate the checkout flow, capture every detail
var playwright = await Playwright.CreateAsync();
var browser = await playwright.Chromium.LaunchAsync(new() { Headless = false });
var context = await browser.NewContextAsync(new()
{
    // Record every network request and response
    RecordHarPath = "checkout-trace.har",
    RecordHarMode = HarMode.Full
});

var page = await context.NewPageAsync();

// Collect all API responses for the Validator to inspect
var apiResponses = new List<object>();
page.Response += (_, response) =>
{
    apiResponses.Add(new
    {
        url = response.Url,
        status = response.Status,
        method = response.Request.Method,
        timestamp = DateTime.UtcNow
    });
};

// Explorer: run the flow
await page.GotoAsync("https://your-app.com/cart");
await page.ClickAsync("button#checkout");
await page.FillAsync("input#card-number", "4111111111111111");
await page.FillAsync("input#expiry", "12/28");
await page.ClickAsync("button#place-order");

// Take a final screenshot for visual validation
await page.ScreenshotAsync(new() { Path = "checkout-final.png", FullPage = true });

// Save the API trace for the Validator agent
File.WriteAllText("api-responses.json",
    JsonSerializer.Serialize(apiResponses, new JsonSerializerOptions { WriteIndented = true }));

await browser.CloseAsync();

Step 2 — The Validator agent checks the collected data:

// Define the response record that matches what the Explorer captured
public record ApiResponse(string Url, int Status, string Method, DateTime Timestamp);

// Validator Agent: read the Explorer's output and verify constraints
var responses = JsonSerializer.Deserialize<List<ApiResponse>>(
    File.ReadAllText("api-responses.json"));

var errors = responses
    .Where(r => r.Status < 200 || r.Status >= 300)
    .ToList();

if (errors.Any())
{
    Console.WriteLine($"⚠️ {errors.Count} API error(s) detected:");
    foreach (var err in errors)
        Console.WriteLine($"  {err.Method} {err.Url} → {err.Status}");
}
else
{
    Console.WriteLine("✅ All API calls returned 2xx");
}

// Validate critical endpoints were called
var requiredEndpoints = new[] { "/api/cart", "/api/checkout", "/api/orders" };
foreach (var endpoint in requiredEndpoints)
{
    var found = responses.Any(r => r.Url.Contains(endpoint));
    Console.WriteLine(found
        ? $"✅ Required endpoint {endpoint} was called"
        : $"❌ Missing required endpoint: {endpoint}");
}

Step 3 — The Supervisor agent (you, or an LLM) reviews both outputs:

• Explorer report: screenshot shows the order confirmation page — UI passed ✅
• Validator report: /api/checkout returned 422 — API validation error ⚠️
• Verdict: the frontend rendered a success page, but the backend rejected the payment payload. This bug would be invisible in a UI-only test.

Why Multi-Agent Catches What Single-Agent Misses

Step 6: When to Use Each Approach

After setting up all three layers (Raw Playwright, Playwright MCP, Multi-Agent), here’s how to choose:

flowchart TD
    START["🤔 I need to test a web application"] --> Q1{"Is this an exploratory<br/>or one-off task?"}
    Q1 -->|Yes| Q1a{"Do I need to validate<br/>API calls AND UI in the<br/>same session?"}
    Q1a -->|Yes| MULTI["🧠 Multi-Agent<br/>(Explorer + Validator<br/>in parallel)"]
    Q1a -->|No| MCP["🤖 Playwright MCP<br/>+ AI agent<br/>natural language control"]
    Q1 -->|No| Q2{"Is this a repeatable<br/>CI/CD test suite?"}
    Q2 -->|Yes| Q2a{"Do I need network-level<br/>assertions (API status,<br/>payload validation)?"}
    Q2a -->|Yes| RAW_HAR["✍️ Raw Playwright + HAR recording<br/>+ separate Validator script"]
    Q2a -->|No| RAW["✍️ Raw Playwright<br/>with Web-First Assertions"]
    Q2 -->|No| Q3{"Am I prototyping a new<br/>feature and want quick<br/>feedback?"}
    Q3 -->|Yes| MCP
    Q3 -->|No| MULTI

• Raw Playwright + Web-First Assertions → best for CI/CD regression suites where you need fast, deterministic results with no AI variability.
• Playwright MCP + AI agent → best for exploratory testing, accessibility audits, one-off validations, and prototyping.
• Multi-Agent (Explorer + Validator) → best for end-to-end flows where you cannot afford to miss a single API error or frontend-backend mismatch.

Where Existing Posts on This Blog Fit

This post is the 2026 Playwright refresh that connects to four earlier articles on techtalkwith-veeresh:

Sources & Further Reading

1. Playwright Documentation — official guides, API references, and best practices for all languages
2. Playwright for .NET — C#-specific API reference used in this post’s code examples
3. microsoft/playwright-mcp on GitHub — the official Playwright MCP server, installable via npx @playwright/mcp
4. Model Context Protocol Specification — the open protocol that enables AI agents to control browsers and other tools

What to Do Next

1. Run Step 1–2 right now. Install Playwright and write the Hello World test. It takes under 3 minutes, and the auto-wait behavior will immediately click — you’ll never want to write Thread.Sleep again.
2. Try Playwright MCP. If you have Claude Desktop, add the @playwright/mcp config and ask it to navigate to any site. Compare the experience to the Selenium MCP setup — you’ll notice the speed difference immediately.
3. Experiment with multi-agent. Take any existing Playwright test, add HAR recording, and write a 15-line Validator that checks for non-2xx responses. You’ll probably find a bug your UI test was silently ignoring.
4. For CI/CD pipelines: stick with raw Playwright + Web-First Assertions. MCP and multi-agent add AI variability — fine for exploration, not ideal for deterministic pass/fail gates.
5. Subscribe to this blog’s feed.xml — next up: a deep-dive on Playwright’s AI codegen (npx playwright codegen --ai) and how to generate an entire test suite from a requirements document.

See also: AI-Driven Test Strategy: From Copilot to Multi-Agent Orchestration (Jun 2026) — the overarching thesis on how multi-agent systems are reshaping QA, from test generation to self-healing suites. · Playwright AI Codegen in 2026 (Jul 2026) — the deep-dive teased above: generating test suites from natural language.

Why this card exists: XPath 1.0 is the lingua franca of legacy Selenium suites. CSS 2/3 + Level 4 + Playwright ARIA selectors cover the same ground across more runners, but the patterns don’t map 1:1. This card lets you audit existing XPath and propose a CSS-or-engine equivalent for each — without losing stability intent.

Quick-reference tables

Five categories cover ~90% of the XPath you’ll find in a real suite. Use the cross-references in the § column to jump to the matching cheatsheet row.

A. Text match

B. Structural nth

C. Ancestor / reverse navigation

D. Attribute complex predicates

E. Boolean and combinator choices

F. State-driven predicates

The “no clean CSS translation exists” catalog

These XPath patterns have no pure CSS equivalent — they require engine selectors (Playwright ARIA / text), framework boundary APIs, or stay XPath forever. Don’t fight them; recognize and route around:

Worked-through usage examples

Before you start — what XPath and CSS actually mean. Think of the page like a city map. XPath is like giving driving directions based on relative landmarks: “Go to the third street from the corner, then find the first door.” CSS is like addressing by traits: “Find the house with a red door, then find the mailbox.” They both end up at the same element, but they calculate the route entirely differently. XPath can move forward, backward, and sideways through the DOM (Document Object Model — the browser’s in-memory tree of every element on the page); CSS can only move forward but runs ~25% faster. Tables A–F below show the same target written in both languages.

Anatomy of a CSS selector

When a test runner sees something like button[type='submit']:not([disabled]), it does not read the whole string at once — it processes left-to-right, peeling off one filter at a time. Picture it like a bouncer checking a guest list:

flowchart LR
    classDef node fill:#1e293b,stroke:#38bdf8,color:#f0f2f7,stroke-width:1px
    classDef match fill:#0ea5c7,stroke:#fff,color:#fff,font-weight:bold,stroke-width:2px

    In["button[type='submit']:not([disabled])"]:::node
    S1["1. Match tag<br>find every button on the page"]:::node
    S2["2. Filter by attribute<br>keep only type='submit'"]:::node
    S3["3. Filter by pseudo-class<br>exclude any that are disabled"]:::node
    Out["Matched DOM element(s)"]:::match

    In --> S1 --> S2 --> S3 --> Out

The same left-to-right peeling happens with XPath — //button[@type='submit' and not(@disabled)] literally says the same thing in another dialect. That’s why this appendix exists: not because one is “better”, but because one runner prefers one and a different runner prefers the other.

Tables A–F compare selector strings. The three scenarios below show them wired through a real DOM → Page Object → spec → assertion chain. Every scenario cross-references its source rows so you can audit each selector against the table claim. All XPath below uses strict XPath 1.0 discipline (writing XPath without using 2.0+ features like lower-case() / regex / FLWOR that standard browsers silently ignore) per cheatsheet §4⚠️.

Scenario 1 — Login form: A2 + E1 + F1

A textbook text-match + state-driven form, against the-internet.herokuapp.com/login:

<form id="login">
  <input name="username">
  <input name="password" type="password">
  <button type="submit">Sign in</button>
</form>

Picture that form as a tiny tree — three children hanging off the form, one of them glowing because it’s what we’re hunting for:

flowchart TD
    classDef elt fill:#1e293b,stroke:#9ca3b8,color:#f0f2f7,stroke-width:1px
    classDef target fill:#0ea5c7,stroke:#fff,color:#fff,font-weight:bold,stroke-width:2px

    Form["form#login<br>(the parent)"]:::elt
    U["input[name='username']<br>✗ not a button"]:::elt
    P["input[name='password']<br>✗ not a button"]:::elt
    B["button[type='submit']<br>(Sign in) ✓ this is our target"]:::target

    Form --> U
    Form --> P
    Form --> B

Now read the CSS selector button[type='submit']:not([disabled]) like English:

Plain English walk-through

• button — “find every <button> tag in the page.” (Skips the two inputs immediately.)
• [type='submit'] — “…but only the ones whose type attribute is exactly the word submit.”
• :not([disabled]) — “…and throw away any that currently have the disabled attribute.” (disabled is a state-driven property — it changes at runtime; a button can be enabled when the form loads and disabled when the user types nothing.)

Result: one element, the enabled Pay/Sign-in button. The CSS row maps to F1 (state-driven) and E1 (boolean combo) in the tables above.

Locator forms (rows cited for rationale):

Page Object (TS strict, constructor-body init per cheatsheet §10.1):

import type { Page, Locator } from "playwright";

export class LoginPage {
  private readonly page: Page;
  readonly form: Locator;
  readonly username: Locator;
  readonly password: Locator;
  readonly submitBtn: Locator;

  constructor(page: Page) {
    this.page = page;
    // Tag + ID beats compound predicates here
    this.form     = page.locator("form#login");
    this.username = this.form.locator("input[name='username']");
    this.password = this.form.locator("input[name='password']");
    // E1 + F1: type='submit' AND not(:disabled)
    this.submitBtn = this.form.locator("button[type='submit']:not([disabled])");
  }

  async loginAs(user: string, pass: string): Promise<void> {
    await this.username.fill(user);
    await this.password.fill(pass);
    await this.submitBtn.click();
  }
}

Selenium Java equivalent (for cross-runner parity):

import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;

public class LoginPage {
  private final WebDriver driver;
  private final By form      = By.cssSelector("form#login");
  private final By username  = By.cssSelector("input[name='username']");
  private final By password  = By.cssSelector("input[name='password']");
  private final By submitBtn = By.cssSelector("button[type='submit']:not([disabled])");
  public LoginPage(WebDriver driver) { this.driver = driver; }
  public LoginPage loginAs(String user, String pass) {
    driver.findElement(username).sendKeys(user);
    driver.findElement(password).sendKeys(pass);
    driver.findElement(submitBtn).click();
    return this;
  }
}

Spec snippet — asserts on URL and a state, not on in-DOM text:

import { test, expect } from "@playwright/test";
import { LoginPage } from "./pages/LoginPage";

test.describe("Scenario 1 · login (A2 + D6 + E1 + F1)", () => {
  test("valid creds redirect to /secure", async ({ page }) => {
    const lp = new LoginPage(page);
    await page.goto("https://the-internet.herokuapp.com/login");
    await lp.loginAs("tomsmith", "SuperSecretPassword!");
    await expect(page).toHaveURL(/\/secure$/);
    await expect(page.getByRole("button", { name: "Logout" })).toBeVisible();
  });
});

Verdict: ship the Playwright engine form as primary (getByRole('button', { name: 'Sign in' })) for accessibility-first intent; keep button[type='submit']:not([disabled]) as the CSS fallback for Cypress + Selenium 4. Skip the XPath here — three readings of the same intent aren’t worth the maintenance tax.

Scenario 2 — Dynamic striped table: A4 + B3 + D8 + F5

A managing-listings table from the-internet’s Sortable Data Tables page. Find the rows whose status column reads Open (case-insensitive), restricted to odd table rows:

<table>
  <thead><tr><th>Last Name</th><th>First Name</th><th>Email</th><th>Status</th></tr></thead>
  <tbody>
    <tr><td>Smith</td><td>John</td><td>jsmith@example.com</td><td class="status status-open">OPEN</td></tr>
    <tr><td>Bach</td><td>Frank</td><td>fbach@example.com</td><td class="status status-closed">Closed</td></tr>
    <tr><td>Doe</td><td>Jason</td><td>jdoe@example.com</td><td class="status status-open">Open</td></tr>
    <tr><td>Conway</td><td>Tim</td><td>tconway@example.com</td><td class="status status-closed">Closed</td></tr>
  </tbody>
</table>

Here’s the same table drawn as a tree — odd rows stand out (alternate shading, like real spreadsheets), and the rows whose Status column text is “Open-ish” are marked:

flowchart TD
    classDef odd fill:#1e293b,stroke:#38bdf8,color:#f0f2f7,stroke-width:1px
    classDef even fill:#0f1119,stroke:#6b7394,color:#6b7394,stroke-width:1px
    classDef match fill:#0ea5c7,stroke:#fff,color:#fff,font-weight:bold,stroke-width:2px
    classDef head fill:#1e293b,stroke:#fbbf24,color:#f0f2f7,stroke-width:1px

    T["table"]:::head
    TH["thead — header row<br>(excluded — not a body row)"]:::head
    R1["tr:nth-child(odd) — Smith<br>OPEN ✓ matches"]:::odd
    R2["tr:nth-child(even) — Bach<br>(skipped, not odd)"]:::even
    R3["tr:nth-child(odd) — Doe<br>Open ✓ matches"]:::odd
    R4["tr:nth-child(even) — Conway<br>(skipped, not odd)"]:::even

    T --> TH
    T --> R1
    T --> R2
    T --> R3
    T --> R4

Now decode tr:nth-child(odd) td[class*='open' i] like English:

Plain English walk-through

• tr — “only look at table rows.” (<thead> lives in a different parent, so its <th> cells are out of scope.)
• :nth-child(odd) (B3) — “…and only the rows whose position among their tbody siblings is 1, 3, 5, …” — Inside <tbody>, Smith is the 1st child (odd ✓), Bach the 2nd (skip), Doe the 3rd (odd ✓), Conway the 4th (skip). So :nth-child(odd) keeps Smith and Doe only — Conway is :nth-child(4) and is skipped.
• td (the column we care about) — “…inside those odd rows, examine the cells.”
• [class*='open' i] (D8) — “…keep cells whose class attribute contains the substring open (*= means “contains”), and do it case-insensitively (i means 'open', 'OPEN', and 'Open' all match). The fixture encodes state in the class: open rows carry class="status status-open" and closed rows carry class="status status-closed". So [class*='open' i] literally matches Smith’s and Doe’s cells and skips Bach’s and Conway’s.

In plain English: “In the body rows whose position is 1 or 3, find the Status cells whose class contains the word open — regardless of capitalization.” Smith and Doe match; Bach and Conway don’t.

(Note: the element-level alternative is page.locator('tr').nth(0) / .nth(2) for the 0-indexed engine equivalent — nth-child() is 1-indexed and tag-specific, so it does not always match .nth() intent. Use the explicit index when count restarts mid-row.)

The XPath equivalent uses the clunky translate() function (a workaround from XPath 1.0 that maps every uppercase letter A–Z to its lowercase a–z, then compares) instead of lower-case() because lower-case() is XPath 2.0+ and silently returns nothing in browsers. The CSS [class*='open' i] flag is shorter and faster.

Locator forms:

⚠️ The XPath version above uses translate() per article §12.7 / cheatsheet §11.6 — do not substitute lower-case(); WebDriver silently fails on XPath 2.0 functions. Use the CSS [attr*='open' i] form wherever the runner supports CSS Level 4.

Page Object (TS):

export class OrdersTablePage {
  private readonly page: Page;
  readonly rows: Locator;
  // B3: odd rows only, used in two spec variants
  readonly oddRows: Locator;

  constructor(page: Page) {
    this.page = page;
    this.rows = page.locator("table tbody tr");
    // B3 mod 2 = 1 → CSS nth-child(odd); D8 attribute case-insensitive flag
    this.oddRows = this.rows.filter({
      has: page.locator("td:nth-child(4):has-text(/open/i)"),
    });
  }

  async oddOpenRows(): Promise<readonly string[]> {
    return await this.oddRows.allInnerTexts();
  }
}

Spec snippet — verifies behavior across the row alphabetization:

import { test, expect } from "@playwright/test";
import { OrdersTablePage } from "./pages/OrdersTablePage";

test.describe("Scenario 2 · striped table (A4 + B3 + D8 + F5)", () => {
  test("odd rows show 'Open' status regardless of case/ordering", async ({ page }) => {
    const tp = new OrdersTablePage(page);
    await page.goto("https://the-internet.herokuapp.com/tables");
    const openRows = await tp.oddOpenRows();
    expect(openRows.length).toBeGreaterThan(0);
    for (const text of openRows) expect(text.toLowerCase()).toContain("open");
  });
});

Verdict: B3’s CSS tr:nth-child(odd) is faster than position() mod 2 = 1 by ~25% in headless Chromium (per cheatsheet §11.8 row on speed), and D8’s i attribute flag is shorter than translate(). Ship CSS + filter-hasText regex as the primary; keep the XPath version only in your Selenium 3 / older-Cypress fallback file.

Scenario 3 — Reverse-tree ARIA: C1 + C2 + X3 hint

A settings panel whose sections anchor on their header text, and one of those settings lives inside a shadow-rooted payment-form component:

<section>
  <h2>Billing</h2>
  <input name="card" type="text">
  <payment-form>
    <template shadowrootmode="open"><button>Pay</button></template>
  </payment-form>
</section>

That section has two stories: the light DOM (the <section>, <h2>, and <input>) and a shadow root (a private mini-DOM tree inside <payment-form> that ordinary selectors can’t see). Picture it as a building with a fenced-off inner courtyard:

flowchart TD
    classDef visible fill:#1e293b,stroke:#9ca3b8,color:#f0f2f7,stroke-width:1px
    classDef wall fill:none,stroke:#f87171,stroke-width:3px,stroke-dasharray:4 4
    classDef target fill:#0ea5c7,stroke:#fff,color:#fff,font-weight:bold,stroke-width:2px

    S["section<br>(light DOM)"]:::visible
    H["h2 — Billing"]:::visible
    I["input[name='card']"]:::visible
    P["payment-form<br>━━━━━━━━━━━━<br> shadow root wall"]:::visible
    Pay["button — Pay<br>(inside shadow root)"]:::target

    S --> H
    S --> I
    S --> P
    P -. ">>>&nbsp;(pierce&nbsp;the&nbsp;wall)" .-> Pay
    linkStyle 3 stroke:#f87171,stroke-width:2px,color:#f87171

Now read those selectors like English:

Plain English walk-through

• section:has(h2) (C2) — “find a <section>, but only if it contains an <h2> somewhere inside.” The :has(...) pseudo-class is CSS Level 4’s “parent selector” — the only way in CSS to ask “does this element have a matching child?” It’s the reverse-trip answer to “I know the heading, where’s its section?”
• form:has(input[name='card']) (C1) — “find a <form>, but validate it by checking that it contains an <input> whose name is card.” Same reverse trick, different starting tag.
• page.locator('payment-form').locator('>>> button') (X3) — “go to <payment-form>, then >>> pierces the shadow boundary to find a <button> inside the shadow tree.” The shadow root is a private mini-DOM that the web component owns; CSS rules and most XPaths stop at the boundary like a fence, but >>> is Playwright’s crowbar. The Selenium equivalent requires (SearchContext) shadowRoot.findElement(...) after getShadowRoot() — more ceremony, same result.

Net reading: “Find the Billing section, take its card input, then click the Pay button even though Pay lives behind a shadow-root fence.”

Locator forms:

Page Object (TS):

export class SettingsPage {
  private readonly page: Page;
  readonly billingSection: Locator;
  readonly cardInput: Locator;
  readonly paymentFormRoot: Locator;
  readonly payButton: Locator;

  constructor(page: Page) {
    this.page = page;

    // C2: section-by-aria-heading via filter({ has })
    this.billingSection = page.locator("section").filter({
      has: page.getByRole("heading", { name: "Billing" }),
    });
    // C1: form-by-input via :has() equivalent
    this.cardInput = this.billingSection.locator("input[name='card']");

    // X3: payment-form lives in shadow DOM. >>> pierces open shadow roots.
    // Pure XPath cannot reach across the boundary — fall back to a chained selector.
    this.paymentFormRoot = page.locator("payment-form");
    this.payButton       = this.paymentFormRoot.locator(">>> button");
  }

  async enterCardAndPay(cardNumber: string): Promise<void> {
    await this.cardInput.fill(cardNumber);
    await this.payButton.click();          // pierces shadow root automatically
  }
}

Spec snippet — confirms both the cross-section reverse (C1 + C2) and the shadow-DOM pay action (X3):

import { test, expect } from "@playwright/test";
import { SettingsPage } from "./pages/SettingsPage";

test.describe("Scenario 3 · reverse tree + shadow DOM (C1 + C2 + F3 + X3)", () => {
  test("card input inside the Billing section pays through shadow root", async ({ page }) => {
    const sp = new SettingsPage(page);
    await page.goto("https://the-internet.herokuapp.com/settings");  // illustrative
    await sp.enterCardAndPay("4111111111111111");
    await expect(sp.paymentFormRoot).toContainText(/paid/i);
  });
});