The Book Of Geb

Geb builds on the WebDriver browser automation library, which means that Geb can work with any browser that WebDriver can. While Geb provides an extra layer of convenience and productivity, it is always possible to “drop down” to the WebDriver level to do something directly should you need to.

For more information see the manual section on using a driver implementation.

The Page Object Pattern gives us a common sense way to model content in a reusable and maintainable way. From the WebDriver wiki page on the Page Object Pattern:

Furthermore (from the same document):

The Page Object Pattern is an important technique, and Geb provides first class support via its page and module constructs.

The jQuery JavaScript library provides an excellent API for (among other things) selecting or targeting content on a page and traversing through and around content. Geb takes a lot of inspiration from this.

In Geb, content is selected through the $ function, which returns a Navigator object. A Navigator object is in someways analogous to the jQuery data type in jQuery in that it represents one or more targeted elements on the page.

Let’s see some examples:

These methods return Navigator objects that can be used to further refine the content.

This is just the beginning of what is possible with the Navigator API. See the chapter on the navigator for more details.

Let’s have a look at a simple case of going to Geb’s home page and navigating to the latest version of this manual.

Geb itself is a available as a single geb-core jar from the central Maven repository. To get up and running you simply need this jar, a WebDriver driver implementation and the selenium-support jar.

Via @Grab…

Via Maven…

Via Gradle…

Alternatively, if using an integration such as geb-spock or geb-junit4 you can depend on that instead of geb-core. You can check out the listing of all artifacts in org.gebish group to see what’s available.

The Browser class features a static method, drive(), that makes Geb scripting a little more convenient.

Which is equivalent to:

The drive() method takes all of the arguments that the Browser constructor takes (i.e. none, a Configuration and/or property overrides) or an existing browser instance, and a closure. The closure is evaluated against created browser instance (i.e. the browser is made the delegate of the closure). The net result is that all top level method calls and property accesses are implied to be against the browser.

The drive() method always returns the browser object that was used, so if you need to quit the browser after the drive session you can do something like…

Browser instances hold a reference to a page. This page instance is retrievable via the page property. Initially, all browser instances have a page of type Page which provides the basic navigation functions and is the superclass for all page objects.

However, the page property is rarely accessed directly. The browser object will forward any method calls or property read/writes that it can’t handle to the current page instance.

The page is providing the $() function, not the browser. This forwarding facilitates very concise code, void of unnecessary noise.

When using the Page Object pattern, you create subclasses of Page that define content via a powerful DSL that allows you to refer to content by meaningful names instead of tag names or CSS expressions.

Page objects are discussed in depth in the Pages chapter, which also explores the Content DSL.

Pages define an “at checker” that the browser uses for checking if it is pointing at a given page.

The to() method that takes a single page type or instance verifies that the browser ends up at the given page. If the request may initiate a redirect and take the browser to a different page you should use via() method:

Browser objects have <T extends Page> T at(Class<T> pageType) and <T extends Page> T at(T page) methods that test whether or not the browser is currently at the page modeled by the given page class or instance.

The at AccessDeniedPage method call return a page instance if the “at checker” is fulfilled. If on the other hand it is not then an AssertionError will be thrown even if there are no explicit assertions in the “at checker” (the default, see the section on Implicit assertions for details) or return null if implicit assertions are disabled.

It’s always a good idea to either use the to() method which implicitly verifies the “at checker” or the via() method followed by an at() check whenever the page changes in order to fail fast. Otherwise, subsequent steps may fail in harder to diagnose ways due to the content not matching what is expected and content look-ups returning strange results.

If you pass a page class or instance that doesn’t define an “at checker” to at() you will get an UndefinedAtCheckerException - “at checkers” are mandatory when doing explicit “at checks”. By default this is not the case when implicit “at checks” are being performed, like when using to(), but it’s configurable. This behaviour is intended to make you aware that you probably want to define an “at checker” when explicitly verifying if you’re at a given page but not forcing you to do so when using implicit “at checking”.

The at() method will also update the browser’s page instance if the “at checker” is successful. This means that you don’t have to manually set browser’s page to the new one after “at checking”.

Pages can also define content that declares what the browser’s page type should change to when that content is clicked. After clicking on such content the declared page is automatically ”at checked” if it defines an “at checker” (see the content DSL reference for the to parameter).

