Docs Code Examples

Getting Started With Selenium

Welcome to the exciting world of automated web testing with Selenium!

Our goal for this guide is to help you make the most out of your Selenium investment by:

  • Providing a comprehensive introduction to Selenium
  • Showing you how to configure Selenium
  • Teaching you about and Sauce OnDemand
  • Sharing tips and tricks

What is Selenium?

Selenium is an open-source testing tool that is used to interact with web content inside a real browser.

Let's break this down further:

  • Selenium is an open-source project — This means anyone can inspect or modify the source code for any part of Selenium.
  • which can be used to interact with web content — Within Selenium is a JavaScript library that interacts with your content, making your application believe a real person has clicked a button, filled out a form, or followed a link. Simply put, this library holds the magic of Selenium.
  • inside a real browser — If the magic of Selenium is the JavaScript library, then the power of Selenium is that it runs in a real browser. By sending HTTP commands directly to the server, it is possible to simulate user behavior, but that pales in comparison to being able to actually have the page load (as a user would load it) and interact with it there.

What can Selenium not do?

  • Selenium is not a browser control framework. Selenium can interact with the rendered HTML content of a given web page, but it cannot interact with native browser operations like the "Save As" dialog. Other tools, such as AutoIT, need to be employed in conjunction with Selenium to solve that problem. In short, Selenium can control things in the browser, not of the browser.
  • Most importantly, Selenium is not a testing framework. While it is most often used for and associated with testing, it won't help you write tests. Remember that it interacts with web content inside a real browser rather than test the web content. Selenium will allow you to automate a large portion of your regression testing.
  • Selenium was created by Jason Huggins, co-founder of Sauce Labs, while he was at ThoughtWorks working on their internal expense reporting system. In one part of the application he was working with, there was a devilish Add Row button that caused an array of browser-specific problems. In response, Jason developed Selenium Core, allowing him to interact with web content across multiple real browsers.

    Selenium's entrance to the open source world has attracted a wide audience of developers interested in using it for their own testing needs. It has also attracted a number of people who want to contribute to the project. The development of Selenium is now steered by a team of volunteers from all over the world.

    Selenium includes a few different add-ons, including Selenium Remote Control (RC). It provides native bindings for a number of languages (C#, Java, Perl, PHP, Python, and Ruby) that merge with Selenium Core's ability to control the browser. Also included is a Firefox plugin that wraps Selenium in a record/playback shell. This plugin, the popular Selenium Integrated Development Environment (IDE), allows for quick test development (often by less technical testers) and a rapid prototyping of Selenium RC tests.

    As the adoption of Selenium has increased, so, too, has the need to reduce the time it takes to run tests. Selenium Grid was created to address this issue. With Selenium Grid, tests are farmed out to any number of different node machines to execute in parallel, which leads to quicker test release cycles, but doing it in-house requires costly IT maintence to handle the growing farm. We created Sauce OnDemand to help you lower IT costs while increasing testing speed!

Sauce OnDemand

Sauce OnDemand is a service that allows you to run your Selenium tests in our testing cloud. The IT burden of maintaining all those machines for Selenium Grid goes away and you can focus on writing tests. With Sauce OnDemand, you can:

  • Run the same script against different configurations in parallel
  • Instantly scale your testing efforts
  • Watch your script run in real time
  • Archive the results of a test after using the record function
  • Share the video playback with stakeholders or customers to showcase new functionality

Selenium Locators

Locators are how Selenium identifies and interacts with objects in the browser. Locators generated by Selenium IDE are very specific, and sometimes you'll need to broaden their matching power to accomidate changing pages. This is especially true for dynamically generated content.

Here's a brief rundown of locator basics.

  • Id - A locator that begins with id= will search the page's DOM for the element that corresponds to it. The id according to W3C standards will uniquely identify a single item. However, the page content will still display if there are duplicate copies of an id. The easiest way to ensure non-brittle scripts is to use unique ids across your application that do not change from build-to-build.
  • Name - Some HTML elements can have the name attribute on them. A locator that begins with name= will use that as the index when looking for an element.
  • Identifier - Id and name are the two most common ways of identifying page elements so the default locator is a combination of the two of them. Any time a locator does not have a prefix, it uses the Identifier strategy, which checks by id and then by name.
  • Link - A locator that begins with link= will attempt to find an anchor element with the locator text as the label. The sample script uses the strategy to verify the text of a link once the login is successful. One warning about using Link - it is not i18n safe. If the link content is translated, then the script will need to be modified to reflect the new label.
  • XPath - XPath is possibly the most powerful identifier in the Selenium arsenal. XPath is a W3C standard for identifying elements within an XML-like structure (such as HTML). The XPath produced by Selenium IDE tend to be very specific, and refactoring them to handle dynamically generated content is commonly the first step on the way to robust tests. The prefix for the XPath locator is xpath=, but because it's used so often, a locator that begins with // (XPath for "starting from anywhere in the document") is also interpreted as XPath. It is worth noting that IE does not have native support for XPath, though selectors will work due to a Javascript emulation layer. We recommend using css selectors if you intend to do a lot of IE testing.
  • CSS - Just as powerful as XPath in locating elements is the CSS strategy, which uses the standard CSS syntax. This is often considered an advanced strategy because Selenium IDE does not compute CSS values when recording. But it's also the easiest way to write fast, cross-browser selectors to capture any element on the page. Locators prefixed with css= will use the CSS method and can include standard selectors as well as CSS pseudo classes. See the series on CSS selectors on the Sauce Labs Blog
  • DOM - At its heart, Selenium is a Javascript library that interacts with the DOM. A locator that begins with dom= is treated as a DOM lookup. The root of the locator will always begin with document. so it's possible to omit the prefix when using this locator and still have the desired effect.

There are many options available to you when trying to find a specific item on a large page. By using Selenium IDE to first record your script, much of the work is done for you in that regard. You should, however, get in the habit of looking at all recorded identifiers to see if they are the strong enough to stand up to a changing application. This often takes the form of tightening up the XPath or converting to CSS.

Browser Strings

Part of the reason for exporting scripts out of Selenium IDE is to run them against a different browser than just Firefox. The browser is specified when initially connecting to the Selenium RC server with the format of *browser. There are close to a dozen different browser strings, but the ones used in the majority of cases are:

  • firefox
  • iexplore
  • safari
  • googlechrome
  • opera

The launcher for each of these browsers knows where the default installation for each platform is. When running scripts on a machine that uses non-standard locations for installs, the path to the browser executable can also be included after the browser string, such as firefox c:/my/custom/path/firefox.exe?.

Running Selenium RC scripts on Sauce OnDemand

Because Selenium RC scripts tend to leverage an external framework for their structure, the actual running and results-gathering process is also framework dependent. If you want to use Sauce OnDemand from within a Selenium RC script, there is an extra bit of configuration necessary.

Direct Sauce OnDemand Integration

The best way to run tests against Sauce OnDemand is to go directly to the Sauce Labs servers. In order to do this, two changes need to be made to the script.

  • Selenium RC scripts need to connect to a Selenium RC server in order to launch and control a browser. Normally this would be either localhost or another machine on your local network. For OnDemand, that server URL will be port 80.
  • Where you normally provide the browser string to the server, a JSON string will instead be sent with your username, access key, and browser information. This is the minimum JSON that needs to be sent.
              '{"username": "your username here",
                "access-key": "your access key here",
                "os": "Linux",
                "browser": "firefox",
                "browser-version": "3."}'

