Browser Automation and Acceptance Testing with Geb

This post focuses on the technical side of automated acceptance tests for web applications. There are a lot of high-level frameworks, that allow definition of acceptance tests in natural language (Robot, JBehave, Cucumber, …). But when it comes to the technical implementation of the test cases, you are often forced to use the rather low-level WebDriver API directly.

Geb addresses exactly this problem. It is an abstraction of the WebDriver API and combines the expressive and concise Groovy language with a jQuery-like selection and traversal API. This makes the test implementation easier and the code more readable. On top of that, you get support for the page object pattern, asynchronous content lookup and a very good integration in existing test frameworks.

Quickstart with the Groovy Shell

If you want to start playing around with Geb immediately, just open up a Groovy Shell (normally via groovysh) and type in the following lines. Of course, you can also save these lines to a file and execute it with groovy. But for trying out new things, I think the Groovy Shell is a good starting point.

1import groovy.grape.Grape
2Grape.grab(group:"org.gebish", module:"geb-core", version:"0.9.0-RC-1")
3Grape.grab(group:"org.seleniumhq.selenium", module:"selenium-firefox-driver", version:"2.28.0")
4import geb.Browser
5 
6browser = new Browser() 
7 
8// the duckduckgo website has a much cleaner structure than google
9// that makes it a better choice for demonstrating browser automation
10browser.go "https://duckduckgo.com/"

After loading the necessary libraries with Grape, a new Browser instance is created. At this point, nothing else happens. When calling the go-method, a firefox opens up and navigates to “http://duckduckgo.com”. In the background Geb searches for available WebDriver implementations. It will find the previously loaded FirefoxDriver and will use it to start a new browser and connect to it. Now we can control the firefox via the Browser instance. For example, we can search for the term “Groovy Browser Automation” and click on the first result.

1// fill the search input field with the searchterm 
2// ".q" is just a shortcut for find("input", name:"q")
3browser.find("#search_form_homepage").q = "Groovy Browser Automation"
4 
5// click the button with id "search_button_homepage"
6browser.find("#search_button_homepage").click()
7 
8// click the first "a"-tag below the element with class "links_main" 
9browser.find(".links_main").find("a", 0).click()

In this little example, we already see one of Geb’s core features: the jQuery-like syntax for selecting elements. You can use a great variety of CSS-selectors and attribute-matchers, you can filter the result-set or find descendants. And you can easily iterate over the result-set (like we do in the next example). For more information on element selection and traversal, have a look at Geb’s reference documentation (the “The Book of Geb”). It is not only a complete overview of Geb’s features (including configuration and integration in test frameworks and build systems), but also a good starting point for anybody who wants to learn more about Geb.

When using Geb outside the Groovy Shell, it is probably not very convenient to type “browser” over and over again. Thankfully, Geb offers a shortcut: the drive method accepts a closure, where all method-calls are delegated to the underlying Browser instance. In the next example, we extract the items of the sidemenu from the Geb-Homepage. We also show another handy shortcut: instead of find, we can use $. Those already familiar with jQuery, probably aren’t too surprised by this choice.

1browser.drive({
2    go "http://www.gebish.org/"
3    $(".sidemenu a").each({
4        element -> println element.text()
5    })
6})

You have seen, how easy it is to do browser automation with Geb. In simple scripts, it is enough to create a Browser instance and use its drive method. But Geb is much more than a helper for browser automation scripts. So let’s have look at something more interesting: Testing.

Integration with the Spock Testing Framework

Spock is one of the most popular testing frameworks for the Groovy language. And Geb comes with an excellent integration for Spock. I won’t go through the details of configuring Geb and Spock in a maven (or gradle) project. Detailed instructions, how to do this, can be found in the Book of Geb. I can also recommend the geb-maven-example on GitHub .

The Spock integration of Geb comes with a subclass of Spock’s Specification class. Inside test methods, you have the same possibilities as when using the Browser.drive method. You have access to a Browser instance via the browser property. Geb takes care of configuring and starting the browser before the tests (as well as closing the browser once the tests are finished). Just like inside a drive block, you don’t have to use the browser property. All unknown methods are directly delegated to it. This makes the tests very clean and readable. As an example, the following test makes sure, that the Geb homepage is the first result when searching for “Groovy Browser Automation”.

1import geb.spock.GebSpec
2 
3class SearchSpec extends GebReportingSpec {
4    def "search 'Groovy Browser Automation' in duckduckgo"() {
5        given: "we are on the duckduckgo search-engine"
6            go "http://duckduckgo.com"
7 
8        when: "we search for 'Groovy Browser Automation'"
9            $("#search_form_homepage").q = "Groovy Browser Automation"
10            $("#search_button_homepage").click()
11 
12        then: "the first result is the geb website"
13            assert $("#links").find(".links_main a", 0).attr("href") == "http://www.gebish.org/"            
14    }
15}