It is possible to be notified when a browser’s page instance changes (note that this is not necessarily when the browser makes a request to a new URL) using the PageChangeListener interface.

As soon as a listener is registered, its pageWillChange() method will be called with newPage as the current page and oldPage as null. Subsequently, each time the page changes oldPage will be the page that the browser currently has, and newPage will be the page that will soon be the browser’s page.

You can remove a listener at any time…

The removePageChangeListener(PageChangeListener listener) returns true if listener was registered and has now been removed, otherwise it returns false.

Listeners cannot be registered twice. If an attempt is made to register a listener that is already registered (i.e. there is another listener that is equal to the listener being registered, based on their equals() implementation) then a PageChangeListenerAlreadyRegisteredException will be raised.

When you’re working with an application that opens new windows or tabs, for example when clicking on a link with a target attribute set, you can use withWindow() and withNewWindow() methods to execute code in the context of other windows.

If you really need to know the name of the current window or all the names of open windows use Browser.getCurrentWindow() and Browser.getAvailableWindows() methods but withWindow() and withNewWindow() are the preferred methods when it comes to dealing with multiple windows.

It often proves useful to be able to pause the execution of code using Geb at some given point for debugging purposes. This can be achieved by either:

While the former is more powerful in that it allows to inspect variable values in the JVM as well as use Geb’s classes and methods where the breakpoint was set, the latter might be easier and quicker to setup and just being able to open developer console in the browser and inspect DOM and javascript variables in there is often sufficient to resolve the issue being debugged.

Local storage can be accessed using localStorage property and session storage using sessionStorage property of a Browser instance. Both of them can be used to read and write values to the underlying storage as if they were a map. Following is an example of setting and reading a value form local storage:

Both localStorage and sessionStorage properties are of geb.webstorage.WebStorage type - please refer to its javadoc for information about other operations that are supported apart from reading and writing values.

The browser object has quit() and close() methods (that simply delegate to the underlying driver). See the section on driver management for more information on when and why you need to quit the browser.

One option for specifying the driver implementation is to construct the driver instance and pass it to the Browser to be used when it is constructed.

However, where possible prefer implicit driver management which is discussed later in this chapter.

When the driver is constructed by the user, the user is responsible for quitting the driver at the appropriate time. This can be done via the methods on the WebDriver instance (obtainable via getDriver()) or by calling the delegating methods on the browser object.

If a driver is not given when a Browser object is constructed, one will be created and managed implicitly by Geb by the configuration mechanism.

By default, Geb internally caches and reuses the first driver created, meaning that all subsequent browser instances created without an explicit driver will reuse the cached driver. This avoids the overhead of creating a new driver each time, which can be significant when working with a real browser.

This means that you may need to call the clearCookies() or clearCookies(String…​ additionalUrls) as well as clearWebStorage() methods on the browser in order not to get strange results due to state carried on from previous executions.

The shared driver will be closed and quited when the JVM shuts down.

A new driver can be forced at anytime by calling either of CachingDriverFactory.clearCache() or CachingDriverFactory.clearCacheAndQuitDriver() both of which are static. After calling any of these methods, the next request for a default driver will result in a new driver instance being created.

This caching behavior is configurable.

This section details various quirks or issues that have been encountered with different driver implementations.

The default behaviour of the HTMLUnit driver is to immediately refresh the page as soon as it encounters a <meta http-equiv="refresh" content="5"> regardless of the specified time. The solution is to use a refresh handler that handles the refresh asynchronously.

See this mailing list thread for details.

HTMLUnit can be very noisy, and it’s not clear how to make it not so noisy.

See this issue for some tips on how to tune its logging.

The $() function is the access point to the browser’s page content. It returns a Navigator object that is roughly analogous to a jQuery object. It is analogous in that it represents one or more elements on the page and can be used to refine the matched content or query the matched content. When a $() function is called that does not match any content, an “empty” navigator object is returned that represents no content. Operations on “empty” navigators return null or another “empty” navigator or other values that make sense (e.g. the size() method returns 0).

The signature of the $() function is as follows…

The following is a concrete example…

This would find the 3rd (elements are 0 indexed) h1 element whose class attribute is exactly “heading”.

