> 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/framework-selection.md).

# Choose a Testing Framework

Choose Playwright, Cypress, Selenium, or native unit and integration tests based on risk, existing code, and ownership; add ContextQA MCP where it fits.

## Quick answer

Choose the test layer and framework from the behavior you need to protect and the stack your team already maintains. Claude Code, Cursor, and Codex can help author tests in multiple frameworks; choosing an assistant does not require replacing your runner. Use native unit tests for isolated logic, integration tests for system boundaries, and browser tests for critical journeys. Add ContextQA MCP when shared test authoring, managed execution, and accessible failure evidence solve a practical ownership problem.

This guide is for engineering managers, QA leads, and developers deciding where a new AI-assisted testing workflow belongs. It is a decision procedure, not a ranking of tools.

## Prerequisites: inventory what already works

Before comparing frameworks, record:

* Application languages, frontend framework, and supported browsers.
* Existing test runners, commands, fixtures, and CI jobs.
* The failures customers experience and the tests that currently detect them.
* Authentication, test-data, network, and deployment constraints.
* Who reviews generated changes and who investigates failed runs.
* Any requirement to run exported tests independently.

Ask the coding agent to inspect package manifests, test directories, build configuration, and two representative tests. Have it report what it actually found, including gaps. A filename containing “test” does not establish useful coverage.

## 1. Select the narrowest useful test boundary

| Risk or question                                        | Usually start with                   | Example outcome                                      |
| ------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------- |
| Does a discount calculation handle the boundary?        | Native unit test                     | Exact amount for minimum, maximum, and invalid input |
| Does persistence enforce ownership?                     | Integration test                     | A user cannot read another tenant's record           |
| Does a component display an error correctly?            | Component or focused UI test         | Accessible error state after a stubbed failure       |
| Does checkout work across the deployed stack?           | Browser end-to-end test              | One confirmed order with the correct amount          |
| Can another team reproduce a reported workflow failure? | Shared functional test with evidence | Reviewed steps and a run tied to the affected build  |

Functional testing describes checking required behavior; it is not restricted to a browser or a particular framework. A permission rule can have unit, integration, and end-to-end checks, each answering a different question. See [functional testing](/testing-with-ai-coding-agents/functional-testing.md) for turning requirements into scenarios.

Avoid reproducing every unit-test combination through the browser. Also avoid calling a mocked service interaction a full end-to-end test. Declare the boundaries and retain the few cross-system checks needed for release confidence.

## 2. Compare the options against your constraints

| Option                         | Evaluate when                                                                        | Questions the pilot must answer                                                                 |
| ------------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| Playwright Test                | You want repository-owned browser tests and a browser project matrix                 | Do fixtures, authentication, assertions, and traces fit your CI workflow?                       |
| Cypress                        | Your team already uses Cypress or values its end-to-end and component workflows      | Does the application's behavior fit the execution model and supported integrations?             |
| Selenium WebDriver             | Existing language bindings, browser automation, or Grid infrastructure are important | Who owns the runner, synchronization, reporting, and environment lifecycle?                     |
| Native unit/integration runner | The behavior can be checked close to application code                                | Are real boundaries, isolation, and deterministic data represented?                             |
| ContextQA through MCP          | A team wants an assistant to author, execute, and investigate shared managed tests   | Do the actual steps, evidence, access controls, and export boundaries meet acceptance criteria? |

