Arquillian Guides Designed exclusively to teach you how to use Arquillian to write real tests.

Functional Testing using Drone

Edit this file

Authors: Dan Allen, Karel Piwko
Level: More Coverage Tags: drone, selenium, as7, cdi, solder Last Update:Dec 11, 2012

This guide introduces you to the Arquillian Drone extension. After reading this guide, you’ll be able to:

Add the Drone extension to your Arquillian-based test suite to activate Selenium 2
Package portions of your web application to test the web user interface (UI)
Inject the DefaultSelenium API into your test case
Control the browser using Selenium to validate the behavior of your web application

You’ll appreciate how much heavy lifting Arquillian is doing to simplify the task of using Selenium 2 to perform automated functional testing!

Assumptions

We’ll assume that you’ve read the Getting Started guide and have an Arquillian test suite setup in your project. We’ll be adding a simple JSF login form to the project as an example of a web UI to test. From there, you can apply these instructions to any other web pages you may need to test.

The instructions in this guide are specific to a Maven project, though remember that Arquillian is not tied to Maven in any way. We’ll be running the tests on a JBoss AS 7 instance, though you can use any container supported by Arquillian that has a web container.

In this guide, we’ll be using the following technologies:

Arquillian
Arquillian Drone
ShrinkWrap Maven Resolver
Selenium (Selenium Server and DefaultSelenium)

The first three technologies are a part of Arquillian test platform. The final technology, Selenium, automates browsers. Selenium integrates into Arquillian via the Arquillian Drone extension to test the frontend of Java-based web applications.

We’ll be using two parts of Selenium:

Selenium Server is a test tool that allows you to write automated web application UI tests against any HTTP website using any mainstream JavaScript-enabled browser.
DefaultSelenium is the Java client API that you use to control the browser.

If you are already familiar with Selenium, you’ll discover that Arquillian manages the Selenium Server life cycle in much the same way it manages the container life cycle. If Selenium is new to you, this is a great opportunity to begin using it to test the web UI of your application without having to worry about how it’s setup.

Introducing Client Mode

If you’d ever written an Arquillian based test, you know that it looks almost the same as a unit test for the unit testing framework you are using. Let’s look at an example of an Arquillian test that uses JUnit:

@RunWith(Arquillian.class)
public class BasicInContainerTest {
    @Deployment
    public static JavaArchive createDeployment() {
        return ShrinkWrap.create(JavaArchive.class)
            .addClass(MyBean.class)
            .addAsManifestResource(EmptyAsset.INSTANCE, "beans.xml");
    }
    
    @Inject
    MyBean bean;
 
    @Test
    public void should_inject_bean_instance() {
        Assert.assertNotNull(bean);
    }
}

Here we’ve deployed a CDI bean to the server inside a bean archive. In the test, we’ve injected the instance of the bean, then asserted that the injection has occurred. Arquillian first enriches the archive with the test infrastructure. It then connects to the server to deploy the archive and execute the test method inside of the container by launching the JUnit test runner a second time inside that environment. Finally, Arquillian retrieves the results from that remote execution. This example demonstrates the default run mode of Arquillian: in-container. In a sense, the local JUnit runner is a client of the container, being driven by Arquillian.

The other run mode in Arquillian is the client run mode. In this mode, Arquillian deploys the test archive as is to the server. It then allows the tests to run in the same JVM as the test runner. Now your test case is a client of the container. The test no longer runs inside the container, yet Arquillian still handles the life cycle of the container as well as deployment of the test archive. It’s the ideal mode for web UI testing.

Enabling Client Mode

How do you activate client mode? Quite simply. You either mark a deployment as non-testable, meaning Arquillian will not enrich the archive, or you can mark a specified method with the annotation @RunAsClient. Here’s an example:

@RunWith(Arquillian.class)
public class BasicClientTest {
    @Deployment(testable = false)
    public static WebArchive createDeployment() {
        return ShrinkWrap.create(WebArchive.class)
            .addClasses(MyBean.class)
            .setWebXML("WEB-INF/web.xml");
    }
    
    @Test
    public void should_login_successfully() {
    }
}

It’s also possible to mix in-container and client modes in the same test! Just leave off the testable attribute. Any method annotated with @RunAsClient will execute from the client, the remainder will execute inside the container, giving you the best of both worlds!