All arguments are optional, meaning the following calls are all valid:

Navigator objects have find() and $() methods for finding descendants, and filter() and not() methods for reducing the matched content.

Consider the following HTML…

We can select p.b by…

We can select div.b by…

or…

We can select the div containing the p with…

Or select the div containing the input with a type attribute of "text" like so…

We can select the div that does not contain the p with…

Or select the div that does not contain the input with a type attribute of "text" like so…

Or select the two div that do not contain input with a type attribute of "submit" like so…

The find() and $() methods support the exact same argument types as the $() function.

The filter(), not(), has() and hasNot() methods have the same signatures - they accept: a selector string, a predicates map or both.

These methods return a new navigator object that represents the new content.

It is also possible to compose navigator objects from other navigator objects, for situations where you can’t express a content set in one query. To do this, simply call the $() function and pass in the navigators to compose.

Consider the following markup…

You can then create a new navigator object that represents both the a and b paragraphs the following way:

An alternative way is to use the add() method of Navigator that takes either a String or a Webdriver’s By selector:

Finally, you can compose navigator objects from content. So given a page content definition:

You can compose content elements into a navigator in the following way:

Navigators also have methods for selecting content around the matched content.

Consider the following HTML…

You can select content around p.d by…

Consider the following HTML…

The following code will select p.b & p.c…

The previous(), prevAll(), next(), nextAll(), parent(), parents(), closest(), siblings() and children() methods can also take CSS selectors and attribute matchers.

Using the same html, the following examples will select p.c…

Likewise, consider the following HTML…

The following examples will select div.b…

The closest() method is a special case in that it will select the first ancestor of the current elements that matches a selector. There is no no-argument version of the closest() method. For example, these will select div.a…

These methods do not take indexes as they automatically select the first matching content. To select multiple elements you can use prevAll(), nextAll() and parents() all of which have no-argument versions and versions that filter by a selector.

The nextUntil(), prevUntil() and parentsUntil() methods return all nodes along the relevant axis until the first one that matches a selector or attributes. Consider the following markup:

The following examples will select div.b and div.c:

Navigator objects implement the click() method, which will instruct the browser to click the sole element the navigator has matched. If that method is called on a multi element Navigator then a SingleElementNavigatorOnlyMethodException is thrown.

There are also click(Class) , click(Page) and click(List) methods that are analogous to the browser object’s page(Class<? extends Page>), page(Page), and page(Class<? extends Page>[]), page(Page[]) methods respectively. This allow page changes to be specified at the same time as click actions.

For example…

Would click the a.login element, then effectively call browser.page(LoginPage) and verify that the browser is at the expected page.

All of the page classes passed in when using the list variant have to have an “at” checker defined, otherwise an UndefinedAtCheckerException will be thrown.

Navigator objects have a displayed property that indicates whether the element is visible to the user or not. The displayed property of a navigator object that doesn’t match anything is always false.

Geb comes with an easy way for finding the currently focused element in the form of focused() method which returns a Navigator.

It is also possible to verify if a given Navigator object holds the currently focused element using its focused property. Navigator objects that don’t match any elements will return false as the value of focused property and ones that match multiple elements will throw a SingleElementNavigatorOnlyMethodException.

Given the following html…

focused() method and Navigator’s focused property can be used in the following way…

You can obtain the size and location of content on the page. All units are in pixels. The size is available via the height and width properties, while the location is available as the x and y properties which represent the distance from the top left of the page (or parent frame) to the top left point of the content.

All of these properties operate on the sole matched element only and a SingleElementNavigatorOnlyMethodException is thrown if they are accessed on a multi element Navigator.

Consider the following html…

The following conditions are satisfied for it…

To obtain any of the properties for all matched elements, you can use the Groovy spread operator.

The tag(), text() and classes() methods as well as accessing attributes via the @ notation or attr() method return the requested content on the sole matched element. If these methods are called on a multi element Navigator then a SingleElementNavigatorOnlyMethodException is thrown. The classes() method returns a java.util.List of class names sorted alphabetically.

Consider the following HTML…

The following assertions are valid…

To obtain information about all matched content, you use the Groovy spread operator…

Css properties of a single element navigator can be accessed using the css() method. If that method is called on a multi element Navigator then a SingleElementNavigatorOnlyMethodException is thrown.