Here is the same JUnit script from before, configured to run directly against Sauce OnDemand.

    package com.example.tests;

    import com.thoughtworks.selenium.*;
    import org.junit.After;
    import org.junit.Before;
    import org.junit.Test;
    import java.util.regex.Pattern;

    public class demo_login extends SeleneseTestCase {
        public void setUp() throws Exception {
            selenium = new DefaultSelenium("localhost",
                        '{"username": "your username here",
                          "access-key": "your access key here",
                          "os": "Linux",
                          "browser": "firefox",
                          "browser-version": "3."}',

        public void testDemo_login() throws Exception {
            assertEquals("Login - Sauce Labs", selenium.getTitle());
            selenium.type("username", "XXX");
            selenium.type("password", "XXX");
            verifyEquals("Generate a new access key",
              selenium.getText("link=Generate a new access key"));

        public void tearDown() throws Exception {

A mature suite of Selenium RC scripts will take a long time to run. Traditional Unit Tests are fast since they involve no disk or network access. Selenium, on the other hand, has that overhead in addition to the browser to contend with. Parallelization of test execution across machines is required to bring those times down.

Exactly how to run scripts in parallel is dependent on the test framework being used and beyond the scope of this Quick Start Guide, but the configuration of the components and integration with OnDemand remains the same.