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

# Advanced Configuration

> Change your config.yaml to customize project settings and test execution preferences

# Bugster Configuration File

Learn how to customize Bugster's behavior through the `config.yaml` file to adapt the setup according to your project's preferences and workflows.

The configuration file allows you to control everything from test execution preferences to authentication settings, giving you full control over how Bugster runs in your environment.

## Project Information

```yaml config.yaml theme={null}
project_name: bugster-nextjs-example
project_id: bugster-nextjs-example-1756145574
base_url: "http://localhost:3000"
```

<ResponseField name="project_name" type="string">
  Auto-assigned by Bugster when you initialize your project.
</ResponseField>

<ResponseField name="project_id" type="string">
  Unique identifier generated by Bugster for linking test results, dashboards, and CI jobs.
</ResponseField>

<Warning>
  Do not edit `project_name` or `project_id` fields in the config file. They are used internally by the system for linking test results, dashboards, and CI jobs.
</Warning>

<ResponseField name="base_url" type="string">
  The URL where your application is running. This is the field you can modify.

  **Default:** `http://localhost:3000` - ideal when developing locally.

  **Use cases:**

  * Point to other environments (staging, preprod, prod)
  * Adjust the port if your local server runs on something other than 3000 (e.g., `http://localhost:5173`)
  * Run against `https://staging.myapp.com` before a release to confirm flows work in pre-production

  <Note>
    In CI/CD pipelines, Bugster automatically overwrites this with the Vercel preview URL, so you don't need to change it for PR checks.
  </Note>
</ResponseField>

## Project Authentication

```yaml config.yaml theme={null}
# credentials:
#   - id: admin
#     username: ${BUGSTER_USERNAME}
#     password: ${BUGSTER_PASSWORD}
```

<ResponseField name="credentials" type="array">
  Define login accounts used by tests.

  <Expandable title="Credentials Properties">
    <ResponseField name="id" type="string">
      Friendly alias like `admin`, `viewer`, `editor`.
    </ResponseField>

    <ResponseField name="username" type="string">
      Username provided via environment variables, not hardcoded.
    </ResponseField>

    <ResponseField name="password" type="string">
      Password provided via environment variables, not hardcoded.
    </ResponseField>
  </Expandable>
</ResponseField>

<Tip>
  Create environment variables following our dedicated guide. We do not recommend storing testing credentials directly in the config file.
</Tip>

For more details, see: [Add Credentials, Roles and Permissions](/guides/test-management/credentials-and-roles).

## Vercel Preview Protection

```yaml config.yaml theme={null}
# x-vercel-protection-bypass: ${VERCEL_BYPASS_SECRET}
```

<ResponseField name="x-vercel-protection-bypass" type="string">
  Use when your Vercel previews are protected. Add your bypass secret so Bugster can test non-interactively.

  **Use case:** CI runs against vercel.app previews that normally require login.

  To generate the bypass secret, navigate to your project's [Deployment Protection settings](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fsettings%2Fdeployment-protection\&title=Deployment+Protection+settings) in Vercel.
</ResponseField>

## Test Execution Preferences

All preferences are commented by default. Uncomment lines to activate specific settings.

```yaml config.yaml theme={null}
# preferences:
#   tests:
#     always_run:
#       - .bugster/tests/test1.yaml
#     limit: 5
#     headless: false
#     silent: false
#     verbose: false
#     only_affected: false
#     parallel: 5
#     output: bugster_output.json
```

### Always Run Tests

```yaml config.yaml theme={null}
always_run:
  - .bugster/tests/smoke/login.yaml
  - .bugster/tests/smoke/checkout.yaml
```

<ResponseField name="always_run" type="array">
  Guarantee critical flows (like login/checkout) always run, even if you limit or filter other tests.
</ResponseField>

### Test Limits

```yaml config.yaml theme={null}
limit: 10
```

<ResponseField name="limit" type="integer">
  Restrict how many tests run in a session.

  **Benefits:**

  * Fast PR checks
  * Limiting credits usage in CI pipelines
