> For the complete documentation index, see [llms.txt](https://docs.testery.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.testery.io/integrations/testery-claude-plugin.md).

# Claude Plugin

The Testery Claude Plugin turns [Claude Code](https://docs.anthropic.com/en/docs/claude-code) into a hands-on Testery teammate. It adds a full set of slash commands and skills that let Claude drive the Testery platform — create test runs, monitor them, manage environments and schedules, upload artifacts — and scaffold or author [playwright-bdd](https://github.com/vitalets/playwright-bdd) tests, all from natural-language conversation.

{% hint style="info" %}
Looking for read-only, conversational access to your Testery data instead? See the [Testery MCP Server](/integrations/testery-mcp-server.md). The plugin and the MCP server complement each other — the plugin runs the Testery CLI for write operations, and the MCP server is great for inspection.
{% endhint %}

## Prerequisites

* [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with plugin support installed
* A [Testery account](https://testery.com/signup?plan=2)
* The [Testery CLI](/integrations/testery-cli-docs.md) on your `PATH` (the `/testery-onboard` command will install it for you if it is missing):

  ```bash
  pip install testery
  ```

## Install

From inside a Claude Code session, add the Testery marketplace and install the plugin:

```
/plugin marketplace add testery/testery-skills
/plugin install testery@testery
```

Claude Code clones the repo, registers the marketplace, and installs the plugin. Every `/testery-*` and `/bdd-*` command and skill becomes available immediately.

### Install from a local clone

If you have already cloned the [plugin repository](https://github.com/testery/testery-skills):

```
/plugin marketplace add /absolute/path/to/testery-claude-plugin
/plugin install testery@testery
```

### Update or uninstall

```
/plugin update testery@testery
/plugin uninstall testery@testery
/plugin marketplace remove testery
```

## Quickstart

After installing the plugin, run these two commands to authenticate and wire up a project:

```
/testery-onboard      # sign up or log in on testery.io, persist your API key
/testery-init         # scaffold playwright-bdd + register the project on Testery
```

`/testery-onboard` opens the Testery signup/login page, walks you through generating an API key, then saves it to `~/.testery/credentials` and your shell profile so it persists across sessions. `/testery-init` scaffolds a playwright-bdd project, runs a local smoke test, registers the project on Testery, and optionally fires your first cloud run.

Prefer to set the token yourself? Export it before starting Claude Code:

```bash
export TESTERY_TOKEN=<your-token>        # bash / zsh
```

```powershell
$env:TESTERY_TOKEN = '<your-token>'      # PowerShell
```

## What you can do

Once installed, just talk to Claude in natural language — it picks the right skill automatically. For example:

* "Run my tests on Testery against the staging environment and watch them"
* "What test runs are currently active?"
* "Show me the results of the last run"
* "Register a new `qa` environment"
* "Schedule the smoke suite to run nightly at 2am"
* "Add a scenario that checks the login page rejects a bad password"

### Slash commands

You can also invoke any capability explicitly with a slash command.

#### Testery platform

| Command                                  | What it does                                                       |
| ---------------------------------------- | ------------------------------------------------------------------ |
| `/testery-onboard`                       | **Start here.** Sign up / log in, capture your API key, persist it |
| `/testery-init`                          | Scaffold playwright-bdd in this project and wire it to Testery     |
| `/testery-create-test-run`               | Submit a Git-based test run                                        |
| `/testery-monitor-test-run`              | Follow a run to completion                                         |
| `/testery-cancel-test-run`               | Cancel a running test run                                          |
| `/testery-list-active-test-runs`         | Show in-flight runs                                                |
| `/testery-report-test-run`               | Output per-test results                                            |
| `/testery-upload-artifacts`              | Upload a local file/dir as a build                                 |
| `/testery-add-file`                      | Attach a file to a test run                                        |
| `/testery-register-environment`          | Create a new environment                                           |
| `/testery-update-environment`            | Update an existing environment                                     |
| `/testery-deregister-environment`        | Delete an environment                                              |
| `/testery-list-environments`             | List environments                                                  |
| `/testery-upload-environment-file`       | Upload a file to an environment                                    |
| `/testery-create-schedule`               | Create cron / on-deploy / follow schedules                         |
| `/testery-delete-schedule`               | Remove a schedule                                                  |
| `/testery-create-deploy`                 | Notify Testery of a deploy                                         |
| `/testery-create-alert`                  | Set up an alert                                                    |
| `/testery-run-test-plan`                 | Execute a saved test plan                                          |
| `/testery-load-users`                    | Bulk-load users                                                    |
| `/testery-verify-token`                  | Auth health check                                                  |
| `/testery-run-playwright-bdd-local`      | Run playwright-bdd tests on this machine                           |
| `/testery-run-playwright-bdd-on-testery` | Run playwright-bdd tests on Testery (local build or remote Git)    |

#### Playwright-BDD authoring

| Command               | What it does                                                         |
| --------------------- | -------------------------------------------------------------------- |
| `/bdd-add-scenario`   | Add a scenario, implement step definitions, drive the red→green loop |
| `/bdd-test`           | Run the playwright-bdd suite (or a single scenario by name)          |
| `/bdd-implement-code` | Implement app code to make a failing scenario pass                   |
| `/bdd-view-report`    | Open the Playwright HTML report in a browser                         |

## How it works

Each slash command delegates to a matching skill, so the documented behavior lives in one place. The `testery-*` skills wrap the [Testery CLI](/integrations/testery-cli-docs.md) for write operations — creating runs, uploading artifacts, managing schedules, environments, and deploys. The `testery-playwright-bdd-*` skills help you author and run [playwright-bdd](https://github.com/vitalets/playwright-bdd) tests and are modeled on a project shaped like the Testery example web app: `tests/features/`, `tests/steps/`, a `playwright.config.ts` that calls `defineBddConfig`, and a `test:e2e` script that runs `bddgen && playwright test`.

## Troubleshooting

**`testery` command not found**

* Install the CLI with `pip install testery`, or re-run `/testery-onboard`.

**Authentication failures**

* Run `/testery-verify-token` to confirm your token is valid.
* Re-run `/testery-onboard` to regenerate and persist a new API key.

**Commands not appearing**

* Confirm the plugin is installed with `/plugin`, then reinstall with `/plugin install testery@testery`.

## Learn more

* Plugin source: [github.com/testery/testery-skills](https://github.com/testery/testery-skills)
* [Testery CLI documentation](/integrations/testery-cli-docs.md)
* [Testery MCP Server](/integrations/testery-mcp-server.md)