Playwright supports configuration through projects and reusable fixtures. Cypress documents end-to-end and component testing as distinct workflows. Selenium WebDriver is a browser automation API whose surrounding test organization depends on the selected language and tooling. Review the official [Playwright configuration](https://playwright.dev/docs/test-configuration), [Cypress testing types](https://docs.cypress.io/app/core-concepts/testing-types), and [Selenium WebDriver overview](https://www.selenium.dev/documentation/webdriver/) against your application.

For unit and integration coverage, keep the established runner when it meets the need. Examples include Vitest or Jest for JavaScript/TypeScript, pytest for Python, and JUnit for Java. The official [Vitest](https://vitest.dev/guide/), [pytest](https://docs.pytest.org/en/stable/getting-started.html), and [JUnit](https://docs.junit.org/current/overview.html) guides describe their own setup. These examples are not ContextQA execution or export commitments.

## 3. Adapt the agent's instructions to the framework

A useful prompt names the existing runtime, desired layer, and acceptance evidence:

```
Inspect this repository's test configuration and existing conventions.
We need coverage for <behavior> because <customer or release risk>.
Propose the lowest test layer that verifies it without hiding the relevant
dependency. Reuse our installed framework and fixtures. Explain any additional
browser test needed. Do not add a competing runner without a concrete reason.
For each proposed test, give the setup, assertion, cleanup, and failure signal.
```

Then apply framework-specific review:

* **Playwright:** await browser actions and retrying assertions; use observed locators and explicit test-data lifecycles.
* **Cypress:** preserve its command-chain and retry model; do not mechanically rewrite commands into a Playwright-style async pattern.
* **Selenium:** wait for meaningful conditions using the framework's supported synchronization rather than fixed sleeps.
* **Native runners:** distinguish mocks from real integrations; exercise meaningful error paths and verify state as well as return values.

The official [Cypress retry model](https://docs.cypress.io/app/core-concepts/retry-ability) and [Selenium waiting strategies](https://www.selenium.dev/documentation/webdriver/waits/) matter more than generated code merely looking familiar. A competent agent should inspect your installed version and the relevant API before editing.

## 4. Run a small comparison with the same behavior

Select a representative slice: one happy path, one denied operation, one data-dependent workflow, and one deliberately seeded defect in a disposable build. Use identical requirements, application revision, and seed data.

Capture a baseline before changing frameworks. Record the time needed to author and review a test, investigate a failure, restore data, and repair a legitimate selector change. These are observations from your pilot, not promised savings.

| Criterion     | Evidence to collect                             | Acceptance question                                      |
| ------------- | ----------------------------------------------- | -------------------------------------------------------- |
| Detection     | Baseline and seeded-failure runs                | Does the same important defect fail reliably?            |
| Reviewability | Spec or managed step review                     | Can the owner explain every assertion?                   |
| Diagnosis     | Logs, screenshots, traces, or equivalent output | Can someone other than the author locate the failure?    |
| Repeatability | Clean data and another approved run             | Does success depend on leftover state?                   |
| Maintenance   | One controlled application change               | Was intent preserved during repair?                      |
| Portability   | Representative exported or repository-owned run | What still requires a service, secret, or manual action? |

Set your own thresholds before evaluating results. A faster generated test that never checks the critical amount is not an improvement. A failed test can still be valuable if it correctly reveals a product defect.

## 5. Add ContextQA without discarding useful coverage

Keep fast code-level checks in the application's existing unit and integration jobs. After [MCP setup](/mcp-server/installation-and-setup.md), ask the assistant to create a managed test for the cross-team behavior:

```
Confirm the active ContextQA workspace and available tools. Create a test for
<approved staging URL> covering <business workflow>, with <seeded data> and
these exact expected outcomes: <assertions>. Return the case ID and steps.
Do not execute until I review the data and assertions. Identify any behavior
that must remain in our native unit or integration suite.
```

Review, run in the authorized environment, then request the terminal result and relevant step evidence. Compare detection against the same seeded defect. This produces a concrete basis for adopting managed tests alongside repository tests.

If you already have a substantial suite, use the [migration planning checklist](/migrate-to-contextqa/planning-checklist.md) before conversion. For buyer or engineering exit requirements, use the [export acceptance procedure](/testing-with-ai-coding-agents/export-and-portability.md). A marketing description of a framework export is not evidence that your fixtures and assertions survive conversion.

## Troubleshooting and FAQ

**Should we rewrite Selenium because we use Codex or Claude Code?** No automatic rewrite follows from changing assistants. Start by improving a representative existing test and measuring its review and maintenance burden.

**Can one framework cover everything?** A tool can span multiple activities, but its presence does not remove the need for separate boundaries. Browser success does not establish every calculation or permission rule.

**Can ContextQA run our unit-test suite through MCP?** Do not assume this. Run repository unit tests through the coding agent's authorized terminal or CI. Use verified MCP tools for the supported managed test workflow.

**Should we choose by generated test count?** Count protected behaviors and observed failures instead. Duplicate tests and weak assertions can increase volume without reducing risk.

*Sources and implementation reviewed September 25, 2026. Verify the tool schema in your connected client before using version-dependent capabilities.*

## Next step

Choose one behavior and follow the [unit](/testing-with-ai-coding-agents/unit-testing.md), [integration](/testing-with-ai-coding-agents/integration-testing.md), or [Playwright](/testing-with-ai-coding-agents/playwright-testing.md) guide. For managed execution, [create your first ContextQA MCP test](/mcp-server/first-test-tutorial.md). [Book a framework evaluation demo](https://contextqa.com/book-a-demo/?utm_source=learning.contextqa.com\&utm_medium=referral\&utm_campaign=docs_demand_gen\&utm_content=framework-selection) with a representative spec and your acceptance criteria to compare authoring, failure investigation, and portability on the same workflow.


---

# 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/framework-selection.md?ask=<question>&goal=<user_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.