Skip to main content

Using Extended Debugging

Enable Extended Debugging in your Selenium test script to collect console logs and HTTP Archive (HAR) files generated during testing for use in diagnosing flaky tests or performance degradation.

note

Extended Debugging generates additional assets that impact test performance and is not intended for everyday testing.

What You'll Need

  • A Sauce Labs account (Log in or sign up for a free trial license)
  • Your Sauce Labs Username and Access Key
  • Google Chrome (no older than 3 versions from latest) or Firefox browser (versions 53 and above) as the test browser
    Multi-Window Limitation on Chrome Browser

    In rare instances, tests running in Chrome that launch multiple browser windows may result in a Chrome DevTools socket interruption that throws a 408 Automation Server Error. If this happens, discontinue extended debugging for tests that utilize multiple windows.

Enabling Extended Debugging

To generate the JS console logs and HAR files, add the extendedDebugging capability to the capabilities of your test and set it to true. Here are some example scripts in both W3C WebDriver Protocol and legacy JSON Wire Protocol that show Extended Debugging enabled.

const capabilities: {
browserName: 'chrome',
browserVersion: 'latest',
platformName: 'Windows 10',
'sauce:options': {
extendedDebugging: true,
}
}

For more information and additional examples, see our Extended Debugging Example GitHub repo.

When a test with extended debugging enabled completes, you can access the logs and files through Sauce Labs or with the REST API.

Edit Your Firefox Profile

If you're testing on a Firefox browser, edit the Firefox about:config file to configure your profile as follows to allow Extended Debugging:

about:config Settings
'mozz:firefoxOptions': {
'profile': '<CUSTOM_PROFILE_ID>',
'args': [
'-start-debugger-server',
'9222'
],
prefs: {
'devtools.debugger.remote-enabled': true,
'devtools.debugger.prompt-connection': false,
'devtools.chrome.enabled': true
}
},

Using the JavaScript Executor to Simulate Network Conditions

Selenium's JavascriptExecutor lets you use JavaScript commands in your test scripts to perform actions in the browser, and Sauce Labs exposes a set of custom JavascriptExecutor methods for use with your tests. The commands defined on this page allow you to simulate various test environments for more effective debugging.

Intercept Network Requests

Use the sauce:intercept JavascriptExecutor command to modify browser requests to:

  • Prohibit requests to 3rd party vendors
  • Modify requests to REST API (Mock REST API response)
  • Redirect certain parts of the app
  • Insert or change headers

The following use cases are supported for the sauce:intercept command.

sauce:intercept + redirect

Configure sauce:intercept to redirect an outgoing request to an alternate URL.

Command Parameters
url

| REQUIRED | STRING |

An outgoing request URL. Wildcards are supported, for example https://saucelabs.com/rest/v1/* would redirect any v1 rest API requests.

redirect

| REQUIRED | STRING |

An absolute URL to where the original request is redirected. The code samples use https://google.com.

Examples
driver.execute_script('sauce:intercept', {
"url": "https://saucelabs.com",
"redirect": "https://google.com"
})

sauce:intercept + response

Configure sauce:intercept to return the specified response.

Command Parameters
url

| REQUIRED | STRING |

An outgoing request URL. Wildcards are supported, for example https://saucelabs.com/rest/v1/* would redirect any v1 rest API requests.

response

| REQUIRED | STRING |

An object that defines the response to send when the requested URL is intercepted. Valid attributes of the response are:

  • status: HTTP response code representing the request status, such as 200.
  • headers: List of key/value pairs set as header variables, for example, Cookie: "foo=bar".
  • body: Actual response payload to return.
Examples
driver.execute_script("sauce:intercept", {
"url": "http://sampleapp.appspot.com/api/todos",
"response": {
"headers": {
"x-custom-header": "foobar"
},
"body": [{
"title": "Hello",
"order": 1,
"completed": false,
"url": "http://todo-backend-express.herokuapp.com/15727"
}]
}
})

sauce:intercept + error

Configure sauce:intercept to return the specified error.

Command Parameters
url

| REQUIRED | STRING |

An outgoing request URL. Wildcards are supported, for example https://saucelabs.com/rest/v1/* would redirect any v1 rest API requests.

error

| REQUIRED | STRING |

A valid error status to return when the requested URL is intercepted. Valid values are:

  • Failed
  • Aborted
  • TimedOut
  • AccessDenied
  • ConnectionClosed
  • ConnectionReset
  • ConnectionRefused
  • ConnectionAborted
  • ConnectionFailed
  • NameNotResolved
  • InternetDisconnected
  • AddressUnreachable
