> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/testing-with-ai-coding-agents/playwright-mcp-cli-test-agents.md). # Playwright MCP, CLI, and Test Agents Choose Playwright MCP, CLI skills, Test Agents, or ContextQA MCP for browser exploration, test generation, repeatable execution, and reviewed evidence. ## Quick answer Use Playwright MCP or the Playwright CLI when an agent needs to interact with a browser. Use Playwright Test Agents to organize planning, test generation, and repair. Use Playwright Test to run saved specs with assertions and fixtures. Add ContextQA MCP when you want a compatible agent to work with managed application tests and their execution results. Choose by the artifact and ownership you need: exploring a page, generating a test, and proving a release requirement are different outcomes. ## Why these names are easy to confuse An agent can click through a checkout successfully without creating a repeatable test. A generated spec can look convincing without having run. A completed execution can include a failed or skipped assertion. Decide what you need before choosing the integration. For example, suppose a report-export change should allow an editor to download a CSV while denying a viewer. Your goal is to verify both permissions, the resulting file, and the application's behavior. The goal is not satisfied by navigating to the Reports page or finding an Export button. For your first spec, start with [testing with Playwright](/testing-with-ai-coding-agents/playwright-testing.md). ## Compare the workflows | Option | Main job | Useful output | You still need to decide | | -------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------- | --------------------------------------------------------------------------- | | Playwright Test | Execute repository-owned browser tests | Specs, assertions, runner results and configured artifacts | Fixtures, required coverage, CI policy and maintenance | | Playwright MCP | Let a compatible agent control and inspect a browser through tools | Observations and actions; test code if the agent is asked to create it | What becomes an assertion and what is retained for reruns | | Playwright CLI with skills | Give a terminal-capable agent browser commands and workflow instructions | Browser observations and files the agent creates | How those observations become reviewed tests | | Playwright Test Agents | Structure exploration, generation and failure repair | A plan, generated specs and proposed repairs | Whether coverage is sufficient and repairs preserve requirements | | ContextQA MCP | Let an authenticated agent use available ContextQA testing tools | Managed test cases, execution identifiers and retrieved results | Workspace access, reachable environment, assertions and evidence acceptance | These options can coexist. Keep an established Playwright suite while an agent investigates a new flow, or add a managed application check alongside repository unit tests. ### Browser control: MCP or CLI? Playwright's [coding-agent documentation](https://playwright.dev/docs/getting-started-cli) distinguishes a command-based workflow with installable skills from MCP's tool-based browser interaction. A terminal-capable coding agent may fit the CLI workflow naturally; an MCP-compatible client may fit the server workflow better. Compare them on the same bounded task rather than assuming one is universally faster or cheaper. Use the official [CLI setup](https://playwright.dev/docs/getting-started-cli) or [MCP setup](https://playwright.dev/docs/getting-started-mcp) for your installed client. Confirm its browser, profile and environment before exploring. A developer's existing signed-in profile and an isolated test profile are different fixtures. Neither interface defines your acceptance criteria. Ask the agent to capture observations and propose assertions; then save reviewed tests if you need a repeatable regression check. ### Planning and generation: Test Agents Playwright's [Test Agents documentation](https://playwright.dev/docs/test-agents) describes planner, generator and healer roles. A seed test provides the starting environment and fixture conventions. A reviewed plan can then become Playwright specs. In a repository with a compatible Playwright dependency already installed, check the version and use the definition generator for your client. For example: ```bash npx playwright --version npx playwright init-agents --loop=claude ``` The current documentation also lists `vscode`, `codex` and `opencode` loops. Availability depends on your installed version; inspect its help and the official guide before use. Review generated configuration as a repository change. Regenerate definitions when upgrading, as the vendor recommends. A healer's proposed repair still needs review. Its documented outcome can include a skipped test when it considers the functionality broken. A skipped requirement remains unresolved. Updating a locator is different from deleting a denial assertion or silently changing the expected result. ## A practical workflow from exploration to regression coverage ### 1. Write the behavior contract Use synthetic records and approved test identities. Define the editor's permitted export, the viewer's denial, the expected CSV fields and the cleanup procedure. Record which application build is deployed and how you will observe server-side effects. ``` Plan tests for report export. Editors may export their team's report; viewers must be denied. Use the approved staging build and synthetic data. Read existing fixtures and tests first. Identify missing requirements. Return a matrix of role, action, expected response, persisted effect, test layer and evidence. Do not create tests or change the application yet. ``` ### 2. Explore only what is uncertain Use MCP or CLI browser control to identify the actual flow, accessible controls and download behavior. Use repository inspection for authorization code and existing fixtures. Keep observations separate from requirements: a currently visible button does not establish who should be allowed to use it. Resolve incorrect environment or account access before generating tests. ### 3. Produce the right tests Use the ordinary coding agent or Test Agents to implement the reviewed plan. Check authorization rules at the narrowest useful layer; test the real API boundary for denied requests; reserve browser coverage for the complete permitted journey and relevant UI behavior. See [functional testing](/testing-with-ai-coding-agents/functional-testing.md) for a decision-table approach. For the CSV journey, assert the download and its meaningful contents. For the viewer, verify the denied server operation and absence of an export. Hiding a button alone does not prove authorization. ### 4. Execute and inspect the result Run the saved specs through the repository's normal runner. In a standard Playwright project, a focused command could be: ```bash npx playwright test tests/report-export.spec.ts --retries=0 ``` Use your real spec path. Preserve the first result, build identifier and available artifacts. Validate an assertion against a deliberately broken disposable fixture, then restore and rerun. Keep defects out of shared deployments. For CI, retain the broader required suite. Playwright describes changed-test selection as a heuristic that can miss coverage; it is an early feedback step, not a guarantee of complete impact analysis. [Playwright CI guidance](https://playwright.dev/docs/ci#fail-fast). ## Add ContextQA MCP where managed execution helps Follow [ContextQA MCP installation](/mcp-server/installation-and-setup.md), then discover your account's current tools and schemas. A read-only workspace/test listing establishes which account you are using. The hosted server does not automatically see your checkout, local files or `localhost` application. Reuse the same report-export contract. Search for an existing managed case before creating another. Ask the agent to inspect the available creation tool's side effects, since some workflows can also execute tests. Review the proposed verification steps and then run against the approved reachable environment. Retrieve the result and step evidence using returned identifiers. Record missing artifacts, skipped steps and unresolved outcomes. Keep this execution separate from the repository's Playwright run; neither result automatically proves the other passed. The [first MCP test walkthrough](/mcp-server/first-test-tutorial.md) explains the lifecycle. If you need repository ownership, follow [export and portability](/testing-with-ai-coding-agents/export-and-portability.md). Inspect the actual export, replace manual checkpoints or missing assertions, handle credentials appropriately, and validate standalone execution. Export availability is not proof of equivalent coverage. ## Questions developers ask ### Does Playwright MCP replace Playwright Test? No. MCP provides browser tools to an agent; Playwright Test provides a runner, fixtures and assertion-based specs. You can use MCP during exploration and keep the resulting reviewed specs in the runner. ### Do I need Test Agents to generate tests? No. A coding agent can write specs directly. Test Agents provide a structured planning/generation/repair workflow; choose them if those handoffs help your team review the work. ### Is ContextQA MCP a replacement for repository tests? It need not be. Keep unit, integration and existing browser tests where they are maintained. Evaluate managed cases when shared application testing and result retrieval address a concrete need. ## Try one workflow [Connect ContextQA MCP](/mcp-server/installation-and-setup.md) and evaluate one permitted and one denied case. For team execution or portability requirements, [book a workflow evaluation](https://contextqa.com/book-a-demo/?utm_source=learning.contextqa.com\&utm_medium=referral\&utm_campaign=docs_demand_gen\&utm_content=playwright-mcp-cli-test-agents) with the same acceptance criteria and a representative spec. Reviewed September 25, 2026 against the official sources linked above and the [ContextQA MCP documentation](https://mcp.contextqa.com/docs). This guide is a workflow comparison, not a published performance benchmark or evidence that the example was run against your application. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://learning.contextqa.com/testing-with-ai-coding-agents/playwright-mcp-cli-test-agents.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.