Guidelines for Selenium Scripts

Last modified on August 16, 2021

When designing Selenium scripts for the AlertSite monitoring platform, follow these guidelines for the best results.

Standalone Runnable JAR

AlertSite supports Selenium scripts written in Java and compiled into JAR files. Your compiled JAR file must be runnable, that is, can be run using this command:

java -jar filename.jar

IDEs, like Eclipse, have an option to create runnable JARs (see our tutorial). Technically, a runnable JAR contains the main() method and the manifest file that specifies the main method’s class.

Additionally, the JAR file must contain the Selenium libraries and any other dependencies embedded in it. This way, AlertSite is not locked to a specific Selenium version, plus, you can use any third-party libraries you want. If you use Eclipse IDE, it has the option to pack all required JARs into the resulting JAR.

Script Length

The script should ideally include a single, atomic test case, or transaction. A script that opens 20 pages and does many different things is not really useful.

Length Limit

There is no limit on the JAR file size or the number of test cases (@Test methods) in the Java code. However, Selenium scripts are subject to the transaction step limit on your AlertSite plan. A step is counted for every web page opened by the Selenium script. Most AlertSite Enterprise plans have a limit of 50 steps per transaction.

The entire script has a time limit of 10 minutes. If the run time exceeds this limit, the script will be stopped with AlertSite status 81 “Maximum transaction time was exceeded”.

Exit Code

The main() method in your Java code must return exit code 0 on success and exit code > 0 on error. AlertSite will set the monitor status (OK or error) depending on this exit code.


public static void main(String[] args) {
  // ...

  if (everythingWasOK) {
  }   else {

Check the main() code in our tutorial for a complete example.

Path to ChromeDriver or geckodriver

To use ChromeDriver or geckodriver, include the driver location in your PATH environment variable.

If you prefer to set the driver location in your code by using system properties ( or webdriver.gecko.driver), use the following code:


if (System.getProperty("") == null) {
  System.setProperty("", "/path/to/chromedriver");

This way, AlertSite will be able to use its own driver path.

Successful Local Playback

Your Selenium script should be:

  • played back successfully in Selenium IDE before you move to Eclipse,
  • played back successfully in Eclipse after the AlertSite code is added.

Only then it is ready to be used for monitoring.

Clicking UI Elements

To improve the stability of clicking UI elements, ensure that the element is visible before the click. A typical sequence of actions is:

  1. Explicitly wait for the element presence in the DOM.

  2. Scroll the element into view.

  3. Make sure that the element is clickable.

  4. Perform the click.

That is, instead of:



use something like this:


WebDriverWait wait = new WebDriverWait(driver, 3); // explicit wait timeout, in seconds

// Wait for the element presence in DOM
WebElement element = wait.until(ExpectedConditions.presenceOfElement("element_ID"));
// Scroll the element into view
(new Actions(driver)).moveToElement(element).perform();
// Make sure the element is clickable

Waiting for Pages

Your Selenium script should ensure that each page loads properly. This is needed for AlertSite to measure page loading time properly, and is especially important for dynamic pages that load additional content via Ajax.

A common approach is to explicitly wait for a specific element to exist on the page.


// Some actions that cause a new page to load
// ...

// Ensure the new page is loaded - by checking for the presence of "element_ID"
WebDriverWait wait = new WebDriverWait(driver, 10);

You should use this or a similar approach for each page in the script, including the last page.

Browser Window Size

The default browser window size at AlertSite monitoring locations is 1280×1024. If your Selenium script requires a larger browser window, configure your script to launch the browser with the desired window size. For example:


driver = new FirefoxDriver();
driver.manage().window().setPosition(new Point(0,0));
driver.manage().window().setSize(new Dimension(1600, 1200));

See Also

Website Monitoring With Selenium and AlertSite
Create Runnable JAR From Selenium Script Using Eclipse
Selenium Monitors

Highlight search results