The bugster run command executes your generated test specifications using browser automation, validating that your application works as expected. It runs tests against your configured application URL and reports results.

You must run bugster init and bugster generate before using the run command. Ensure your application is running on the configured base URL.

​
Basic Usage

bugster run

This command will:

  1. Load test specifications from .bugster/tests/ directory
  2. Launch browser automation using Playwright
  3. Execute test steps against your application
  4. Report results with pass/fail status and detailed feedback

​
How It Works

1

Test Discovery

Bugster scans for test files:

  • Loads all .yaml files from .bugster/tests/
  • Applies test limits and filtering (if configured)
  • Processes always-run tests first
  • Organizes execution order
2

Browser Automation

For each test specification:

  • Launches a browser instance (Chrome by default)
  • Navigates to your application
  • Authenticates using configured credentials
  • Executes each test step in sequence
3

Results Collection

After execution:

  • Records pass/fail status for each test
  • Captures failure reasons and screenshots
  • Optionally records video of test execution
  • Streams results to dashboard (if enabled)

​
Command Flags and Options

​
Path Targeting

bugster run [path]

​
Browser Configuration

bugster run --headless

​
Output Control

bugster run --silent

bugster run --verbose

​
Environment Configuration

bugster run --base-url https://staging.myapp.com

​
Test Selection and Filtering

bugster run --only-affected

​
Concurrency Control

bugster run --max-concurrent 3

​
Combined Usage Examples

​
Development Workflow

# Quick test run with debugging
bugster run auth/ --verbose --max-concurrent 1

# Silent production-like run
bugster run --headless --silent 

# Test specific feature after changes
bugster run --only-affected

​
Test Execution Flow

​
Test Discovery and Limits

🧪 Loading tests...
📊 Test limit applied: Running 5 out of 12 tests (limit: 5)

Distribution by folder:
📁 auth: 2 tests
📁 dashboard: 2 tests  
📁 checkout: 1 test

🎯 Always-run tests: 2 (additional to limit)
📊 Total tests to run: 7 (regular: 5 + always-run: 2)

​
Parallel Execution

When running multiple tests concurrently, you’ll see compact status updates:

⚡ Executing tests...
[Login Flow             ] Starting test
[User Registration      ] Starting test  
[Dashboard Overview     ] Starting test
[Login Flow             ] Finished: pass (Time: 12.3s)
[User Registration      ] Finished: pass (Time: 15.7s)
[Dashboard Overview     ] Finished: fail (Time: 8.9s)

​
Results Summary

Test Results
┌─────────────────────┬────────┬─────────────────────────┬──────────┐
│ Name                │ Result │ Reason                  │ Time (s) │
├─────────────────────┼────────┼─────────────────────────┼──────────┤
│ Login Flow          │ pass   │ All steps completed     │ 12.30    │
│ User Registration   │ pass   │ All steps completed     │ 15.70    │
│ Dashboard Overview  │ fail   │ Element not found       │ 8.90     │
└─────────────────────┴────────┴─────────────────────────┴──────────┘

Test Summary
✅ Passed: 2
❌ Failed: 1  
📊 Success Rate: 66.7%

Total execution time: 45.2 seconds

​
Test Limits and Selection

​
Default Test Limits

  • Free tier: Maximum 5 tests per execution
  • Distribution: Tests spread across feature folders
  • Always-run tests: Execute in addition to the limit
  • Selection algorithm: Representative tests chosen intelligently

​
Test Selection Logic

Folder Distribution

Algorithm: Tests distributed evenly across folders

Example: 15 total tests, 5 limit

  • auth/: 2 tests selected
  • dashboard/: 2 tests selected
  • checkout/: 1 test selected

Always-Run Priority

Execution: Always-run tests execute first

Additional: Count separately from regular limits

Maximum: Up to 3 always-run tests per execution

​
Video Recording

Tests automatically record execution for debugging:

​
Video Recording

  • Location: .bugster/videos/{run-id}/{test-id}/
  • Format: WebM video files
  • Content: Complete test execution from start to finish
  • Accessibility: Videos uploaded to dashboard when streaming enabled

​
Authentication Handling

​
Credential Usage

Tests automatically handle authentication using configured credentials:

# In your test file
credentials:
  - id: "admin"
    username: "admin@example.com"
    password: "admin123"

​
Authentication Flow

  1. Credential selection: Test uses appropriate credential set
  2. Login execution: Automated login using provided credentials
  3. Session management: Maintains authentication throughout test
  4. Logout handling: Cleans up sessions between tests

​
Best Practices

Performance Optimization

Use appropriate concurrency: Higher for fast feedback, lower for stability

Run targeted tests: Use --only-affected during development

Environment-specific runs: Use --base-url for different environments

Headless in CI/CD: Always use --headless in automated pipelines

Debugging and Development

Sequential execution: Use --max-concurrent 1 when debugging

Verbose output: Add --verbose to understand test execution

Local URLs: Test against localhost during development

Save results: Use --output to analyze test patterns

​
Troubleshooting

​
Exit Codes

The bugster run command uses standard exit codes:

  • Exit 0: All tests passed successfully
  • Exit 1: One or more tests failed or execution error occurred

This enables proper CI/CD integration where failed tests fail the build.

​
Next Steps

After running tests, you can:

Update Tests

Keep tests synchronized with code changes