@RunWith(Arquillian.class)
public class MixedRunModeTest {
    @Deployment
    public static JavaArchive createDeployment() {
        return ShrinkWrap.create(JavaArchive.class)
            .addClass(MyBean.class)
            .addAsManifestResource(EmptyAsset.INSTANCE, "beans.xml");
    }
    
    @Inject
    MyBean bean;
 
    @Test
    public void should_run_in_container() {
        // executed from the server JVM
        Assert.assertNotNull(bean);
    }

    @Test
    @RunAsClient
    public void should_run_as_client() {
        // executed from the client JVM
    }
}

Now that you understand how to run a test in client mode, let’s check out how to test a web UI by using Arquillian to drive Selenium.

Drone Overview

Arquillian Drone is an extension that manages the life cycle of testing browsers for the purpose of simplifying automated functional testing.

Currently, the list of supported browsers is pretty large, a bounded set of those covered by Selenium Server, Selenium Core, Selenium WebDriver and Arquillian Graphene. Like Arquillian Core, the Arquillian Drone extension is, well, pretty extensible. If your favorite browser is not supported, you’ll find it easy to add the support.

Arquillian Drone bootstraps the tooling required for testing browsers in order to work (e.g. Selenium Server), then it creates instances of a testing browser and properly disposes of it after the test is finished. You only have to worry about writing the logic of the test.

Let’s get Arquillian Drone configured so that we can start writing some tests.

Set Up Drone

Let’s start by setting up the libraries in the Maven pom.xml file that we need to use the Drone extension. As with the previous tutorials, we need to instruct Maven which versions of the artifacts to use by importing a BOM, or version matrix. If you followed the getting started guide, you should already have a BOM defined for Arquillian in the <dependencyManagement> section.

pom.xml

<!-- clip -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.jboss.arquillian</groupId>
            <artifactId>arquillian-bom</artifactId>
            <version>1.0.0.Final</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<!-- clip -->

Below that <dependency>, add another entry for defining the version matrix for Drone’s transitive dependencies, leaving you with the following result:

pom.xml

<!-- clip -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.jboss.arquillian</groupId>
            <artifactId>arquillian-bom</artifactId>
            <version>1.0.0.Final</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.jboss.arquillian.extension</groupId>
            <artifactId>arquillian-drone-bom</artifactId>
            <version>1.0.0.Final</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<!-- clip -->

Next, we need to define the Drone dependencies inside the top-level <dependencies> element. If you’ve set up Arquillian previously, you should already have the JUnit and Arquillian JUnit integration dependencies.

pom.xml

<!-- clip -->
<dependencies>
    <dependency>
        <groupId>org.jboss.arquillian.junit</groupId>
        <artifactId>arquillian-junit-container</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <scope>test</scope>
        <version>4.8.1</version>
    </dependency>
</dependencies>
<!-- clip -->

Insert the following group of <dependency> elements below the existing dependencies to add the Drone extension, Selenium adapter and Selenium runtime to your project’s test classpath:

pom.xml

<!-- clip -->
<dependency>
    <groupId>org.jboss.arquillian.extension</groupId>
    <artifactId>arquillian-drone-impl</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.jboss.arquillian.extension</groupId>
    <artifactId>arquillian-drone-selenium</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.jboss.arquillian.extension</groupId>
    <artifactId>arquillian-drone-selenium-server</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-java</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-server</artifactId>
    <scope>test</scope>
    <exclusions>
        <exclusion>
            <groupId>org.mortbay.jetty</groupId>
            <artifactId>servlet-api-2.5</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>1.6.4</version>
    <scope>test</scope>
</dependency> 
<!-- clip -->

Feel free to select the SLF4J implementation of your choosing.

Finally, you have to specify the dependency on container adapter. We’ll use the JBoss AS 7 managed container since it boots extremely fast!

pom.xml

<!-- clip -->
<dependency>
    <groupId>org.jboss.as</groupId>
    <artifactId>jboss-as-arquillian-container-managed</artifactId>
    <version>7.1.1.Final</version>
    <scope>test</scope>
</dependency>
<!-- clip -->

If you are testing against multiple containers, then the container adapter should be included in a dedicated profile, as described in the Getting Started guide.

While the Drone extension appears to require a lot of dependencies, take comfort that this is the only configuration you need to do to use it. Now you’re ready to write your first Arquillian Drone test!