By default, Geb searches the classpath for an available WebDriver. This is enough, if you just want to play around. In a real-world-project however, there are more things to consider. In the CI environment you’d want to run the tests in a headless mode (for example using PhantomJS and GhostDriver ). If you’re developing a ROCA application, perhaps you also want to check how your application behaves when JavaScript is disabled. Then HtmlDriver is a possible option. This can be achieved by defining different profiles for Geb. Just place a file GebConfig.groovy inside your classpath and Geb will automatically read profile definitions from there. The profile itself is then determined by the system property geb.build.profile. Take a look at my geb-demo project on GitHub to see profiles in action. The project’s README file also contains detailed instructions, how to execute the tests with maven and how to set up the necessary infrastructure (e.g. a PhantomJS daemon).

Tip: Geb provides yet another base class for spock-tests: GebReportingSpec. The only difference to GebSpec is, that GebReportingSpec automatically takes a screenshot for failed tests. This can be very helpful when you search the reason for failing tests.

The Page Object Pattern

Tests are often treated as second-class citizens. But the same principles, that adhere to production code, can and must be applied to test-code. “Open/Closed” and “DRY” are such principles. And the Page Object Pattern is a means to observe these two. The idea behind page objects is quite simple: Each screen (page) of the web application is represented by an object (page object). Similar pages are represented by objects of the same class. The information and possible user interactions of a page (or a class of pages) are described by the properties and methods of the corresponding page object (or its class).

Geb provides support for the page object pattern via the Page class. The elements and possible actions of a page are described inside the content block using a simple DSL. To illustrate how this works, we take the movie database application of Tobias Flohre’s recent blog post on ROCA and write some acceptance tests. The code of the following examples (including maven configuration and README) can be found in my geb-demo project on GitHub .

One can quickly make out candidates for page objects in the movie database: The initial page could be labeled MovieListPage. When you click on a movie, the details to this movie are displayed (MovieDetailPage). And a click on the “Edit” button leads to a simple form to change these details (MovieEditPage). The implementation for the MovieListPage could look like this:

1import geb.Page
2 
3class MovieListPage extends Page {
4    static content = {
5        searchform { $(".form-search") }
6        searchSubmitButton { searchform.find(type: "submit")}
7 
8    // this defines a method "searchFor" that takes a single argument
9    // the search-form is filled with the given argument and the search-button is clicked
10        searchFor { searchTerm ->
11            searchform.searchString = searchTerm
12            searchSubmitButton.click()
13        }
14 
15    // required=false is needed, because otherwise Geb would automatically throw
16        // an AssertionException when the method returns nothing
17        movie(required: false) { movieName -> $("td", text: movieName).parent() }
18        containsMovie(required: false) { movieName ->  movie(movieName).present }
19 
20        movieCount { $("#pageContent tr").size() }
21    }
22}

This definition of the MovieListPage is now the base for tests of the movie database’s search feature. In the following example, we navigate to “http://localhost:8080/moviedatabase”. With the at-method, we tell Geb, that the current screen should be represented by an instance of MovieListPage. After doing so, the Browser automatically delegates all unknown method calls to this object. And because GebSpec delegates all calls to the underlying Browser instance, we can directly call any method of the MovieListPage (e.g. the searchFor method to execute a search). At the end of the test, you can see one of Geb’s other nice features: asynchronous content lookup. Because the search result is loaded via ajax, there is no full page reload. So we tell Geb to wait up to 5 seconds (the default timeout) for the search result to show up. If the movie list doesn’t contain “Star Wars” after 5 seconds, the test fails.

1class SearchSpec extends GebSpec {
2    def "search for 'star' contains movie 'Star Wars'"() {
3        given: "we are on the movie database homepage"
4            go "http://localhost:8080/moviedatabase"
5            at MovieListPage
6 
7        when: "we search for 'star'"
8            searchFor("star")
9            at MovieListPage
10 
11        then: "the search result contains 'Star Wars'"
12            // the waitFor is needed because the movie-database uses javascript
13            // heavily and the click on the searchbutton doesnt trigger a page-reload
14            waitFor { containsMovie("Star Wars") }
15    }
16 
17    def "search for 'foo' returns empty result"() {
18        given: "we are on the movie database homepage":
19            go "http://localhost:8080/moviedatabase"
20            at MovieListPage
21 
22        when: "we search for 'star'"
23            searchFor("foo")
24            at MovieListPage
25 
26        then: "the search result is empty"
27            waitFor { movieCount() == 0 }
28    }
29}

Conclusion

Geb is not only a very nice DSL for browser automation, it has also many powerful features. Most notably the jQuery-like selection API and the support for the Page Object Pattern. Another highlight is the asynchronous content lookup. There is support for existing test frameworks like Spock, easyb, JUnit and TestNG. Integration for JBehave or cucumber-jvm is also possible with the BindingUpdater. Getting started is easy and the documentation answers questions before they arise. There is no reason why you shouldn’t give it a try 😉