Fail a load test on threshold breach

Stop a load test automatically when a critical performance threshold is breached during execution. Save VU hours and get faster feedback by failing tests mid-run instead of waiting for them to complete.

Instead of waiting for the entire test to finish, BrowserStack evaluates your thresholds in real time and fails the test within seconds of a breach. This works with both protocol tests (k6, JMeter, Gatling) and browser tests (Playwright, Selenium, WebdriverIO, Nightwatch).

Setting up fail-on-breach takes about 5 minutes.

Prerequisites

Before you enable fail-on-breach, make sure you have:

• A BrowserStack Load Testing account with an active plan.
• A project with at least one test configured. If you’re new, start with Run your first load test.
• At least one threshold defined on your load test if you haven’t configured thresholds yet.

Enable fail-on-breach

Depending on your preferred method, select any one of the following to enable fail-on-breach:

thresholds:
  - metric: avg-response-time
    condition: '<='
    threshold: 500
    failOnBreach: true
  - metric: error-percentage
    condition: '<='
    threshold: 5
    failOnBreach: true
  - metric: p95-response-time
    condition: '<='
    threshold: 800
    failOnBreach: false   # evaluated only after the test completes (default)

thresholds:
  - metric: avg-response-time
    condition: '<='
    threshold: 200
    request: '/api/checkout'
    failOnBreach: true
  - metric: error-percentage
    condition: '<='
    threshold: 1
    request: '/api/payments/*'
    failOnBreach: true

scenarios:
  - name: checkout-flow
    thresholds:
      - metric: avg-response-time
        condition: '<='
        threshold: 300
        failOnBreach: true
  - name: browse-catalog
    thresholds:
      - metric: error-percentage
        condition: '<='
        threshold: 2
        failOnBreach: true

How it works

Once your test starts running, BrowserStack monitors the thresholds you marked with fail-on-breach:

• Grace period (30 seconds). After your test starts, the system waits 30 seconds before the first evaluation. This allows enough metrics to accumulate for a meaningful comparison.
• Evaluation every 30 seconds. After the grace period, the system checks all fail-on-breach thresholds against live metrics every 30 seconds. Metrics are queried from accumulated test data, not sampled from a single moment.
• On breach: test fails immediately. If any fail-on-breach threshold is violated, the test is stopped and its status is set to Failed. All running virtual users are terminated, and the test results page shows which threshold caused the failure.
• No breach: test completes normally. If no fail-on-breach threshold is violated during the test, the test completes as usual. All thresholds (including the fail-on-breach ones) are re-evaluated at completion with the full dataset as the final source of truth.

Verify it worked

After the test runs, confirm the outcome on the test detail page.

If a threshold was breached:

• The test status shows Failed on the jobs list and the test detail page.
• The failure reason is displayed as a threshold breach — not a script error or timeout.
• The Thresholds section in the test results shows which threshold or thresholds were breached, with the actual value at the time of breach.
• The test duration is shorter than the configured duration, since the test was stopped early.

If no threshold was breached:

• The test status shows Completed.
• Thresholds are evaluated with the full dataset at completion. Results appear in the Thresholds section as usual.

In the test configuration panel:

• Thresholds with fail-on-breach enabled show a Fail on breach badge next to their condition.

Configuration reference

The following settings control fail-on-breach behavior:

Surfaces

You can configure fail-on-breach from any of the following surfaces:

Multi-scenario behavior

For browser tests with multiple scenarios, fail-on-breach behaves as follows:

• Scenario-level threshold breaches only stop the breaching scenario. Other scenarios continue running normally.
• Global thresholds (applied to All scenarios) are evaluated against the combined metrics of all scenarios.
• The parent job is not auto-failed. Its final threshold status is determined after all scenarios complete.

Troubleshooting

Use this section to debug unexpected results.

My test didn’t fail even though the metric exceeded the threshold

Check the following:

• Check the toggle. Confirm that fail-on-breach is enabled on the specific threshold. Regular thresholds are only evaluated at completion.
• Check the grace period. The first evaluation happens 30 seconds after the test starts. If your test is shorter than 30 seconds, fail-on-breach has no effect.
• Check the condition direction. A threshold with condition: '<=' and threshold: 500 means “the metric should be at most 500”. If your actual value is 400, the threshold passes — it’s not breached.
• Endpoint not yet hit. If an endpoint-scoped threshold targets a URL that hasn’t received any traffic yet, the system skips it and retries on the next cycle. It does not fail the test for missing data.

My test failed but I expected it to pass

Check the following:

• Check accumulated metrics. Mid-execution evaluation uses accumulated data from the start of the test, not a point-in-time snapshot. Early spikes (for example, during warm-up) can push averages above the threshold.
• Consider the grace period. If your application needs more than 30 seconds to warm up, your thresholds may be breached during the warm-up phase. Adjust your threshold values to account for warm-up, or move critical thresholds to post-completion only (toggle off).

The test shows “Failed” but I manually stopped it

What’s next

Explore related topics to make the most of fail-on-breach:

• Set thresholds — Configure the metrics and conditions for your thresholds.
• View test results — Understand how to read threshold results on the test detail page.
• Ramping VUs — Configure VU ramp-up patterns to reduce warm-up false positives.