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

# Run Tests (stably run)

> Run Stably-powered Playwright tests locally or in CI with full Playwright compatibility.

There are two ways to run your Stably-powered Playwright tests:

<Tabs>
  <Tab title="Method 1: stably test (Recommended)">
    The simplest approach — the Stably reporter is **automatically configured**.

    ### Setup Requirements

    <Steps>
      <Step title="Set environment variables">
        ```bash theme={null}
        export STABLY_API_KEY=your_api_key_here
        export STABLY_PROJECT_ID=your_project_id_here
        ```
      </Step>

      <Step title="Run tests">
        ```bash theme={null}
        stably test
        ```
      </Step>
    </Steps>

    ### Options

    Stably is fully Playwright compatible. All [Playwright CLI options](https://playwright.dev/docs/test-cli) are supported:

    ```bash theme={null}
    # Run all tests
    stably test

    # Run with Playwright options
    stably test --headed --project=chromium

    # Run specific test file
    stably test tests/login.spec.ts

    # More Playwright options
    stably test --workers=4 --retries=2 --grep="login"

    # Override the reported suite name
    stably test --suiteName="nightly smoke tests"
    ```

    #### `--suiteName`

    Sets the suite name reported to the Stably dashboard and Slack notifications.

    ```bash theme={null}
    stably test --suiteName="daily staging run"
    stably test --suiteName="nightly smoke tests" --project=chromium
    ```

    When `--suiteName` is not provided, the default name is automatically derived from the Playwright project names that are running (sorted alphabetically, joined with `, `). For example, running `--project=chromium --project=firefox` produces a default suite name of `chromium, firefox`.

    You can also set the suite name via the `STABLY_SUITE_NAME` environment variable, or directly in your Playwright config with `stablyReporter({ suiteName: "..." })`.

    <Accordion title="GitHub Actions Workflow">
      ```yaml theme={null}
      # .github/workflows/stably.yml
      name: Stably Tests

      on:
        push:
          branches: [main]
        pull_request:

      jobs:
        test:
          runs-on: ubuntu-latest
          steps:
            - uses: actions/checkout@v4

            - name: Setup Node
              uses: actions/setup-node@v4
              with:
                node-version: '20'

            - name: Install dependencies
              run: npm ci

            - name: Install browsers
              run: npx stably install

            - name: Run Stably tests
              env:
                STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
                STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
              run: npx stably test
      ```
    </Accordion>
  </Tab>

  <Tab title="Method 2: npx playwright test">
    Use this if you need more control over your Playwright configuration.

    ### Setup Requirements

    <Steps>
      <Step title="Set environment variables">
        ```bash theme={null}
        export STABLY_API_KEY=your_api_key_here
        export STABLY_PROJECT_ID=your_project_id_here
        ```
      </Step>

      <Step title="Configure the reporter">
        Add the Stably reporter to your `playwright.config.ts`:

        ```typescript theme={null}
        import { stablyReporter } from "@stablyai/playwright-test";

        export default defineConfig({
          reporter: [
            ["list"],
            stablyReporter({
              apiKey: process.env.STABLY_API_KEY,
              projectId: process.env.STABLY_PROJECT_ID,
            }),
          ],
          use: {
            trace: "on", // Required for full context
          },
        });
        ```
      </Step>

      <Step title="Run tests">
        ```bash theme={null}
        npx playwright test
        ```
      </Step>
    </Steps>

    See the [Stably Test Reporter documentation](/stably/stably-test-reporter) for complete setup instructions.

    <Accordion title="GitHub Actions Workflow">
      ```yaml theme={null}
      # .github/workflows/playwright.yml
      name: Playwright Tests

      on:
        push:
          branches: [main]
        pull_request:

      jobs:
        test:
          runs-on: ubuntu-latest
          steps:
            - uses: actions/checkout@v4

            - name: Setup Node
              uses: actions/setup-node@v4
              with:
                node-version: '20'

            - name: Install dependencies
              run: npm ci

            - name: Install browsers
              run: npx stably install

            - name: Run Playwright tests
              env:
                STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
                STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
              run: npx playwright test
      ```
    </Accordion>
  </Tab>
</Tabs>

## Running Specific Test Groups

If you've organized your tests using [Playwright projects](/use-cases/defining-test-groups), you can run specific groups:

```bash theme={null}
# Run smoke tests only
npx stably test --project=smoke

# Run multiple test groups
npx stably test --project=smoke --project=release

# Combine with grep for fine-grained control
npx stably test --project=critical --grep @p0
```

## Environment Variables

There are several ways to pass environment variables to your tests:

```bash theme={null}
# Inline variables
BASE_URL=http://localhost:3000 npx stably test

# Load from a named environment on Stably
npx stably --env Staging test

# Load from a local .env file
npx stably test --env-file .env.staging

# Combine sources
npx stably --env Production test --env-file .env
```

When using multiple sources, variables are resolved in this order (highest priority wins):

1. Stably internals (`STABLY_API_KEY`, `STABLY_PROJECT_ID`)
2. `process.env` (system/shell environment)
3. `--env-file` (local `.env` files)
4. `--env` (remote environment from Stably)

See [Environments](/stably2/environments) for managing named environments on the dashboard — you can get started quickly by [uploading a `.env` file](https://app.stably.ai/environments) via **Bulk Import**.

## Advanced Options

<AccordionGroup>
  <Accordion title="Debug Mode">
    Run tests in debug mode with Playwright Inspector:

    ```bash theme={null}
    npx stably test --debug
    ```
  </Accordion>

  <Accordion title="Parallel Execution">
    Control the number of parallel tests:

    ```bash theme={null}
    # Run with 4 parallel tests
    npx stably test --workers=4

    # Run serially (one test at a time)
    npx stably test --workers=1
    ```
  </Accordion>

  <Accordion title="Retries">
    Configure test retries:

    ```bash theme={null}
    # Retry failed tests twice
    npx stably test --retries=2
    ```
  </Accordion>

  <Accordion title="Headed Mode & UI Mode">
    Run with a visible browser or Playwright's interactive UI:

    ```bash theme={null}
    # See the browser as tests run
    npx stably test --headed

    # Open Playwright's interactive UI
    npx stably test --ui
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Auto-fix Failures" icon="wand-magic-sparkles" href="/stably-cli/fix">
    Automatically diagnose and repair failing tests
  </Card>

  <Card title="Defining Test Groups" icon="layer-group" href="/use-cases/defining-test-groups">
    Organize tests using Playwright projects
  </Card>

  <Card title="Test Reporter" icon="chart-line" href="/stably/stably-test-reporter">
    Stream results and traces to the Stably dashboard
  </Card>

  <Card title="CI/CD Integration" icon="code-branch" href="/getting-started/ci-integration">
    Integrate tests into your deployment pipeline
  </Card>
</CardGroup>