Headful and Headless mode

Choose between headful and headless execution modes for browser-based load tests. Headless mode optimizes performance and cost, while headful mode provides full browser context for visual dependencies and UI interactions.

By default, BrowserStack Load Testing runs browser-based tests in headless mode, which optimizes scalability and cost efficiency. However, you can enable headful mode when your tests depend on visual rendering or UI interactions that require a full browser context.

Choose the right execution mode based on your testing requirements and infrastructure constraints.

When to use each mode

Each execution mode serves different testing needs. Choose headless for standard performance testing or headful when your tests require visual context and browser rendering.

How to choose your execution mode

Use this quick checklist to determine which mode is right for your load test:

Choose headless mode if:

• Your tests focus on API interactions and network requests
• You’re testing authentication flows, data validation, or backend functionality
• You need to maximize performance and minimize infrastructure costs
• Your application doesn’t rely on CSS rendering or visual elements
• You want to run high-concurrency load tests (50+ virtual users)

Choose headful mode if:

• Your tests require interaction with rendered UI elements (buttons, forms, dropdowns)
• Your application uses WebGL, Canvas, or GPU-accelerated graphics
• You need to test drag-and-drop, hover states, or other pointer-based interactions
• You’re validating visual output, screenshots, or CSS rendering
• Your test fails in headless mode but works locally in a full browser

Performance and cost impact

Running tests in headful mode requires substantially more infrastructure resources than headless mode:

Resource consumption:

• CPU usage: 2-3x higher per virtual user
• Memory usage: 3-5x higher per virtual user

Cost implications:

• Headful mode test execution incurs higher infrastructure costs due to increased resource consumption, with a cost multiplier of approximately 1.5-2x compared to equivalent headless tests

Configure execution mode

Select your execution mode when configuring a load test:

Execution mode priority

The mode you select in the UI takes priority over any configuration in your test script.

The system follows this priority order:

1. UI selection - The mode you select in the load testing dashboard (highest priority)
2. Script configuration - The headless setting in your test script
3. Default - Headless mode (if no other setting is specified)

Depending on your preferred method, select any one of the following:

    headless: false  # Set to false for headful mode,
    headless: true # (default: true) Set to true for headless

Execution metadata

When you run a load test, the system records the execution mode in the test metadata as:

View this metadata on the test results page to confirm which execution mode you used.

Common questions and edge cases

Can I use different execution modes for different scenarios in one test?

No. Execution mode is a global setting that applies to the entire test run across all scenarios. You cannot configure different execution modes for individual scenarios within the same test.

Does execution mode affect hybrid load tests (browser + protocol)?

Execution mode applies to the browser component of hybrid tests. Protocol-based components (JMeter, k6) are not affected by the headless/headful setting.

What if my test fails in headless mode?

Before switching to headful mode (which increases costs), investigate the root cause:

• Check if the failure is visual (UI rendering, CSS, graphics) or functional (logic, data, API)
• Test your script locally in both headless and headful modes to identify the specific issue
• Only switch to headful mode if the failure is specifically related to browser rendering or visual interactions

Can I cancel a headful mode test run before it incurs charges?

Yes. You can stop a running test from the test results dashboard at any time. This minimizes unnecessary resource consumption and costs if you realize the headful mode test is not needed.

How do I compare results between headless and headful modes?

Run the same test configuration in both modes and compare the results:

• Navigate to the test run history
• Select runs from both modes
• Compare metrics like response times, throughput, and error rates
• Note that headful mode may have slightly higher latency due to browser rendering overhead

Does headful mode work with network throttling and other advanced settings?

Yes. Headful mode is compatible with all load configuration options including network throttling, response capture, execution logs, and environment variables. There are no limitations when combining headful mode with other settings.

Related topics

• Configure load parameters - Overview of all available load configuration options
• Run a test - Get started with browser-based load testing