Skip to main content

​
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

config.yaml
project_name: bugster-nextjs-example
project_id: bugster-nextjs-example-1756145574
base_url: "http://localhost:3000"
​
project_name
string
Auto-assigned by Bugster when you initialize your project.
​
project_id
string
Unique identifier generated by Bugster for linking test results, dashboards, and CI jobs.
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.
​
base_url
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
In CI/CD pipelines, Bugster automatically overwrites this with the Vercel preview URL, so you don’t need to change it for PR checks.

​
Project Authentication

config.yaml
# credentials:
#   - id: admin
#     username: ${BUGSTER_USERNAME}
#     password: ${BUGSTER_PASSWORD}
​
credentials
array
Define login accounts used by tests.
Create environment variables following our dedicated guide. We do not recommend storing testing credentials directly in the config file.
For more details, see: Add Credentials, Roles and Permissions.

​
Vercel Preview Protection

config.yaml
# x-vercel-protection-bypass: ${VERCEL_BYPASS_SECRET}
​
x-vercel-protection-bypass
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 in Vercel.

​
Test Execution Preferences

All preferences are commented by default. Uncomment lines to activate specific settings.
config.yaml
# 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

config.yaml
always_run:
  - .bugster/tests/smoke/login.yaml
  - .bugster/tests/smoke/checkout.yaml
​
always_run
array
Guarantee critical flows (like login/checkout) always run, even if you limit or filter other tests.

​
Test Limits

config.yaml
limit: 10
​
limit
integer
Restrict how many tests run in a session.Benefits:
  • Fast PR checks
  • Limiting credits usage in CI pipelines

​
Browser Mode

config.yaml
headless: true
​
headless
boolean
Run without a visible browser (true) or with UI (false).Recommendations:
  • CI environments: true
  • Local debugging: false

​
Logging Control

  • Silent Mode
  • Verbose Mode
config.yaml
silent: true
​
silent
boolean
Produces cleaner CI logs by reducing output verbosity.

​
Smart Test Selection

config.yaml
only_affected: true
​
only_affected
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

​
Parallel Execution

config.yaml
parallel: 6
​
parallel
integer
Number of tests to run simultaneously. Increase for faster pipelines.
Setting parallel execution too high may overload shared services. Start with small values and scale up once stable.

​
Output Configuration

config.yaml
output: .artifacts/bugster_output.json
​
output
string
Write structured JSON results for dashboards, artifacts, or CI reports.Use cases:

​
CLI Overrides

CLI flags always override YAML configuration values.
Example: 
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:
config.yaml
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:
config.yaml
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

  • 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)
  • 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
  • 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

​
Next Steps

Authentication Setup

Learn how to configure credentials and user roles for comprehensive testing

Test Management

Discover how to create, organize, and manage your test suites effectively
⌘I