CL-Selenium is a client for the Selenium Remote Control server. The instructions here assume that you have downloaded and installed the Selenium Remote Control.


CL-Selenium is ASDF installable. Follow the directions for installing any ASDF installable Common Lisp package.


Start the Selenium Remote Control. The default port is 4444.

java -jar ~/selenium-remote-control-0.8.1/server/selenium-server.jar 

Load the CL-Selenium system into your Lisp implementation.

(asdf:oos 'asdf:load-op :selenium)

CL-Selenium works by parsing the Selenium iedoc.xml at compile time. The iedoc.xml is an XML representation of the Selenium API. Other language bindings typically use an XSLT with iedoc.xml to produce source implementing the API.

Because Lisp is wonderful, CL-Selenium is able to parse the XML at compile time and generate the Lisp code on the fly. If you are looking in the source for CL-Selenium and cannot find the various Selenium API functions, this is why.

CL-Selenium is bundled with a recent version of the iedoc.xml so that it may work without the user needing to obtain the iedoc.xml.

Let's test Google Search using CL-Selenium. In this test we will navigate the browser to Google Search, enter "Hello, World!" into the search text input and click the search button.

SELENIUM> (with-selenium-session (*selenium-session* "*opera" "")
            (do-open "")
            (do-type "q" "hello world")
            (do-click "btnG")
            (do-wait-for-page-to-load "5000")
            (string= (do-get-title) "hello world - Google Search"))

The above example assumes the default Selenium RC driver URL. You should customize SELENIUM:*SELENIUM-DRIVER-URL* if you have departed from the Selenium RC defaults.

Error Handling

There are two types of errors that are signaled by Cl-Selenium: HTTP errors and execution errors. HTTP errors occur when there is a HTTP protocol-level error between CL-Selenium and the Selenium RC driver.

Execution errors are occur when there are application level errors. For example:

SELENIUM> (with-selenium-session (*selenium-session* "*opera" "")
            (do-open "")
            (do-type "q" "hello world")
            (handler-case (do-click "FOOBAR")
              (execution-error (cond) (princ cond)))
Selenium execution error:  Element FOOBAR not found