> ## Documentation Index
> Fetch the complete documentation index at: https://onetest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Running Tests

> Execute test runs using the OneTest Skill in Claude Code

## Overview

OneTest uses an AI-powered test execution engine through the [OneTest QA Agent](https://github.com/onetest-ai/qa-agent). Tests stored in OneTest are executed via the `/qa-onetest` skill in Claude Code, which drives a real browser, records results per step, and reports everything back to OneTest automatically.

## Prerequisites

<Steps>
  <Step title="Install Claude Code">
    Install [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — the CLI tool that runs the QA agent.
  </Step>

  <Step title="Install the QA Agent">
    Clone the QA agent skills into your project:

    ```bash theme={null}
    git clone https://github.com/onetest-ai/qa-agent.git
    ```
  </Step>

  <Step title="Configure the OneTest MCP Server">
    <Tip>
      **Tip:** Run `npx github:onetest-ai/qa-agent init` and choose "Connect via browser" for one-click setup — it configures the MCP connection automatically.
    </Tip>

    Or add the `test-management` MCP server manually to your `.mcp.json` (project root):

    ```json theme={null}
    {
      "mcpServers": {
        "test-management": {
          "type": "http",
          "url": "https://tms.onetest.ai/mcp/test-management",
          "headers": {
            "Authorization": "Bearer <YOUR_API_KEY>"
          }
        }
      }
    }
    ```

    Get your API key from **[tms.onetest.ai](https://tms.onetest.ai) -> Settings -> API Keys**.
  </Step>

  <Step title="Restart Claude Code">
    Restart Claude Code so it picks up the new MCP server configuration.
  </Step>
</Steps>

## Running a Test Run

Use the `/qa-onetest run` command in Claude Code to create, execute, and complete a full test run.

```
/qa-onetest run
```

The agent will prompt you for which tests to include, then automatically:

<Steps>
  <Step title="Create Run">
    Creates a test run in OneTest with the selected test cases.
  </Step>

  <Step title="Start Run">
    Transitions the run from `planned` to `in_progress` and freezes the scope.
  </Step>

  <Step title="Execute Tests">
    For each test case in the run:

    * Navigates to the target URL in a real browser
    * Executes each test step via Chrome DevTools Protocol (CDP)
    * Captures screenshots before and after each step
    * Checks the browser console for errors after each step
    * Validates actual results against expected outcomes
  </Step>

  <Step title="Record Results">
    Records the result for each test execution:

    * **Pass** / **Fail** / **Blocked** / **Skipped** status
    * Step-level results with screenshots
    * Failure reasons and classification
    * Links to defects if applicable
  </Step>

  <Step title="Complete Run">
    Marks the run as complete and generates analytics — pass/fail rates, completion percentage, duration, and failure breakdown.
  </Step>
</Steps>

## All Commands

The `/qa-onetest` skill supports four commands:

<CardGroup cols={2}>
  <Card title="run" icon="play">
    Create, execute, and complete a full test run. The agent drives a real browser and records all results back to OneTest.

    ```
    /qa-onetest run
    ```
  </Card>

  <Card title="push findings" icon="upload">
    Convert QA audit findings into OneTest test cases. Maps priorities (p0-p3) and categories (accessibility, security, performance, etc.) automatically.

    ```
    /qa-onetest push findings
    ```
  </Card>

  <Card title="pull tests" icon="download">
    Fetch test cases from OneTest for local browser execution.

    ```
    /qa-onetest pull tests
    ```
  </Card>

  <Card title="status" icon="signal">
    Show the execution queue and any active runs.

    ```
    /qa-onetest status
    ```
  </Card>
</CardGroup>

## How Execution Works

### Browser-Based Testing

The agent executes tests in a real Chrome browser using the Chrome DevTools Protocol (CDP). This means tests interact with your application exactly as a user would — clicking buttons, filling forms, navigating pages, and verifying visual output.

### Exploratory Findings

If the agent discovers issues during test execution that aren't covered by existing test cases, it can record them as exploratory findings using `record_exploratory_result`. These appear in your test run alongside the planned test results.

### Parallel Execution

Non-conflicting tests can run simultaneously using separate Chrome instances on different CDP ports. This speeds up execution when tests target different URLs or isolated user sessions.

## Recording Results

Every test execution records detailed results back to OneTest:

<AccordionGroup>
  <Accordion title="Step-Level Results" icon="list-check">
    Each step in a test case gets its own pass/fail status, along with:

    * Screenshots captured before and after the step
    * Console output from the browser
    * Actual vs. expected result comparison
  </Accordion>

  <Accordion title="Failure Classification" icon="triangle-exclamation">
    When a test fails, the agent records:

    * **Failure reason**: What went wrong
    * **Failure classification**: Environment issue, product defect, test data issue, etc.
    * **Defect links**: Links to related bug tracker issues
  </Accordion>

  <Accordion title="Run Analytics" icon="chart-bar">
    After the run completes, OneTest provides analytics:

    * Pass/fail/skip/blocked rates
    * Completion percentage
    * Total execution duration
    * Failure breakdown by category
  </Accordion>
</AccordionGroup>

## Typical Workflow

A common end-to-end workflow looks like this:

1. **Audit your site** with QA specialist skills (`/qa-accessibility`, `/qa-security`, etc.)
2. **Push findings** to OneTest as test cases with `/qa-onetest push findings`
3. **Run tests** with `/qa-onetest run` to execute them in a real browser
4. **View results** in the [OneTest dashboard](https://tms.onetest.ai) to analyze trends and track regressions

## What's Next?

<CardGroup cols={2}>
  <Card title="Viewing Results" icon="chart-line" href="/ui/viewing-results">
    Analyze test results and trends in the dashboard
  </Card>

  <Card title="QA Agent on GitHub" icon="github" href="https://github.com/onetest-ai/qa-agent">
    Full documentation for the QA agent and all skills
  </Card>
</CardGroup>