Consider the following HTML…

You can obtain the value of float css property in the following way…

Given the following html…

You can send keystrokes to the input (and any other content) via the leftShift operator, which is a shortcut for the sendKeys() method of WebDriver.

How content responds to the keystrokes depends on what the content is.

The value of input, select and textarea elements can be retrieved and set with the value method. Calling value() with no arguments will return the String value of the sole element in the Navigator. If that method is called on a multi element Navigator then a SingleElementNavigatorOnlyMethodException is thrown. Calling value(value) will set the current value of all elements in the Navigator. The argument can be of any type and will be coerced to a String if necessary. The exceptions are that when setting a checkbox value the method expects a boolean (or an existing checkbox value or label) and when setting a multiple select the method expects an array or Collection of values.

Interacting with form controls (input, select etc.) is such a common task in web functional testing that Geb provides convenient shortcuts for common functions.

Geb supports the following shortcuts for dealing with form controls.

Consider the following HTML…

The value can be read and written via property notation…

These are literally shortcuts for…

There is also a shortcut for obtaining a navigator based on a control name…

If your content definition (either a page or a module) describes content which is an input, select or textarea, you can access and set its value the same way as described above for forms. Given a page and module definitions for the above mentioned HTML:

The following will pass:

As well as:

WebDriver supports interactions that are more complex than simply clicking or typing into items, such as dragging. You can use this API directly when using Geb or use the more Geb friendly interact DSL.

This is valid Geb code, and it works well for a one off script but there are two big issues with this approach. Imagine that you have many tests that involve searching and checking results. The implementation of how to search and how to find the results is going to have to be duplicated in every test, maybe many times per test. As soon as something as trivial as the name of the search field changes you have to update a lot of code. The Page Object Pattern allows us to apply the same principles of modularity, reuse and encapsulation that we use in other aspects of programming to avoid such issues in browser automation code.

Here is the same script, utilising page objects…

You have now encapsulated, in a reusable fashion, information about each page and how to interact with it. As anyone who has tried to knows, maintaining a large suite of functional web tests for a changing application can become an expensive and frustrating process. Geb’s support for the Page Object pattern addresses this problem.

All page objects must inherit from Page.

Geb features a DSL for defining page content in a templated fashion, which allows very concise yet flexible page definitions. Pages define a static closure property called content that describes the page content.

Consider the following HTML…

We could define this content as so…

The structure to the content DSL is…

Where «definition» is Groovy code that is evaluated against the instance of the page.

Here is how it could be used…

So how is this working? First, remember that the Browser instance delegates any method calls or property accesses that it doesn’t know about to the current page instance. So the above code is the same as…

Secondly, defined content becomes available as properties and methods on instance of the page…

The Content DSL actually defines content templates. This is best illustrated by example…

There are no restrictions on what arguments can be passed to content templates.

A content template can return anything. Typically they will return a Navigator object through the use of the $() function, but it can be anything.

It’s important to realise that «definition» code is evaluated against the page instance. This allows code like the following…

And this is not restricted to other content…

Or…

Each page can define a way to check whether the underlying browser is at the page that the page class actually represents. This is done via a static at closure…

This closure can either return a false value or throw an AssertionError (via the assert method). The verifyAt() method call will either:

Considering the example above you could use it like this…

The verifyAt() method is used by the Browser.at() method that takes a page class or instance. It behaves the same as verifyAt() if the “at” checker fails and returns a page instance if the checker succeeds (which is useful if you wish to write strongly typed code with Geb)…

At checkers are subject to “implicit assertions”. See the section on implicit assertions for more information.

If you don’t wish to get an exception when “at” checking fails there are methods that return false in that case: Page#verifyAtSafely() and Browser#isAt(Class<? extends Page>).

As mentioned previously, when a content template defines a to option of more than one page the page’s verifyAt() method is used to determine which one of the pages to use. In this situation, any AssertionError thrown by “at” checkers are suppressed.

The “at” checker is evaluated against the page instance, and can access defined content or any other variables or methods…

If a page does not have an “at” checker, the verifyAt() and at() methods will throw an UndefinedAtCheckerException. The same will happen if any of the pages in the list used as to content template option doesn’t define an “at” checker.

