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.

W3C
JSONWP

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

const capabilities = {
  browserName: 'chrome',
  version: 'latest',
  platform: 'Windows 10',
  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

Python
WebdriverIO

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

browser.interceptRequest({
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

Python
WebdriverIO

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"
            }]
        }
    })

browser.interceptRequest({
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

Python
WebdriverIO

driver.execute_script("sauce:intercept", {
    "url": "https://saucecon.com/wp-content/uploads/2017/07/SauceCon-hero-img-100-2.jpg",
    "error": "Failed"})

browser.interceptRequest({
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

Python
WebdriverIO

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

browser.throttleCPU(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:

Profile	Download Speed (kb/s)	Upload Speed (kb/s)	Round Trip Time (ms)
`offline`	0	0	0
`GPRS`	50	20	500
`Regular 2G`	250	50	300
`Good 2G`	450	150	150
`Regular 3G`	750	250	100
`Good 3G`	1Mb/s	750	40
`Regular 4G`	4Mb/s	3Mb/s	20
`DSL`	2Mb/s	1Mb/s	5
`WiFi`	30Mb/s	15Mb/s	2
`online`	No Restrictions	No Restrictions	No 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

Python
WebdriverIO

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

browser.throttleNetwork('GPRS')
// or
browser.throttleNetwork({
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:

Chrome devtools builtin HAR imports
Google Admin Toolbox HAR Analyzer
Software is Hard blog HTTP Archive Viewer

Accessing HAR Files

To download HAR files from Sauce Labs:

Navigate to Live > Test Results.
Select the applicable test.
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' }):

What You'll Need​

Enabling Extended Debugging​

Edit Your Firefox Profile​

Using the JavaScript Executor to Simulate Network Conditions​

Intercept Network Requests​

sauce:intercept + redirect​

Command Parameters​

Examples​

sauce:intercept + response​

Command Parameters​

Examples​

sauce:intercept + error​

Command Parameters​

Examples​

Throttle Conditions​

sauce:throttleCPU​

Command Parameters​

Examples​

sauce:throttleNetwork​

Command Parameters​

Examples​

JavaScript (JS) Console Logs​

Accessing Console Logs​

HAR Files​

Viewing HAR Files​

Accessing HAR Files​

Network Logs​

What You'll Need

Enabling Extended Debugging

Edit Your Firefox Profile

Using the JavaScript Executor to Simulate Network Conditions

Intercept Network Requests

`sauce:intercept` + redirect

Command Parameters

Examples

`sauce:intercept` + response

Command Parameters

Examples

`sauce:intercept` + error

Command Parameters

Examples

Throttle Conditions

`sauce:throttleCPU`

Command Parameters

Examples

`sauce:throttleNetwork`

Command Parameters

Examples

JavaScript (JS) Console Logs

Accessing Console Logs

HAR Files

Viewing HAR Files

Accessing HAR Files

Network Logs