| id | debug |
|---|---|
| title | Using Extended Debugging |
| sidebar_label | Debugging |
| description | Collect extended debugging data to help audit flaky test results. |
import useBaseUrl from '@docusaurus/useBaseUrl'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
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. :::
- 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) as the test browser
:::caution Chrome and OS Compatibility Check the Platform Configurator to verify your selected operating system supports the latest three versions of Chrome; otherwise, you might run into issues when using Extended Debugging. :::
:::caution 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.
:::
To generate the JS console logs and HAR files, add the extendedDebugging capability to your test capabilities and set it to true.
const capabilities = {
browserName: 'chrome',
browserVersion: 'latest',
platformName: 'Windows 11',
'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.
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.
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.
Configure sauce:intercept to redirect an outgoing request to an alternate URL.
url |
| REQUIRED | STRING | An outgoing request URL. Wildcards are supported, for example |
redirect |
| REQUIRED | STRING | An absolute URL to where the original request is redirected. The code samples use |
<Tabs groupId="lang" defaultValue="python" values={[ {"label":"Python","value":"python"}, {"label":"WebdriverIO","value":"wdio"} ]}>
driver.execute_script('sauce:intercept', {
"url": "https://saucelabs.com",
"redirect": "https://google.com"
})browser.interceptRequest({
url: 'https://saucelabs.com/',
redirect: 'https://google.com'
})Configure sauce:intercept to return the specified response.
url |
| REQUIRED | STRING | An outgoing request URL. Wildcards are supported, for example |
response |
| REQUIRED | STRING | An object that defines the response to send when the requested URL is intercepted. Valid attributes of the response are:
|
<Tabs groupId="lang" defaultValue="python" values={[ {"label":"Python","value":"python"}, {"label":"WebdriverIO","value":"wdio"} ]}>
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'
}
]
}
})Configure sauce:intercept to return the specified error.
url |
| REQUIRED | STRING | An outgoing request URL. Wildcards are supported, for example |
error |
| REQUIRED | STRING | A valid error status to return when the requested URL is intercepted. Valid values are:
|
<Tabs groupId="lang" defaultValue="python" values={[ {"label":"Python","value":"python"}, {"label":"WebdriverIO","value":"wdio"} ]}>
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'
})Use the JavascriptExecutor throttle commands to simulate different connectivity conditions that may affect the performance of your app.
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.
rate |
| REQUIRED | STRING | A number defining the amount of slowdown (e.g., |
<Tabs groupId="lang" defaultValue="python" values={[ {"label":"Python","value":"python"}, {"label":"WebdriverIO","value":"wdio"} ]}>
driver.execute_script('sauce:throttleCPU', {
"rate": 4
})browser.throttleCPU(4)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).
condition |
| REQUIRED | STRING | A string or object representing browser network conditions. Sauce Labs supports the following predefined network profiles:
Alternatively, you can define an object specifying individual parameters for each of the three network values, as shown in the code examples:
|
<Tabs groupId="lang" defaultValue="python" values={[ {"label":"Python","value":"python"}, {"label":"WebdriverIO","value":"wdio"} ]}>
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
})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:
{
"https://webdriver.io/docs/api/element/click":[
{
"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"
}
]
}
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
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
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
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
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' }):