Examples
driver.execute_script("sauce:intercept", {
"url": "https://saucecon.com/wp-content/uploads/2017/07/SauceCon-hero-img-100-2.jpg",
"error": "Failed"})

Throttle Conditions

Use the JavascriptExecutor throttle commands to simulate different connectivity conditions that may affect the performance of your app.

sauce:throttleCPU

Mobile devices have less CPU power than most desktops and laptops (or a VM's default configuration). Use CPU Throttling to simulate how your app will run on slower systems.

Command Parameters
rate

| REQUIRED | STRING |

A number defining the amount of slowdown (e.g., 2 ~ 2x slowdown, your CPU will be 2 times slower than usual).

Examples
driver.execute_script('sauce:throttleCPU', {
"rate": 4
})

sauce:throttleNetwork

With network conditioning you can test your site on a variety of network connections, including Edge, 3G, and even offline. You can throttle the data throughput, including the maximum download and upload throughput, and use latency manipulation to enforce a minimum delay in connection round-trip time (RTT).

Command Parameters
condition

| REQUIRED | STRING |

A string or object representing browser network conditions. Sauce Labs supports the following predefined network profiles:

ProfileDownload Speed (kb/s)Upload Speed (kb/s)Round Trip Time (ms)
offline000
GPRS5020500
Regular 2G25050300
Good 2G450150150
Regular 3G750250100
Good 3G1Mb/s75040
Regular 4G4Mb/s3Mb/s20
DSL2Mb/s1Mb/s5
WiFi30Mb/s15Mb/s2
onlineNo RestrictionsNo RestrictionsNo Restrictions

Alternatively, you can define an object specifying individual parameters for each of the three network values, as shown in the code examples:

  • download
  • upload
  • latency
Examples
driver.execute_script('sauce:throttleNetwork', {
"condition": "GPRS"
})
# or
driver.execute_script('sauce:throttleNetwork', {
"condition": {
"download": 1000,
"upload": 500,
"latency": 40
}
})

JavaScript (JS) Console Logs

The JS console collects security errors, warnings, and messages that are explicitly logged by the browser. You can use these logs to find out which components of your web app failed to load or ran into an error, what warnings were logged by the browser, and get more information about app performance. The console log information is associated with the URL where it occurred, and is composed of four types of information: Log, Info, Warning, and Error. In this example, you can see how an error was generated for the URL https://pbs.twimg.com/profile_images/477099293250052097/fMFjb8gu_400x400.jpeg when a resource failed to load:

{
"http://webdriver.io/api/action/click.html":[
{
"level":"error",
"column":0,
"text":"Failed to load resource: the server responded with a status of 404 (OK)",
"source":"network",
"networkRequestId":"1543.182",
"url":"https://pbs.twimg.com/profile_images/477099293250052097/fMFjb8gu_400x400.jpeg",
"timestamp":1501197041.22091,
"line":0,
"type":"log"
}
]
}

Accessing Console Logs

Access the JS Console logs (console.json) under the Logs tab of the Test Details page, or through the REST API by calling the assets endpoint:

curl --compressed -O https://{SAUCE_USERNAME}:{SAUCE_ACCESS_KEY}@{DATA_CENTER}.saucelabs.com/v1/eds/JOB_ID/console.json

HAR Files

HTTP Archive Format (HAR) files collect all network requests and responses made and received by the browser during testing. HAR files offer useful debugging information, such as:

  • Identifying browser requests that time out
  • Pinpointing requests slowing down the loading process
  • Locating faulty API calls

Viewing HAR Files

You need a HAR viewer to read HAR files. Sauce Labs provides a React Network Viewer HAR viewer for your convenience. For step-by-step usage instructions, see our Visualize HAR Files with the New React Network Viewer blog article.

Alternatively, some other commonly used HAR viewers include:

Accessing HAR Files

To download HAR files from Sauce Labs:

  1. Navigate to Live > Test Results.
  2. Select the applicable test.
  3. Click the Metadata tab.

You can also download a HAR file programmatically using the following API request:

curl --compressed -O https://{SAUCE_USERNAME}:{SAUCE_ACCESS_KEY}@{DATA_CENTER}.saucelabs.com/v1/eds/JOB_ID/network.har

Network Logs

Sauce Labs records all network requests made by the open page in the browser during the test. To generate the network logs in your test output, include the following JavaScript Executor command in your test script:

driver.execute('sauce:log', { type: 'sauce:network' }):