It can sometimes prove useful to wrap “at” verification in waitFor() calls by default - some drivers are known to return control after URL change before the page is fully loaded in some circumstances or before one might consider it to be loaded. This behaviour can be required using atCheckWaiting configuration entry.

Pages can define URLs via the static url property.

The url is used when using the browser to() method.

See the section on the base url for notes about URLs and slashes.

Page classes can customise how they generate URLs when used in conjunction with the browser to() method.

Consider the following example…

The to() method can also take arguments…

Any arguments passed to the to() method after the page class are converted to a URL path by calling toString() on each argument and joining them with “/”.

However, this is extensible. You can specify how a set of arguments is converted to a URL path to be added to the page URL. This is done by overriding the convertToPath() method. The Page implementation of this method looks like this…

You can either overwrite this catchall method to control path conversion for all invocations or provide an overloaded version for a specific type signature. Consider the following…

Browser methods like to(), via(), at() and page() accept not only page classes but page instances as well. This is useful for example when parameterizing pages to use property values in “at” checkers:

Pages can be arranged in an inheritance hierarchy. The content definitions are merged…

If a subclass defines a content template with the same name as a content template defined in a superclass, the subclass version replaces the version from the superclass.

Page classes can optionally implement methods that are called when the page is set as the browser’s current page and when it is swapped out for another page. This can be used to transfer state between pages.

Frames might seem a thing of the past, but if you’re accessing or testing some legacy application with Geb, you might still need to deal with them. Thankfully, Geb makes working with them groovier thanks to the withFrame() method which is available on Browser, Page and Module instances.

Modules can be localised to a specific section of the page that they are used in, or they can specify an absolute context as part of their definition. There are two ways that a modules base/context can be defined.

Module can be based on a Navigator instance…

It can also be done outside of a content definition…

We can define a Navigator context when including the module using the above syntax. This now means that calls to all Navigator (e.g. $()) method calls that occur within the module are against the given context (in this case, the form element).

However, module classes can also define their own base…

Basing a module on a Navigator and defining a base in a module can be combined. Consider the following HTML…

And the following content definitions…

Then they can be used in the following way…

If the module declares a base, it is always calculated relative to the Navigator used in the initialization statement. If the initialization statement does not use a Navigator, the module’s base is calculated relative to the document root.

Modules always have a base navigator associated with them (if you don’t specify a base for a module at all then it will be assigned the root element of the document as the base) so it is natural to think of them as navigators. Keeping in mind that Module implements Navigator and considering the following HTML…

As well as these content definitions…

The following will pass…

It’s also possible to use Navigator methods inside of a module implementation…

As previously stated, modules can be used to model page fragments that are reused across multiple pages. For example, many different types of pages in your application may show information about the user’s shopping cart. You could handle this with modules…

Modules work well for this.

Other than content that is repeated on different pages (like the shopping cart mentioned above), pages also can have content that is repeated on the page itself. On a checkout page, the contents of the shopping cart could be summarized with the product name, the quantity and price for each product contained. For this kind of page, a list of modules can be collected using the moduleList() methods of Navigator.

Consider the following HTML for our cart contents:

We can model one line of the table like this:

And define a list of CartRows in our Page:

Because the return value of cartItems is a list of CartRow instances, we can use any of the usual collection methods:

We can also access the cart items using subscript operator together with an index or a range of indexes:

Keep in mind that you can use parametrized module instances to create lists of modules for repeating content:

The Content DSL used for modules is exactly the same as the one used for pages, so all of the same options and techniques can be used.

Modules can use inheritance in the same way that pages can. That is, their content definitions are merged with any content redefined in the subclass taking precedence of the superclass.

If you are using Geb in a strongly typed manner you might consider using the provided modules modelling form controls instead of manipulating them directly using the Navigator API. This will result in longer content definitions but using them will be easier because you won’t have to remember what is the meaning of value() calls for different types of controls. This is for example the case when manipulating checkboxes for which checking and unchecking is achieved by passing booleans to value() when interacting with them via Navigator API.

For the sake of better error reporting, current implementation wraps any module declared within content block into geb.content.TemplateDerivedPageContent instance.

Given a page defined as follows:

And a custom module:

A module assignment to a variable of its declared type will fail with GroovyCastException:

