Browser API

The entry-point into any clj-webdriver application involves "starting up" a browser. After that, you can perform various browser-level actions like going to a new URL, refreshing the page, or quitting. For more information about interacting with individual page elements, read the Element API section of the wiki.

Starting a Browser

Starting a browser means two things: an actual web browser is opened (Firefox, Chrome, etc.) and clj-webdriver returns a Driver record that controls it. In your Clojure code, you obviously want to keep a reference to that Driver record to use the rest of the clj-webdriver API. (Terminology Note: I have tried to limit my use of the word "browser" below to instances referring to the actual GUI browser application, and use the word "driver" when referring to the Clojure datastructure that gives you access to that browser via clj-webdriver's API).

To start a browser, you can use one of two functions, as follows:

(def driver (new-driver :firefox))

(def driver (start :firefox "http://example.com"))

The start function calls new-driver and immediately points the driver at a URL, instead of the default blank page.

(Related topics: The new-driver function is the entry point for initializing the Driver cache; see Caching Support for more details. These functions also have equivalents for dealing with the Grid, which you can read about on the Grid Support page.)

Driver Actions

Once you've started your driver, there are a number of things you can do it with before interacting with the actual page.

Basics

The following functions are defined in the IDriver protocol, which encapsulates what I've termed "browser basics":

Navigation:

• get-url - Point driver at a new URL
• to - Synonym for get-url
• back - Go back in the driver's history
• forward - Go forward in the driver's history
• refresh - Refresh the page currently loaded in the driver

Driver Information:

• current-url - Return driver's current URL
• title - Return driver's current title
• page-source - Return source code of the currently loaded page

Screenshots:

• get-screenshot - Return a screenshot as a :file, :bytes or :base64, optionally saving to a permanent file if a destination is given

Closing/Quitting:

• close - Close the current browser window (does not quit the browser if multiple windows are open)
• quit - Quit the browser application (closes all open windows)

Finding Things

The heart of clj-webdriver's API is the find-it function. This function wraps the various ways that Selenium-WebDriver allows you to find elements and condenses them into a handful of "mini languages" for finding elements on the page, hopefully in a more Clojure-amenable fashion. Since this is the initial way people start playing with this API, I will continue to maintain the most up-to-date information about it on the README:

README

Waiting

The protocol IWait provides two functions that allow you to determine how long or under what conditions the driver should "wait" while looking for elements on the page:

• implicit-wait - Set a global wait time that the driver will wait before throwing an exception
• wait-until - Make the driver wait a certain maximum amount of time for a given predicate to evaluate to true

The first is implicit-wait. This function accepts a numeric value which represents the number of milliseconds the driver should wait on all pages when testing for the presence of page elements. This comes in handy when you repeatedly wait for portions of webpages to load via AJAX, and the only variable in your test execution is the length of time it takes to load those portions.

The second function is wait-until. Unlike implicit-wait, which affects the driver for the duration of its life, the wait-until function is meant for one-off situations where you require the Driver to wait. It accepts both a predicate, which must eventually evaluate to true, and a timeout maximum, to cap wait-until at a certain number of milliseconds before throwing an exception.

Window Handling

The protocol ITargetLocator provides functionality for handling multiple open windows. Windows are uniquely identified by "handles," which live in the Clojure code as WindowHandle records.

• window-handle - Return handle for currently-active window
• window-handles - Return a seq of window handles for all open browser windows
• other-window-handles - Return a seq of window handles that does not include the currently-active window
• switch-to-window - Make the window handle passed into this function the new currently-active one
• switch-to-other-window - Iff two windows are open, switch to the other

Cookie Handling

The protocol IOptions manages cookie handling (thus called to be consistent with Selenium-WebDriver's API).

• add-cookie - Add a new cookie to the driver session
• cookies - Return a seq of cookies in the current driver session
• cookie-named - Return a cookie given its name
• delete-cookie - Delete a cookie
• delete-cookie-named - Delete a cookie, given only its name
• delete-all-cookies - Delete all cookies in the current driver session