</ResponseField>

### Browser Mode

```yaml config.yaml theme={null}
headless: true
```

<ResponseField name="headless" type="boolean">
  Run without a visible browser (`true`) or with UI (`false`).

  **Recommendations:**

  * CI environments: `true`
  * Local debugging: `false`
</ResponseField>

### Logging Control

<Tabs>
  <Tab title="Silent Mode">
    ```yaml config.yaml theme={null}
    silent: true
    ```

    <ResponseField name="silent" type="boolean">
      Produces cleaner CI logs by reducing output verbosity.
    </ResponseField>
  </Tab>

  <Tab title="Verbose Mode">
    ```yaml config.yaml theme={null}
    verbose: true
    ```

    <ResponseField name="verbose" type="boolean">
      Provides detailed logs for debugging purposes.
    </ResponseField>
  </Tab>
</Tabs>

### Smart Test Selection

```yaml config.yaml theme={null}
only_affected: true
```

<ResponseField name="only_affected" type="boolean">
  Instead of running all tests (or up to the limit), Bugster only runs tests affected by recent changes based on git diff.

  **Features:**

  * Works both locally and on PRs
  * `always_run` tests will still execute regardless
</ResponseField>

### Parallel Execution

```yaml config.yaml theme={null}
parallel: 6
```

<ResponseField name="parallel" type="integer">
  Number of tests to run simultaneously. Increase for faster pipelines.
</ResponseField>

<Warning>
  Setting parallel execution too high may overload shared services. Start with small values and scale up once stable.
</Warning>

### Output Configuration

```yaml config.yaml theme={null}
output: .artifacts/bugster_output.json
```

<ResponseField name="output" type="string">
  Write structured JSON results for dashboards, artifacts, or CI reports.

  **Use cases:**

  * Dashboard integration
  * CI artifact storage
  * Piping results into coding agents (see [Claude Code / Cursor Use Case](/guides/coding-agents))
</ResponseField>

## CLI Overrides

<Info>
  CLI flags always override YAML configuration values.
</Info>

**Example:**

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

This command will ignore the `only_affected` and `parallel` values in your YAML configuration.

## Common Configuration Scenarios

### Local Debugging

Perfect for watching flows in a real browser during development:

```yaml config.yaml theme={null}
preferences:
  tests:
    headless: false
    verbose: true
    parallel: 5
    limit: 15
    output: bugster_output.json
```

**Use case:** Watch flows in a real browser, run \~15 tests, and export results as JSON for use with a coding agent.

### CI for Pull Requests

Optimized for fast feedback with minimal resource usage:

```yaml config.yaml theme={null}
preferences:
  tests:
    headless: true
    only_affected: true
    always_run:
      - .bugster/tests/smoke/login.yaml
    parallel: 6
    silent: true
```

**Use case:** Fast PR checks that protect core flows while keeping runtime and credits low.

## Best Practices

<AccordionGroup>
  <Accordion title="Configuration Management">
    * Always uncomment lines you want active
    * Store sensitive data (credentials, secrets) in environment variables, not plain text
    * Use version control for your config.yaml file (excluding sensitive data)
  </Accordion>

  <Accordion title="Performance Optimization">
    * Start with small parallel values, scale up once stable
    * Use `only_affected` + `always_run` for efficient PR checks
    * Set appropriate `limit` values to control resource usage
  </Accordion>

  <Accordion title="Environment Strategy">
    * Adjust `base_url` for different environments (local, staging, production)
    * Use environment-specific configuration files when needed
    * Export results with `output` for flaky test tracking or coding agent integrations
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication Setup" icon="key" href="/guides/authentication">
    Learn how to configure credentials and user roles for comprehensive testing
  </Card>

  <Card title="Test Management" icon="list-check" href="/guides/test-management/test-crud">
    Discover how to create, organize, and manage your test suites effectively
  </Card>
</CardGroup>