An invocation of a method which takes a module as argument with its declared type will fail with MissingMethodException:

As you may like or need to use strong typing for modules there is a way to do that. Module can be cast to its declared type with the Groovy as operator:

What’s the trade-off? Calling toString() on any content element, including module, gives a meaningful path like:

Such paths can be seen in error messages and this is exactly what you are going to give away for unwrapped modules.

The Configuration object also has setters for all of the config properties it exposes, allowing you to override config properties at runtime in particular circumstances if you need to.

For example, you may have one Spock spec that requires the autoClearCookies property to be disabled. You could disable it for just this spec by doing something like…

Let’s take the “at checker” case.

Consider the following small Geb script…

At checking works by verifying that the page’s “at check” returns a trueish value. If it does, the at() method returns true. If not, the at() method will return false. However, due to implicit assertions, the “at check” will never return false. Instead, the at checker will throw an AssertionError. Because the page’s “at check” is turned into an assertion, you’ll see the following in the stacktrace:

As you can see, this is much more informative than the at() method simply returning false.

Another place where implicit assertions are utilised is for waiting.

Consider the following Geb script:

The waitFor method verifies that the given clause returns a trueish value within a certain timeframe. Because of implicit assertions, when this fails you’ll see the following in the stacktrace:

The failed assertion is carried as the cause of the geb.waiting.WaitTimeoutException and gives you an informative message as to why the waiting failed.

The “implicit assertions” feature is implemented as a Groovy compile time transformation, which literally turns all expressions in a candidate block of code into assertions.

This transform is packaged as a separate JAR named geb-implicit-assertions. This JAR needs to be on the compilation classpath of your Geb test/pages/modules (and any other code that you want to use implicit assertions) in order for this feature to work.

If you are obtaining Geb via a dependency management system, this is typically not something you need to be concerned about as it will happen automatically. Geb is distributed via the Maven Central repository in Apache Maven format (i.e. via POM files). The main Geb module, geb-core depends on the geb-implicit-assertions module as a compile dependency.

If your dependency management system inherits transitive compile dependencies (i.e. also makes compile dependencies of first class compile dependencies first class compile dependencies) then you will automatically have the geb-implicit-assertions module as a compile dependency and everything will work fine (Maven, Gradle and most configurations of Ivy do this). If your dependency management system does not do this, or if you are manually managing the geb-core dependency, be sure to include the geb-implicit-assertions dependency as a compile dependency.

The browser instance exposes a “js” object that provides support for working with JavaScript over and above what WebDriver provides. It’s important to understand how WebDriver does handle JavaScript, which is through a driver’s implementation of JavascriptExecutor.executeScript() method.

You can execute JavaScript like you would with straight WebDriver using the driver instance via the browser…

This is a bit long winded, and as you would expect Geb uses the dynamism of Groovy to make life easier.

Geb provides some convenient methods for waiting for a certain condition to be true. This is useful for testing pages using AJAX, timers or effects.