Create a Login Screen

When writing a web UI test, you have to make sure you deploy a complete web application, even if it’s only a fraction of your full application (e.g., a micro application). Therefore, the @Deployment method for these types of tests is going to be a bit more complex, but don’t let it turn you off. Over time, you’ll divide up the deployment into reusable parts to trim down the configuration on a per-test basis.

To create the login screen of the application, we need the following files and resources:

Credentials bean to capture the username and password
User bean to represent the current user
Login controller to authenticate the user and produce the current user
Login page
Home page (landing page after successful login)

If you haven’t done so already, open the project in your IDE. Next, create a Credentials class in the org.arquillian.example package.

src/main/java/org/arquillian/example/Credentials.java

package org.arquillian.example;

import javax.enterprise.inject.Model;

@Model
public class Credentials {
    private String username;
    private String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

Credentials is a request-scoped, named bean (as indicated by the @Model stereotype annotation) to make it capable of capturing data from the JSF login form we are going to create.

Next, create the User class in the same package. In a more advanced example, this class would likely serve as a JPA entity, able to retrieve the user’s information from a database. For now, we’ll stick with a more basic use case.

src/main/java/org/arquillian/example/User.java

package org.arquillian.example;

public class User {
    private String username;

    public User() {}
    
    public User(String username) {
        this.username = username;
    }
    
    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }
}

Next up, create the LoginController class, again in the same package. For the purpose of this example, this implementation only accepts a username and password of “demo” and issues a welcome message when the login is successful.

src/main/java/org/arquillian/example/LoginController.java

package org.arquillian.example;

import java.io.Serializable;

import javax.enterprise.context.SessionScoped;
import javax.enterprise.inject.Produces;
import javax.faces.application.FacesMessage;
import javax.faces.context.FacesContext;
import javax.inject.Inject;
import javax.inject.Named;

@Named
@SessionScoped
public class LoginController implements Serializable {
    private static final long serialVersionUID = 1L;

    private static final String SUCCESS_MESSAGE = "Welcome";
    private static final String FAILURE_MESSAGE =
        "Incorrect username and password combination";

    private User currentUser;
    
    @Inject
    private Credentials credentials;
    
    public String login() {
        if ("demo".equals(credentials.getUsername()) &&
            "demo".equals(credentials.getPassword())) {
            currentUser = new User("demo");
            FacesContext.getCurrentInstance().addMessage(null,
                new FacesMessage(SUCCESS_MESSAGE));
            return "home.xhtml";
        }

        FacesContext.getCurrentInstance().addMessage(null,
            new FacesMessage(FacesMessage.SEVERITY_WARN,
                FAILURE_MESSAGE, FAILURE_MESSAGE));
        return null;
    }
    
    public boolean isLoggedIn() {
        return currentUser != null;
    }
    
    @Produces
    @Named
    public User getCurrentUser() {
        return currentUser;
    }
}

The LoginController is session-scoped so that it can store the current user for the duration of the user’s session and named so that it can be accessed by the action button on the login form.

Finally, we need to create the UI screens. In the src/main/webapp directory, create a login page:

src/main/webapp/login.xhtml

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:f="http://java.sun.com/jsf/core">
    <head>
        <title>Log in</title>
    </head>
    <body>
        <h:messages/>
        <h:form id="loginForm">
            <h:panelGrid columns="2">
                <h:outputLabel for="username">Username:</h:outputLabel>
                <h:inputText id="username" value="#{credentials.username}"/>
                <h:outputLabel for="password">Password:</h:outputLabel>
                <h:inputSecret id="password" value="#{credentials.password}"/>
                <h:commandButton id="login" value="Log in"
                    action="#{loginController.login}"/>
            </h:panelGrid>
        </h:form>
    </body>
</html>

and a home page:

src/main/webapp/home.xhtml

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:f="http://java.sun.com/jsf/core">
    <head>
        <title>Home</title>
    </head>
    <body>
        <h:messages/>
        <h:panelGroup rendered="#{loginController.loggedIn}">
            <p>You are signed in as #{currentUser.username}.</p>
        </h:panelGroup>
    </body>
</html>

Now we need to write a test to see if these components come together to produce a functioning login screen.

Create a Test Archive

Here’s the shell of a test case for testing the logic screen with just the @Deployment method in place. All the files all listed explicitly to illustrate what’s being included.