Skip to main content

BROWSERSTACK_IDLE_TIMEOUT

Learn how to resolve the BROWSERSTACK_IDLE_TIMEOUT error.

Issue

When you run a test using BrowserStack Automate, the following error might appear on the Issues Detected tab on the Automate dashboard:

BROWSERSTACK_IDLE_TIMEOUT has occurred

Cause

In BrowserStack, a test session receives it, runs it, and expects another command to arrive. If a test session does not receive the next test command after running the earlier command, it waits for a maximum of 90 seconds, which is the default timeout duration.

If another command does not arrive at BrowserStack within the default timeout duration of 90 seconds, the session generates the BROWSERSTACK_IDLE_TIMEOUT error on the Automate dashboard.

After generating the error, the session stops and is marked as Timed Out on the Automate dashboard.

Why you must mitigate this issue

As an organization, optimizing your builds to run faster is crucial. BrowserStack understands this issue has a significant impact on the speed and stability of your test sessions.

We recommend resolving these issues to:

  • Ensure the test script works correctly by handing any possible exceptions if you’ve encountered this error due to unhandled exceptions.
  • Improve the build time of your parallel test session since a device gets free as soon as you terminate a test session in BrowserStack.

Resolution/Workaround

Try the following resolutions to resolve the BROWSERSTACK_IDLE_TIMEOUT error:

Add driver.quit command in test script

BrowserStack Selenium Grid, by default, does not know when your test scripts have completed running. Hence your test script must send information about test completion to the BrowserStack Selenium Grid. Add the following driver.quit command at the end of your test script, or in the after hook of your language framework, to let the BrowserStack Selenium Grid know about test completion.

driver.quit();
driver.quit();
driver.Quit();
$driver->quit();
driver.quit()
driver.quit
$driver->quit();

Sometimes, you might see the BROWSERSTACK_IDLE_TIMEOUT error even after adding driver.quit in your test script. In such a case, your test script might have encountered an unhandled exception. This exception prevents the test flow from reaching the driver.quit command, resulting in a timeout error. Check out the handle exceptions section to learn about exception handling.

Increase timeout duration

There are situations when a command of your test script performs tasks that are independent of BrowserStack. Such tasks may include making an API request, querying a database, etc. In such a case, if a task takes more than 90 seconds to complete, your test session in BrowserStack gives the BROWSERSTACK_IDLE_TIMEOUT error.

To avoid getting the BROWSERSTACK_IDLE_TIMEOUT error, you can increase the default idle timeout duration up to a maximum of 300 seconds using the browserstack.idleTimeout capability in a test script.

Use the following sample code snippets to set the browserstack.idleTimeout capability in your test script:

If you are using BrowserStack SDK, you can set the following capabilities in the browserstack.yml file:

browserstack.yml
Copy icon Copy snippet

BrowserStack SDK is a plug-n-play solution that takes care of all the integration steps for you. Using the BrowserStack SDK is the recommended integration method for your project. To know more, visit the SDK core concepts page.

DesiredCapabilities caps = new DesiredCapabilities();

// set the timeout to a maximum of 300 seconds
caps.setCapability("browserstack.idleTimeout", "<time_in_seconds>");
var capabilities = {
  // set the timeout to a maximum of 300 seconds
 "browserstack.idleTimeout" : "<time_in_seconds>"
}
// For Chrome browser
OpenQA.Selenium.Chrome.ChromeOptions chromeCapability = new OpenQA.Selenium.Chrome.ChromeOptions();
// set the timeout to a maximum of 300 seconds
capability.AddAdditionalCapability("browserstack.idleTimeout", "<time_in_seconds>", true);

// For Edge browser
OpenQA.Selenium.Edge.EdgeOptions edgecapability = new OpenQA.Selenium.Edge.EdgeOptions();
// set the timeout to a maximum of 300 seconds
capability.AddAdditionalCapability("browserstack.idleTimeout", "<time_in_seconds>");