The waitFor methods are provided by the WaitingSupport mixin which delegates to the Wait class (see the documentation of the waitFor() method of this class for the precise semantics of waiting). These methods take various parameters that determine how long to wait for the given closure to return a true object according to the {`}[Groovy Truth], and how long to wait in between invoking the closure again.

Apart from the generic waiting support Geb also comes with a convenience method which reloads the page each time before the block passed to it is evaluated.

The method is available on Page class and is called refreshWaitFor() and it is the same as the waitFor() method with regards to everything else than the page reloading behaviour. This means that you can pass the same arguments to it as to waitFor(), the block passed to it is implicitly asserted and it supports custom messages.

The following example shows waiting for a static timestamp of when the page was rendered to be at least three hundred milliseconds after the test has started:

WebDriver currently does not handle the alert() and confirm() dialog windows. However, we can fake it through some JavaScript magic as discussed on the WebDriver issue for this. Geb implements a workaround based on this solution for you. Note that this feature relies on making changes to the browser’s window DOM object so may not work on all browsers on all platforms. At the time when WebDriver adds support for this functionality the underlying implementation of the following methods will change to use that which will presumably be more robust. Geb adds this functionality through the AlertAndConfirmSupport class that is mixed into Page and Module.

The Geb methods prevent the browser from actually displaying the dialog, which is a good thing. This prevents the browser blocking while the dialog is displayed and causing your test to hang indefinitely.

Geb has special support for jQuery. Navigator objects have a special adapter that makes calling jQuery methods against the underlying DOM elements simple. This is best explained by example.

Consider the following page:

We want to click the Geb link, but can’t because it’s hidden (WebDriver does not let you interact with hidden elements). The div containing the link (div “a”) is only displayed when the mouse moves over div “a”.

The jQuery library provides convenient methods for triggering browser events. We can use this to simulate the mouse being moved over the div “a”.

In straight jQuery JavaScript we would do…

Which we could invoke via Geb easy enough…

That will work, but can be inconvenient as it duplicates content definitions in our Geb pages. Geb’s jQuery integration allows you to use your defined content in Geb with jQuery. Here is how we could call the mouseover jQuery function on an element from Geb…

To be clear, that is Groovy (not JavaScript code). It can be used with pages…

The jquery property of a navigator is conceptually equivalent to a jQuery object for all of the navigator’s matched page elements.

The methods can also take arguments…

The same set of restricted types as allowed by WebDriver’s JavascriptExecutor.executeScript() method are permitted here.

The return value of methods called on the jquery property depends on what the corresponding jQuery method returns. A jQuery object will be converted to a Navigator representing the same set of elements, other values such as objects, strings and numbers are returned as per WebDriver’s JavascriptExecutor.executeScript() method.

For example, let’s say you are using Geb to exercise a web application that generates PDF documents. The WebDriver API can only deal with HTML documents. You want to hit the PDF download link and also do some tests on the downloaded PDF. The direct download API is there to fill this need.

Simple enough, but consider what is happening behind the scenes. Our application required us to log in, which implies some kind of session state. Geb is using HttpURLConnection to get the content and before doing so the cookies from the real browser are being transferred onto the connection allowing it to reuse the same session. The PDF download link href may also be relative, and Geb handles this by resolving the link passed to the download function against the browser’s current page URL.

The Direct Download API can also be used for making fine grained requests which can be useful for testing edge cases or abnormal behavior.

All of the download*() methods take an optional closure that can configure the HttpURLConnection that will be used to make the request (after the Cookie header has been set).

For example, we could test what happens when we send application/json in the Accept header.

When facing web applications using untrusted (e.g. self-signed) SSL certificates, you will likely get exceptions when trying to use Geb’s download API. By overriding the behavior of the request you can get around this kind of problem. Using the following code will allow running requests against a server which uses a certificate from the given keystore:

In the configuration, the default behaviour of the HttpURLConnection object can be specified by providing a closure as the defaultDownloadConfig property.

The below example configures all requests executed using direct downloading support to carry a User-Agent header.

This config closure will be run first, so anything set here can be overridden using the fine grained request configuration shown above.

As previously mentioned, the direct download API uses java.net.HttpURLConnection for performing http requests. This means that it can be configured to use a proxy in the exact same way as java.net.HttpURLConnection, that is by setting http.proxyHost and http.proxyPort system properties

Any I/O type errors that occur during a download operation (e.g. HTTP 500 responses) will result in a DownloadException being thrown that wraps the original exception and provides access to the HttpURLConnection used to make the request.

To use the binding support, you simply create a BindingUpdater object with a Binding and Browser…

If you wish to configure the reporting to also write reports which contain the source content of page frames you can do so the following way:

By default, reports are only taken for the window which is set to be the current browser window at the time of taking a report. It’s also possible to take reports for each of the opened windows by configuring the reporting to use MultiWindowReporter:

The configuration mechanism allows you to specify the base reportsDir which is where reports are written to by default. It is also possible to change the report group to a relative path inside this directory.

We have now created the following files inside the reportsDir…

The browser will create the directory for the report group as needed. By default, the report group is not set which means that reports are written to the base of the reportsDir. To go back to this after setting a report group, simply call reportGroup(null).

It is possible to register a listener on the reporter that gets notified when a report is taken. This was added to make it possible to write something to stdout when a report is taken, which is how the Jenkins JUnit Attachments Plugin makes it possible to associate arbitrary files to test execution. Reporting listeners are of type ReportingListener can be specified as part of the config…

Geb does not automatically clean the reports dir for you. It does however provide a method that you can call to do this.

The cleanReportGroupDir() method will remove whatever the reports group dir is set to at the time. If it cannot do this it will throw an exception.

The Spock, JUnit and TestNG integrations work fundamentally the same way. They provide subclasses that setup a Browser instance that all method calls and property accesses/references resolve against via Groovy’s methodMissing and propertyMissing mechanism.

Consider the following Spock spec…

Which is equivalent to…

It is possible to both:

For both SauceLabs and BrowserStack, a special driver factory is provided that, given a browser specification as well as an username and access key, creates an instance of RemoteWebDriver configured to use a browser in the cloud. Examples of typical usage in GebConfig.groovy are included below. They will configure Geb to run in SauceLabs/BrowserStack if the appropriate system property is set, and if not it will use whatever driver that is configured. This is useful if you want to run the code in a local browser for development. In theory you could use any system property to pass the browser specification but geb.saucelabs.browser/geb.browserstack.browser are also used by the Geb Gradle plugins, so it’s a good idea to stick with those property names.

The first parameter passed to the create() method is a ”browser specification“ and it should be a list of required browser capabilities in Java properties file format:

Assuming you’re using the following snippet in your GebConfig.groovy to execute your code via SauceLabs with Firefox 19 on Linux, you would set the geb.saucelabs.browser system property to:

and to execute it with IE 9 on Vista to:

Some browsers like Chrome automatically update to the latest version; for these browsers you don’t need to specify the version as there’s only one, and you would use something like:

as the ”browser specification“. For a full list of available browsers, versions and operating systems refer to your cloud provider’s documentation:

Please note that Geb Gradle plugins can set the geb.saucelabs.browser/geb.browserstack.browser system properties for you using the aforementioned format.

Following the browser specification are the username and access key used to identify your account with the cloud provider. The example uses two environment variables to access this information. This is usually the easiest way of passing something secret to your build in open CI services like drone.io or Travis CI if your code is public, but you can use other mechanisms if desired.

You can optionally pass additional configuration settings by providing a Map to the create() method as the last parameter. The configuration options available are described in your cloud provider’s documentation:

Finally, there is also an overloaded version of create() method available that doesn’t take a string specification and allows you to simply specify all the required capabilities using a map. This method might be useful if you just want to use the factory, but don’t need the build level parametrization.

For both SauceLabs and BrowserStack, Geb provides a Gradle plugin which simplifies declaring the account and browsers that are desired, as well as configuring a tunnel to allow the cloud provider to access local applications. These plugins allow easily creating multiple Test tasks that will have the appropriate geb.PROVIDER.browser property set (where PROVIDER is either saucelabs or browserstack). The value of that property can be then passed in configuration file to SauceLabsDriverFactory/BrowserStackDriverFactory as the ”browser specification“. Examples of typical usage are included below.

Using Geb with Gradle simply involves pulling in the appropriate dependencies, and configuring the base URL and reports dir in the build script if they are necessary.

Below is a valid Gradle build.gradle file for working with Geb for testing.

There is a Gradle example project available.

Using Geb with Maven simply involves pulling in the appropriate dependencies, and configuring the base URL and reports dir in the build script if they are necessary.

Below is a valid pom.xml file for working with Geb for testing (with Spock).

There is a Maven example project available.

Geb scripts can be executed in an IDE if that IDE supports executing Groovy scripts. All IDEs that support Groovy typically support this. There are typically only two concerns in the configuration of this: getting the Geb classes on the classpath, and the GebConfig.groovy file.

Geb tests can be executed in an IDE if that IDE supports Groovy scripts and the testing framework that you are using with Geb. If you are using JUnit or Spock (which is based on JUnit) this is trivial, as all modern Java IDEs support JUnit. As far as the IDE is concerned, the Geb test is simply a JUnit test and no special support is required. As with executing scripts, the IDE must put the Geb classes on the classpath for test execution and the GebConfig.groovy file must be accessible (typically putting this file at the root of the test source tree is sufficient).

In both cases, the simplest way to create such an IDE configuration is to use a build tool (such as Gradle or Maven) that supports IDE integration. This will take care of the classpath setup and other concerns.

This section discusses what kind of authoring assistance can be provided by IDEs and usage patterns that enable better authoring support.