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

# Run

> Execute your test specifications with browser automation

The `bugster run` command executes your test specifications using an AI agent in automated browser instances. It provides comprehensive test execution with real browser automation and intelligent result analysis.

## Basic Usage

```bash theme={null}
bugster run
```

## Command Overview

Executes test specifications using AI-powered browser automation to validate your application's functionality across different scenarios and user flows.

### When to Use

* **Before deploying** to validate functionality
* In CI/CD pipelines for automated testing
* During development to catch regressions
* To verify fixes after bug reports

### Key Features

* AI agent executes tests in real browser instances
* Supports parallel execution for faster results
* Automatic video recording for failed tests
* Real-time streaming to dashboard
* Quick ad-hoc testing with text prompts

<Warning>
  Requires your application to be running and accessible on the configured URL before executing tests.
</Warning>

## Command Syntax

```bash theme={null}
bugster run [path] [options]
```

## How It Works

The run command:

1. **Test Discovery**: Scans for test specifications in `.bugster/tests/` directory
2. **Browser Initialization**: Launches browser instances (visible or headless)
3. **AI Execution**: AI agent interprets and executes test steps
4. **Result Analysis**: Captures screenshots, videos, and detailed logs
5. **Reporting**: Streams results to dashboard and generates reports

## Execution Options

<ParamField query="--headless" type="boolean">
  Run tests in headless mode without visible browser UI. Ideal for CI/CD environments.
</ParamField>

<ParamField query="--parallel" type="integer" default="3">
  Maximum number of concurrent tests to run simultaneously. Higher values speed up execution but use more resources.
</ParamField>

<ParamField query="--max-concurrent" type="integer">
  Alias for `--parallel`. Specifies the maximum number of tests to run concurrently.
</ParamField>

<ParamField query="--limit" type="integer">
  Maximum number of tests to execute. Useful for quick validation or debugging specific test counts.
</ParamField>

<ParamField query="--browser" type="string" default="chromium">
  Browser engine to use for test execution. Supports chromium, firefox, and webkit.
</ParamField>

<ParamField query="--viewport-size" type="string" default="1280x720">
  Set the browser viewport size in WIDTHxHEIGHT format (e.g., 1920x1080, 1280x720, 375x667 for mobile).
</ParamField>

<ParamField query="--prompt" type="string">
  Run an instant test from a text description (max 1000 characters). Creates and executes a test without needing YAML files.
</ParamField>

<ParamField query="--quick" type="string">
  Alias for `--prompt`. Run a quick test from natural language description.
</ParamField>

## Filtering Options

<ParamField query="--only-affected" type="boolean">
  Run only tests for files/directories that have been modified. Perfect for PR workflows and focused testing.
</ParamField>

<ParamField query="--base-url" type="string">
  Override the base URL from configuration. Useful for testing against different environments.
</ParamField>

## Output Options

<ParamField query="--output" type="string">
  Save detailed test results to a JSON file. Essential for CI/CD integration and test reporting.
</ParamField>

<ParamField query="--stream-results" type="boolean" default="true">
  Stream real-time results to the Bugster dashboard for live monitoring.
</ParamField>

<ParamField query="--no-stream-results" type="boolean">
  Disable streaming to dashboard. Results will only be available locally.
</ParamField>

<ParamField query="--verbose" type="boolean">
  Enable detailed logging output for debugging test execution issues.
</ParamField>

<ParamField query="--silent" type="boolean">
  Run in silent mode with minimal output. Reduces noise in CI/CD logs.
</ParamField>

## Examples

### Complete Test Suite

```bash theme={null}
bugster run
```

Runs all available tests with default settings and visible browser.

### Headless CI/CD Execution

```bash theme={null}
bugster run --headless --stream-results
```

Perfect for automated testing in continuous integration pipelines.

### Parallel Execution

```bash theme={null}
bugster run --parallel 8 --headless
```

Runs up to 8 tests concurrently for maximum speed.

### Target Specific Directory

```bash theme={null}
bugster run auth/ --verbose
```

Runs only authentication tests with detailed debugging output.

### Quick Ad-hoc Testing

```bash theme={null}
bugster run --prompt "Test user login with valid credentials and verify dashboard loads"
```

Creates and runs an instant test from natural language description.

### Environment Testing

```bash theme={null}
bugster run --base-url https://staging.myapp.com --limit 5
```

Tests against staging environment with a limited number of tests.

### Custom Viewport Size

```bash theme={null}
bugster run --viewport-size 1920x1080
```

Run tests with a specific browser viewport size. Useful for testing responsive designs or specific screen resolutions.

## Quick Test Prompts

<Tabs>
  <Tab title="Authentication">
    ```bash theme={null}
    bugster run --prompt "Test user login with valid credentials and verify dashboard loads"
    ```

    Complete login flow validation.
  </Tab>

  <Tab title="E-commerce">
    ```bash theme={null}
    bugster run --prompt "Add product to cart, proceed to checkout, and verify total calculation"
    ```

    Shopping workflow testing.
  </Tab>

  <Tab title="Form Validation">
    ```bash theme={null}
    bugster run --prompt "Test contact form with invalid email and verify error messages"
    ```

    Form error handling validation.
  </Tab>

  <Tab title="Mobile Testing">
    ```bash theme={null}
    bugster run --prompt "Test navigation menu on mobile device and verify all links work"
    ```

    Mobile-specific functionality testing.
  </Tab>
</Tabs>

## Common Usage Patterns

<CardGroup cols={2}>
  <Card title="Development Testing" icon="code">
    ```bash theme={null}
    bugster run
    ```

    Run all tests with visible browser for development.
  </Card>

  <Card title="CI/CD Pipeline" icon="rocket">
    ```bash theme={null}
    bugster run --headless --output results.json
    ```

    Automated testing with result export.
  </Card>

  <Card title="Quick Validation" icon="bolt">
    ```bash theme={null}
    bugster run --limit 5 --parallel 3
    ```

    Fast subset testing for quick feedback.
  </Card>

  <Card title="Debugging" icon="bug">
    ```bash theme={null}
    bugster run auth/ --verbose
    ```

    Detailed logging for specific test categories.
  </Card>
</CardGroup>

## Test Results

After execution, you'll receive:

* **Pass/Fail Status**: Clear indication of test outcomes
* **Screenshots**: Visual evidence of test execution
* **Video Recordings**: Automatic recording for failed tests
* **Detailed Logs**: Step-by-step execution information
* **Performance Metrics**: Timing and resource usage data

## Best Practices

<Tip>
  Use `--only-affected` in PR workflows to test only changed functionality. Combine `--parallel` with `--headless` for maximum execution speed in CI/CD environments.
</Tip>

<Note>
  Quick prompt tests are limited to 1000 characters and run with maximum concurrency of 1. They're perfect for exploratory testing and quick validation scenarios.
</Note>