// For IE browser
OpenQA.Selenium.IE.InternetExplorerOptions ieCapability = new OpenQA.Selenium.IE.InternetExplorerOptions();
// set the timeout to a maximum of 300 seconds
capability.AddAdditionalCapability("browserstack.idleTimeout", "<time_in_seconds>", true);

// For Firefox browser
OpenQA.Selenium.Firefox.FirefoxOptions firefoxCapability = new OpenQA.Selenium.Firefox.FirefoxOptions();
// set the timeout to a maximum of 300 seconds
capability.AddAdditionalCapability("browserstack.idleTimeout", "<time_in_seconds>", true);

// For Safari browser
OpenQA.Selenium.Safari.SafariOptions safariCapability = new OpenQA.Selenium.Safari.SafariOptions();
// set the timeout to a maximum of 300 seconds
safariCapability.AddAdditionalCapability("browserstack.idleTimeout", "<time_in_seconds>");
$caps = array(
  // set the timeout to a maximum of 300 seconds
 "browserstack.idleTimeout" => "<time_in_seconds>"
);
capabilities = {
  # set the timeout to a maximum of 300 seconds
 "browserstack.idleTimeout": "<time_in_seconds>"
}
caps = Selenium::WebDriver::Remote::Capabilities.new
# set the timeout to a maximum of 300 seconds
caps["browserstack.idleTimeout"] = "<time_in_seconds>"
my $capabilities = {
  # set the timeout to a maximum of 300 seconds
  "browserstack.idleTimeout" => "<time_in_seconds>"
}

Handle exceptions

When your test script encounters an exception in the test flow, it might never reach the driver.quit command in your test script.

Some of the common causes for the exceptions to occur are:

  • Unable to locate an element on a webpage
  • Elements are not interactable or clickable
  • Page or its elements did not load within a particular duration, etc.

The recommended way to handle exceptions is to use a try...catch block in your test scripts. As a best practice, add your code statements in a try block, and add the logic to handle any exceptions in the catch block of your test script.

Adding the try...catch block ensures that irrespective of whether the test script encounters an error or not, the driver.quit command is executed to avoid the BROWSERSTACK_IDLE_TIMEOUT error.

The following tab shows a sample Java test script that handles exceptions both with and without using a try...catch block.

The following test script searches for an element to click, which does not exist on the web page. Since this test script has implemented exception handling by using a try...catch block, it stops running and terminates a session in BrowserStack.

import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.remote.DesiredCapabilities;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;
public class Sample {
public static final String AUTOMATE_USERNAME = "YOUR_USERNAME";
public static final String AUTOMATE_ACCESS_KEY = "YOUR_ACCESS_KEY";
public static final String URL = "https://" + AUTOMATE_USERNAME + ":" + AUTOMATE_ACCESS_KEY + "@hub-cloud.browserstack.com/wd/hub";
public static void main(String[] args) throws Exception {
 DesiredCapabilities caps = new DesiredCapabilities();
 caps.setCapability("os_version", "10");
 caps.setCapability("resolution", "1920x1080");
 caps.setCapability("browser", "Chrome");
 caps.setCapability("browser_version", "latest");
 caps.setCapability("os", "Windows");
 caps.setCapability("name", "Sample Java test using Try block"); // test name
 caps.setCapability("build", "BStack Build Number 1"); // CI/CD job or build name
 final WebDriver driver = new RemoteWebDriver(new URL(URL), caps);
 try {
   // go to bstackdemo.com
   driver.get("https://bstackdemo.com/");
   // click a button
   driver.findElement(By.xpath("//*[@id=\'1\']/div[")).click();
   } catch (Exception e) {
     // print any exception
     System.out.println(e);
     }
    // quit the driver
   driver.quit();
 }
}

The following test script searches for an element to click, which does not exist on the web page. Since this test script has not implemented exception handling, it keeps waiting for next command and eventually gives BROWSERSTACK_IDLE_TIMEOUT error after default timeout of 90 seconds.

