> ## 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

> Execute your Playwright tests on Stably's cloud infrastructure for scalable, distributed test execution

## Overview

Stably Cloud provides scalable infrastructure for running your Playwright tests with high parallelism, AI-powered features, and comprehensive reporting. Your tests run in the cloud while using your existing `playwright.config.ts` configuration.

## Prerequisites

<Steps>
  <Step title="Publish Your Tests">
    Before running tests in the cloud, ensure your latest tests are published from the UI.
  </Step>

  <Step title="Get API Key">
    Obtain your API key from the [settings page](https://app.stably.ai/settings?tab=api-key) for API and CI integrations.
  </Step>
</Steps>

## Running Tests in the Cloud

You can trigger cloud execution using several methods:

<Tabs>
  <Tab title="Web Editor">
    ### Using the Stably Web Editor

    The easiest way to run tests in the cloud is directly from the Stably dashboard:

    1. Navigate to your project in the [Stably dashboard](https://app.stably.ai)
    2. Select the tests you want to run
    3. Click the **Run** button
    4. Choose your run configuration (projects, grep patterns, environment)
    5. Monitor results in real-time from the dashboard

    <Card title="Web Editor Guide" icon="browser" href="/stably/stably-web-editor">
      Learn more about the Stably Web Editor
    </Card>
  </Tab>

  <Tab title="Stably CLI">
    ### Using the Command Line

    Run tests from your terminal:

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

    # Run specific projects
    npx stably cloud test --project=smoke --project=critical

    # Combine with grep patterns
    npx stably cloud test --project=release --grep @p0

    # Run with environment variables
    npx stably cloud test --env=STAGING
    ```

    <AccordionGroup>
      <Accordion title="CLI Options">
        * `--project`: Specify which Playwright projects to run (can be used multiple times)
        * `--grep`: Filter tests by pattern
        * `--env`: Set environment for variable overrides
        * `--workers`: Control parallelism (cloud supports hundreds and thousands of parallel tests)
        * `--retries`: Set retry attempts for failed tests
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="REST API">
    ### Using the API

    Trigger test runs programmatically:

    ```bash theme={null}
    curl -X 'POST' \
      'https://api.stably.ai/v1/projects/{projectId}/runs' \
      -H 'accept: application/json' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "projects": ["smoke", "critical"],
        "grep": "@p0"
      }'
    ```

    <Card title="API Reference" icon="book" href="/api-reference/introduction">
      View complete API documentation with all available endpoints and parameters
    </Card>
  </Tab>

  <Tab title="GitHub Action">
    ### Using GitHub Actions

    Integrate cloud testing into your GitHub workflows:

    ```yaml .github/workflows/stably.yaml theme={null}
    name: Run Stably Tests

    on:
      pull_request:
      push:
        branches:
          - main

    jobs:
      test:
        runs-on: ubuntu-latest
        steps:
          - name: Run Cloud Tests
            uses: stablyai/stably-runner-action@v4
            with:
              api-key: ${{ secrets.STABLY_API_KEY }}
              project-id: your-project-id
              projects: "smoke,critical"
    ```

    <Card title="GitHub Integration Guide" icon="github" href="/run-tests/run-tests-on-github">
      Learn more about GitHub Actions integration
    </Card>
  </Tab>

  <Tab title="Scheduled Runs">
    ### Using Schedules

    Configure automatic test runs using `stably.yaml`:

    ```yaml stably.yaml theme={null}
    schedules:
      nightly-smoke:
        cron: "0 2 * * *"
        stablyTestArgs: "--project smoke --project mobile-smoke"
      
      hourly-critical:
        cron: "0 * * * *"
        stablyTestArgs: "--project critical --grep @p0"
    ```

    <Card title="Scheduling Guide" icon="clock" href="/run-tests/scheduled-runs">
      Learn how to configure scheduled test runs
    </Card>
  </Tab>
</Tabs>

## Cloud Execution Features

<CardGroup cols={2}>
  <Card title="High Parallelism" icon="layer-group">
    Run up to 100 tests in parallel for faster test execution. Contact us if you need more.
  </Card>

  <Card title="AI Auto-Heal" icon="wand-magic-sparkles">
    Tests automatically adapt to minor UI changes, reducing maintenance burden.
  </Card>

  <Card title="Smart Reporting" icon="chart-line">
    Get detailed insights with screenshots, traces, and AI-powered failure analysis.
  </Card>

  <Card title="Environment Management" icon="gear">
    Easily switch between environments and manage test data variables.
  </Card>
</CardGroup>

## Monitoring Test Runs

After triggering a test run, you can monitor progress:

<Steps>
  <Step title="View Real-Time Progress">
    Navigate to your Stably dashboard to see:

    * Real-time test execution status
    * Pass/fail rates
    * Test duration and performance metrics
  </Step>

  <Step title="Review Results">
    Once tests complete, access:

    * Detailed test reports with screenshots
    * Trace files for debugging failures
    * AI-generated failure analysis
    * Historical trends and analytics
  </Step>

  <Step title="Receive Notifications">
    Get alerts via:

    * Email notifications
    * Slack messages
    * GitHub PR comments

    Configure notifications in your [project settings](/run-tests/alerting).
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Use Project Organization">
    Organize tests into logical projects (smoke, regression, critical) for flexible execution strategies.
  </Accordion>

  <Accordion title="Leverage High Parallelism">
    Take advantage of parallel cloud tests by ensuring your tests are independent and can run in parallel.
  </Accordion>

  <Accordion title="Configure Retries">
    Set appropriate retry counts for different test types. Critical tests might need fewer retries, while flaky tests might need more.
  </Accordion>

  <Accordion title="Monitor Resource Usage">
    Track your test execution time and optimize slow tests to reduce costs and improve feedback time.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="API Authentication Errors">
    **Problem**: Getting 401 or 403 errors when using the API

    **Solution**: Verify your API key is correct and has proper permissions. Get a new key from the [settings page](https://app.stably.ai/settings?tab=api-key).
  </Accordion>

  <Accordion title="Project Not Found">
    **Problem**: Error saying specified project doesn't exist

    **Solution**: Ensure the project name matches exactly what's defined in your `playwright.config.ts`
  </Accordion>

  <Accordion title="High Execution Time">
    **Problem**: Tests are taking longer than expected

    **Solution**:

    * Increase parallel test count for better parallelism
    * Check if tests have dependencies preventing parallel execution
    * Review individual test timeouts
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Define Test Groups" icon="layer-group" href="/use-cases/defining-test-groups">
    Learn how to organize tests using Playwright projects
  </Card>

  <Card title="Schedule Tests" icon="clock" href="/run-tests/scheduled-runs">
    Configure automatic test runs with cron schedules
  </Card>

  <Card title="CI/CD Integration" icon="code-branch" href="/run-tests/ci-integration">
    Integrate cloud testing into your CI/CD pipeline
  </Card>

  <Card title="Configure Notifications" icon="bell" href="/run-tests/alerting">
    Set up alerts for test results
  </Card>
</CardGroup>