Debug hybrid load tests

Troubleshoot and optimize Hybrid load tests by isolating issues between browser and API components.

This guide walks you through isolating and debugging issues in Hybrid tests that combine Browser and API components. Learn to identify which component is failing and apply targeted debugging strategies.

Understand Hybrid architecture

Hybrid tests run Browser (Browser Load Units or BLU) and API (Protocol Load Units or PLU) components simultaneously as separate child jobs.

Key characteristics:

• Browser job: Executes full user flows with real browser instances
• API job: Sends direct HTTP requests without a browser
• Both jobs: Start at different times (BLU slower to initialize than PLU)
• Combined metrics: Aggregated from both components; analyze separately to isolate issues
• Resource sharing: Some infrastructure resources shared between components

When to use Hybrid:

• Test realistic user flows that include both UI interactions and backend API calls
• Identify whether performance issues originate from frontend or backend
• Validate that APIs perform well under load independent of browser overhead

Isolate errors by component

Errors can originate from either the Browser or API component.

Steps:

1. Check the Summary tab to see overall error rate
2. Navigate to Errors tab to identify which component has failures:
   • Browser component errors: Script failures, element not found, navigation timeout
   • API component errors: HTTP status codes, connection failures, request errors
3. Determine if errors come from one component or both
4. Isolate the failing component to debug more efficiently

Browser component errors:

• Selector not found (page structure changed)
• Navigation timeout (backend slow to respond)
• Browser crash (memory exhaustion or unhandled error)
• JavaScript error (code issue in page)

API component errors:

• HTTP 4xx: Client-side request issue
• HTTP 5xx: Server error
• Connection timeout: Network or server unavailable
• Rate limited (429): Too many requests

Decision matrix:

Use this matrix to determine which component has the issue:

Debug browser component

Browser component issues relate to user interface interaction and page load.

Steps:

1. Check the Browser tab in results for browser-specific metrics:
   • Error rate and error types
   • Response time (page load time)
   • Web Vitals (LCP, INP, CLS, TTFB, FCP)
2. Open Test Run Analysis (TRA) for failing iterations:
   • Watch video recording to see what happened
   • Check Network waterfall for slow requests
   • Review debug logs for JavaScript errors
3. Compare against standalone Browser test with same script
4. Identify if browser errors correlate with API component load

Common browser issues in Hybrid:

• Slow API responses delaying page rendering
• Backend errors showing error pages to browser
• Element interactions failing due to timing issues
• Memory exhaustion from concurrent browser instances

Debugging steps:

1. Reproduce issue in standalone Browser test first
2. If issue only occurs in Hybrid, it’s likely caused by:
   • API component consuming shared infrastructure
   • Concurrent load affecting application stability
   • Test data conflicts between components
3. Check timing correlation: does browser slowness correspond to API component startup?

Debug API component

API component issues relate to direct HTTP requests.

Steps:

1. Check the API tab in results for API-specific metrics:
   • Error rate and HTTP status codes
   • Response time (p50, p95, p99)
   • Requests per second (RPS)
   • Errors by endpoint
2. Review which endpoints have failures or slowness
3. Check if API errors correlate with high browser load
4. Compare against standalone API test with same load profile

Common API issues in Hybrid:

• High error rate due to increased server load from browser component
• Slow responses caused by shared backend resources
• Rate limiting triggered by combined API + browser traffic
• Connection pool exhaustion

Debugging steps:

1. Reproduce issue in standalone API test with same Virtual Users (VUs) count and duration
2. If issue only occurs in Hybrid, shared resources or backend concurrency is the cause
3. Check if backend can handle combined load from both components
4. Consider staggering component startup or reducing overall VU count

Debug Web Vitals

Web Vitals measure real user experience and only apply to the Browser component.

Metrics:

• LCP (Largest Contentful Paint): Target < 2.5 seconds. Slow LCP often indicates slow API responses or large assets
• INP (Interaction to Next Paint): Target < 200 ms. Slow INP indicates JavaScript processing delays
• CLS (Cumulative Layout Shift): Target < 0.1. Issues indicate late-loaded content causing layout changes
• TTFB (Time to First Byte): Target < 600 ms. Backend server response time
• FCP (First Contentful Paint): Target < 1.8 seconds. Time to render first pixel

Debugging steps:

1. Open Web Vitals tab to identify which metric fails
2. Check if the failing metric correlates with API component load
3. In TRA, identify where visual rendering stalls
4. Check Network waterfall for blocking resources or slow API calls
5. Compare Web Vitals between Hybrid and standalone Browser test

Common causes:

• Slow API responses delaying page render (impacts LCP)
• Heavy JavaScript execution after page load (impacts INP)
• Render-blocking CSS or JavaScript
• Third-party scripts or tracking code
• Deferred content loading without layout reservation

Compare Hybrid vs. Standalone tests

Use comparison to determine if Hybrid-specific issues exist.

Steps:

1. Run three tests with same load profile:
   • Hybrid test: Both Browser and API components
   • Standalone Browser test: Browser component only
   • Standalone API test: API component only
2. Compare metrics side-by-side:
   • Hybrid Browser response time vs. Standalone Browser response time
   • Hybrid API response time vs. Standalone API response time
3. Identify if metrics diverge when running together

Interpretation:

Review the test results across all three runs to identify the root cause:

Analyze component startup timing

Browser and API components start at different times, affecting concurrency.

Key facts:

• API component starts first (PLU faster to initialize)
• Browser component starts seconds later (BLU needs browser provisioning)
• Peak concurrent load occurs after both components are running
• Early errors may occur when only one component is active

Analysis steps:

1. Check Engine Health tab for resource usage timeline
2. Note when errors or slowness begins
3. Correlate with component startup timeline:
   • If errors start immediately, API component has the issue
   • If errors start after 10-15 seconds, Browser component likely has the issue
   • If errors accelerate after both running, it’s concurrency or resource contention
4. Adjust test design based on findings (stagger startup, reduce VUs, etc.)

Frontend vs. backend decision tree

Use this logic to isolate the root cause:

1. Is the error rate high?
   a. Errors only in Browser
      -> Go to Debugging Browser Component
   b. Errors only in API
      -> Go to Debugging API Component
   c. Errors in both
      -> Backend infrastructure issue; check Engine Health

2. Is response time slow?
   a. Browser slow, API normal
      -> Frontend issue or backend API returning late (check TTFB)
   b. API slow, Browser normal
      -> Backend issue; may cascade to Browser as pageloads slow
   c. Both slow
      -> Shared infrastructure under pressure; reduce load

3. Is throughput low?
   a. Browser throughput low
      -> Check page load times; reduce think time between interactions
   b. API throughput low
      -> Check request rate; increase connection pooling; verify no rate limits
   c. Both low
      -> Infrastructure bottleneck or network saturation

Common pitfalls

Avoid these mistakes when testing and analyzing Hybrid load tests:

Next steps

• For unresolved issues, contact our technical support team with test execution IDs and TRA recordings
• Review Load Testing FAQs for general questions
• Check the Troubleshooting guide for additional debugging techniques