import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.remote.DesiredCapabilities;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;
public class Sample {
public static final String AUTOMATE_USERNAME = "YOUR_USERNAME";
public static final String AUTOMATE_ACCESS_KEY = "YOUR_ACCESS_KEY";
public static final String URL = "https://" + AUTOMATE_USERNAME + ":" + AUTOMATE_ACCESS_KEY + "@hub-cloud.browserstack.com/wd/hub";
public static void main(String[] args) throws Exception {
 DesiredCapabilities caps = new DesiredCapabilities();
 caps.setCapability("os_version", "10");
 caps.setCapability("resolution", "1920x1080");
 caps.setCapability("browser", "Chrome");
 caps.setCapability("browser_version", "latest");
 caps.setCapability("os", "Windows");
 caps.setCapability("name", "Sample Java test without using Try block"); // test name
 caps.setCapability("build", "BStack Build Number 1"); // CI/CD job or build name
 final WebDriver driver = new RemoteWebDriver(new URL(URL), caps);
 // go to bstackdemo.com
 driver.get("https://bstackdemo.com/");
 // click a button
 driver.findElement(By.xpath("//*[@id=\'1\']/div[")).click();
 // quit the driver
 driver.quit();
 }
}

It is recommended to use waits to avoid the test script from encountering any exceptions. Check out the next section to learn about implementing waits in your test script.

Best practice of using Selenium waits to improve test stability

The duration in which an element loads on a web page may vary. A test script that implements the logic for exception handling might still raise an exception and stop running if an element loads after a particular duration.

A session of your test script may or may not encounter an exception depending on availability of an element on the web page. Thus, to eliminate flakiness from your tests, you must use explicit waits.

When you use an explicit wait, the test script waits for a specific duration until an element loads on the web page. An explicit wait minimizes the chances of your test scripts encountering any exception, thus improving the stability of your test sessions.

Avoid using the sleep() method for implementing waits in your test script since it causes flakiness in your tests.

The following sample Java test script implements an explicit wait of 10 seconds to run the test:

Sample.java
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.remote.DesiredCapabilities;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.openqa.selenium.support.ui.WebDriverWait;
import org.openqa.selenium.WebElement;

public class Sample {
  public static final String AUTOMATE_USERNAME = "YOUR_USERNAME";
  public static final String AUTOMATE_ACCESS_KEY = "YOUR_ACCESS_KEY";
  public static final String URL = "https://" + AUTOMATE_USERNAME + ":" + AUTOMATE_ACCESS_KEY + "@hub-cloud.browserstack.com/wd/hub";
  public static void main(String[] args) throws Exception {
    DesiredCapabilities caps = new DesiredCapabilities();
    caps.setCapability("os_version", "10");
    caps.setCapability("resolution", "1920x1080");
    caps.setCapability("browser", "Chrome");
    caps.setCapability("browser_version", "latest");
    caps.setCapability("os", "Windows");
    caps.setCapability("name", "Java code using explicit wait"); // test name
    caps.setCapability("build", "BStack Build Number 1"); // CI/CD job or build name
    final WebDriver driver = new RemoteWebDriver(new URL(URL), caps);

    // define an explicit wait of 10 seconds
    WebDriverWait wait = new WebDriverWait(driver, 10);

    try {
      driver.get("https://bstackdemo.com/");
      // use the Selenium's explicit wait of 10 seconds in the test script that waits until the browser's title is 'StackDemo'
      wait.until(ExpectedConditions.titleIs("StackDemo"));

      // use the Selenium's explicit wait of 10 seconds in the test script that waits until the button is clickable
      WebElement cart_btn = wait.until(ExpectedConditions.elementToBeClickable(By.xpath("//*[@id=\'1\']/div[4]")));

      // click the button
      cart_btn.click();
      } catch (Exception e) {
        System.out.println(e);
        }
      driver.quit();
    }
}

Selenium also provides other types of waits, namely implicit wait and fluent wait, which you can use after careful consideration.

Need some help?

If you need additional help, contact our Support team.

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback

Is this page helping you?

Yes
No

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback!

Talk to an Expert
Download Copy