Arquillian Graphene 2.0 - Functional Testing with Elegance

Since we wrote this post we didn't laze around. Check our latest announcement.

The Arquillian team is proud to announce the 2.0.0.Final release of the Graphene component!

It’s already been a year since we announced the first alpha release of Graphene 2. Back then the Selenium project had undergone huge changes adopting the WebDriver API. We were excited to explore the new waters to make sure web applications are as easy to test as writing simple unit tests.

We quickly established some objectives for the project which evolved to what we can call Graphene 2.0 today:

  • built on top of WebDriver,
  • encourage to use/create reusable test abstractions,
  • simplify testing of AJAX pages.
  • fast development turnaround,

and last but not least, we wanted to make sure people could use the same features that were part of Graphene 1. Now, one and half year after the Graphene 1.0.0.Final release, we can finally report that we were able to rope in all of the concepts anticipated back then. During this journey we’ve basically touched all APIs and adopted all of the features while leveraging the modern WebDriver API for browser automation.

Graphene now consists of more than 700 commits from 11 code contributors – and that fact leads me to another aspect:

We would like to thank everyone who have been involved with the project so far; early adopters, issue reporters, people who improved documentation and of course people who picked up a ball and contributed to the code. You all hardened the project to the shape it is now.

Thank you, you guys rock!

How Graphene compares to WebDriver?

It’s important to say that Graphene is not just another dialect for WebDriver as we fully support the original WebDriver Java API. Instead, we add sensitive API extensions which we do believe altogether improves the experience and emphasizes ease of use – the common requirement for mass adoption.

We take the best of WebDriver such as

  • wide browser support,
  • object-oriented API,
  • testing design patterns such as Page Objects,

and we push them to the next level.

Graphene, together with its buddy Drone, are truly helpful for developers to lower the effort needed to build a reliable, robust and maintainable functional test suite. And we of course integrates seamlessly into the whole Arquillian test platform.

If you were to ask me; “whether you should just use the plain WebDriver API, or leverage Graphene?” the answer would be: you can continue using just WebDriver as you do today, and use as much or as little of Graphene as you see fit. Graphene just makes a few things a lot easier for you. The decision of which API to use can be compared to the decision you make when buying a new car – Should you buy a car with air-condition? Well, it certainly makes the ride a lot more pleasurable.

So, what’s so cool about Graphene?

Let’s go through some of the most prominent features:

Best Practices: Page Abstractions

As with WebDriver you can use Page Abstractions in the form of Page Objects. In Graphene we’ve made Page Abstractions a first class citizen, combined with dependency injection into the Arquillian test cases.

Graphene adds to this the concept of Page Fragments, which allows you to make even better abstractions. Page Fragments are so brilliant that e.g. the RichFaces project plan to offer fragments for testing their own widgets, in order to make your life super-easy.

public class UserDetailsPage {

    @FindBy(css = “.ui-timepicker”)
    private TimePicker birthday;

    public void setBirthDay(DateTime date) {

public void TestCase {

    private UserDetailsPage userDetails;

    public void when_user_changes_birthday_then_admin_will_be_notified() {
        DateTime birthday = new Birthday(2012, 05, 04);

Testing AJAX

Another area where Graphene excels is testing AJAX applications. In fact, Graphene doesn’t consider the WebElement as a concrete element on the target page, but rather as a proxy (or promise) for the real element that might be.

You no longer need to make sure the element you point to is not stale, since the proxy will make sure to bind to the most recent element for the given locator. This allows us to inject all Page Objects and their members using dependency injection during the start phase of the test. Members are then dereferenced as they are used.

Another useful feature is the Fluent Waiting API, which aims to better the readability of the test code.

Even more interesting is the use of Request Guards, which allow you to add synchronization points in your test logic when dealing with AJAX communication.

private WebElement confirmButton;

@FindByJQuery(“body div.modal”)
private ModalPanel modalPanel;

// waits until a popup is opened

// blocks until AJAX (XMLHttpRequest) communication is done

Dependency Injection

Graphene is capable of providing injection of objects such as:

  • WebDriver context
  • interesting objects from WebDriver API e.g. JavascriptExecutor
  • elements using FindBy

into test objects such as:

  • Arquillian test case (class)
  • Page Objects
  • Page Fragments
  • WebElement wrappers, for example Select
private WebDriver driver;

private TakesScreenshot screenshotter;

You can find a complete list of resources available for injection in the Reference Documentation.

You can find a complete list of features in the Reference Documentation.

Learning Graphene

If you’re new to functional testing, I recommend you start by reading Functional Testing using Drone and Graphene which will guide you from the first build setup; through packaging parts of your application as a testable deployment and how to write your first test using Arquillian Graphene. It will give you an idea of how to structure the tests and give a few tips on how to write tests in a robust way.

Then you should focus on learning the WebDriver API.

If you already know the WebDriver API, I recommend you reading through the Reference Documentation which contain descriptions of all the Graphene features/goodies. Plus a few tips and tricks.

And finally, you can also read up on the JavaDoc.

Support and Compatibility Notes

We proactively test Graphene on Chrome, Firefox, Internet Explorer and PhantomJS, where we run our extensive test suite as part of the automated build. But generally speaking we support anything that Drone supports! We know for instance that Graphene also works on mobile devices such as Android.

From our experience, we also know that Graphene works great for testing web frameworks like JSF, GWT, AngularJS and generally it should work with any other web framework.

We hope that you’ll enjoy this new release and we look forward to your feedback on the community forum.
If you find any problems, have a new feature request, want some help spreading the word or want to show us a success story blog post, please don’t hesitate to contact us on the forum. All requests are welcome!

What is Arquillian?

Arquillian is open source software that empowers you to test JVM-based applications more effectively. Created to defend the software galaxy from bugs, Arquillian brings your test to the runtime so you can focus on testing your application's behavior rather than managing the runtime. Using Arquillian, you can develop a comprehensive suite of tests from the convenience of your IDE and run them in any IDE, build tool or continuous integration environment.

Release details

Component Graphene
Version 2.0.0.Final view tag
Release date 2013-10-11
Released by Lukas Fryc
Compiled against

Published artifacts org.jboss.arquillian.graphene

  • org.jboss.arquillian.graphene » graphene-parent pom
  • org.jboss.arquillian.graphene » graphene-webdriver pom
  • org.jboss.arquillian.graphene » arquillian-graphene pom
  • org.jboss.arquillian.graphene » graphene-webdriver-spi jar javadoc pom
  • org.jboss.arquillian.graphene » graphene-webdriver-api jar javadoc pom
  • org.jboss.arquillian.graphene » graphene-webdriver-impl jar javadoc pom

Release notes and resolved issues 10

Final release


Thanks to the following list of contributors: Lukas Fryc