Create a QA Engineer Agent in OpenCode for Automated Playwright Testing

Modern web applications require reliable, maintainable test suites — but writing end-to-end tests manually is slow, repetitive, and often falls behind fast-moving development cycles. This article shows you how to solve that by creating a dedicated QA Engineer agent in OpenCode, an AI-powered CLI built around customizable agents. Combined with Playwright's browser automation capabilities, this agent can explore your application, generate structured test plans, and produce executable TypeScript tests — all guided by natural language instructions.

We'll use Claude Sonnet 4.5 (claude-sonnet-4-5) as our underlying language model throughout.

Note on experimental tooling: Some of the Playwright agent capabilities referenced in this article (playwright-planner, playwright-generator, playwright-healer) are part of an experimental integration layer between OpenCode and Playwright's AI tooling. Verify the current availability of these features against the OpenCode documentation and the @playwright/test release notes before using them in production workflows.

Prerequisites

Before getting started, make sure you have the following in place:

Node.js 18+ and npm installed
A web application running locally (we'll use http://localhost:3000 in examples)
Basic familiarity with Playwright and TypeScript

Installation and Setup

Start by installing OpenCode and initializing Playwright in your project:

bash
# Install OpenCode — a Go-based CLI for AI-assisted development
curl -fsSL https://opencode.ai/install.sh | sh

# Initialize Playwright inside your project directory
# This creates playwright.config.ts and an example test
npm init playwright@latest

# Install the Playwright test runner globally for easy CLI access
npm install -g @playwright/test

# Set up Playwright's experimental AI agent integration with OpenCode
# The --loop=opencode flag wires the Planner, Generator, and Healer agents
# into OpenCode's terminal session loop
npx playwright init-agents --loop=opencode

The --loop=opencode flag is what connects Playwright's agent system to OpenCode's interface. Without it, the agents operate as standalone tools rather than as part of an interactive OpenCode session.

Configuring OpenCode for Playwright

In the root of your Playwright project, create an opencode.json file. This is how you tell OpenCode which model to use and which tools to expose to your agents:

json
{
  "model": "claude-sonnet-4-5",
  "tools": [
    "playwright-planner",
    "playwright-generator",
    "playwright-healer",
    "playwright-cli"
  ],
  "context": {
    "projectType": "playwright-e2e-testing",
    "testFramework": "@playwright/test",
    "language": "typescript"
  }
}

Each tool in this configuration serves a distinct role. The Planner produces structured Markdown test plans from natural language descriptions. The Generator converts those plans into runnable TypeScript test files. The Healer analyzes failing tests and attempts to fix broken selectors or timing issues automatically. The CLI gives the agent direct, interactive control over a browser instance for exploratory sessions.

Defining the QA Engineer Agent

OpenCode agents are defined as Markdown files in .opencode/agent/. This file is more than documentation — it shapes how the agent interprets your instructions and sequences its tool use. Create .opencode/agent/QA_Engineer.md with the following content:

markdown
# QA Engineer Agent

## Role
Senior QA Automation Engineer specializing in Playwright end-to-end testing.

## Goal
Ensure comprehensive test coverage and maintain test stability for web applications using Playwright.

## Responsibilities
1. Analyze user stories and requirements to create structured test plans
2. Explore applications using Playwright CLI to map user flows before writing tests
3. Generate executable Playwright tests using the Planner and Generator agents
4. Execute tests and use the Healer agent to address flaky or broken tests
5. Maintain test documentation and keep coverage reports up to date

## Tools Available
- **Playwright Planner** — Creates structured test plans in Markdown format
- **Playwright Generator** — Converts test plans into TypeScript test code
- **Playwright Healer** — Repairs failing tests by updating selectors and timing
- **Playwright CLI** — Provides interactive browser control for exploration sessions

## Workflow
1. Use Playwright CLI to explore the application and map the key user flows
2. Create detailed test plans with the Planner, grounded in what you observed
3. Generate executable TypeScript tests from those plans using the Generator
4. Run the tests; apply the Healer if failures appear
5. Review generated code and refine assertions for edge cases

The key design principle here is exploration before generation. By having the agent use the CLI to actually navigate the application first, the resulting test plans are grounded in observed reality rather than assumptions — which produces much more stable selectors and realistic assertions.

Example: Creating an Authentication Test Suite

To see the agent in action, let's walk through creating a login test. Start an OpenCode session with your QA Engineer agent:

bash

opencode --agent QA_Engineer

Step 1 — Explore the Application

Give the agent a clear exploration goal:

QA Engineer, please explore our application at http://localhost:3000 using
Playwright CLI. Navigate to the login page and test both a successful and a
failed login attempt. Intercept and record any network requests made during
authentication.

The agent will open a browser, navigate to the login page, attempt login with invalid credentials to capture the error response, then authenticate successfully and verify the resulting state. Crucially, it will also record the network traffic — which gives the Generator enough context to write meaningful request/response assertions later.

Step 2 — Generate the Test Suite

Once exploration is complete, ask the agent to produce the tests:

Based on your exploration, use the Planner and Generator agents to create a
comprehensive authentication test suite. Include tests for:
- Invalid credentials (wrong password)
- Successful login with valid credentials
- Network request and response validation
- UI state assertions (error messages, redirects, session indicators)

Save the output as tests/auth.spec.ts.

The agent first produces a Markdown test plan with the Planner, so you can review the intended coverage before any code is written. It then feeds that plan to the Generator, which outputs tests/auth.spec.ts.

A word of advice: Always review the generated code before committing it. AI-generated tests are a strong starting point, but they may need hand-tuning for application-specific edge cases, dynamic content, or unusual timing behaviors.

Running and Maintaining Tests

With the test file in place, you can run it like any standard Playwright test:

bash
# Run the authentication test suite
npx playwright test tests/auth.spec.ts

# Open UI mode to visually step through and debug failures
npx playwright test tests/auth.spec.ts --ui

# If a test starts failing after a UI change, ask the Healer agent to fix it
opencode --agent QA_Engineer "The authentication tests are failing. Please analyze the failures and apply fixes."

The Healer agent examines the failure output, identifies whether the issue is a changed selector, a timing problem, or a shifted assertion, and patches the test file accordingly. This is particularly useful when the application's UI is being actively developed and minor DOM changes would otherwise break dozens of tests at once.

Conclusion

Creating a dedicated QA Engineer agent in OpenCode gives your team a consistent, version-controlled approach to test automation. Rather than relying on individual engineers to remember Playwright's API or write boilerplate setup code from scratch, the agent encodes your testing standards and workflows directly into a file that lives alongside your codebase.

The most important shift this enables is moving QA effort earlier in the development cycle. Because the agent can explore a feature and generate a test suite in the same session you use to build it, there's less of a gap between writing code and testing it. Over time, the Healer's ability to adapt tests to UI changes also reduces the maintenance burden that causes teams to abandon test suites altogether.

The combination of OpenCode's agent system with Playwright's browser automation creates a foundation that scales naturally with your application — and with Claude Sonnet 4.5 powering the reasoning, the quality of generated plans and tests improves as the model's understanding of your codebase deepens across sessions.