Testing Web Applications with JBehave, PhantomJS and PageObjects

No Comments

Testing web applications is the one thing that could be really really painful. Nevertheless typically there is no way around it when implementing web applications. Luckily the selected tools and applying best practices can help a lot to improve in this area. And hey, JBehave, PhantomJS and PageObjects already sound that cool that testing web applications this way can only be a piece of cake in the end. Well, almost ;-).


While JBehave and PhantomJS are on the tooling side of this article, PageObjects is a very helpful design approach for testing web applications.

With JBehave the tests as such are implemented in Java and the testcases are specified using Given/When/Then notation. This typically makes the testcases quite readable which helps in the communication between the development team and the subject specialists. Doing the implementation in Java allows the usage of the well known development tools including support for refactoring. Assuming of course that the application itself is implemented in Java as well. Executing tests directly from the IDE during development is definitely a huge advantage here. This is possible with no additional effort and of course due to the Maven-integration of Java the tests can be easily executed on the CI-environment – for example Jenkins – using Maven.

By using PhantomJS the web side of the tests is getting quite lightweight. The tests are executed headless which means that no real browser is started to execute the tests. This makes the tests faster and easier to execute across different environments. Of course this does not help if very specific compatibility issues must be tested for certain browsers, but still then this might be done manually while the majority of tests are automated using PhantomJS. As we will see the integration with JBehave is also working seamlessly.

The concept of PageObjects allows for a very clean design of the test implementation. Basically this is achieved by having one class for each page of the web application that contains all possible interactions with that specific page. Let’s directly jump into the details of this in the following chapter.

Page Objects

Let’s take a look at the following fictitious code-snippet.

page.loginPage().login("user", "password");

Looks pretty nice, doesn’t it? As mentioned beforehand the basic concept of PageObjects is to have a Java class that represents one page of the web application. All actions that can be taken on that page are bundled in that “page-class”. On the one hand side this is a quite natural approach once one thinks about it. On the other hand it right away gives an approach to split the complexity of the test implementation into different classes. This is also depicted in the following figure.

Concept of PageObjects

Concept of PageObjects

One important part of this is to have one central Pages-class that is a kind of proxy to access all the individual “page-classes”. This way there is no need to add all the individual classes to the classes implementing the individual tests. Furthermore this also allows to keep the state of the pages if this is required.

Often it makes sense to have a common abstract superclass for all the “page-classes” that contains – uh, well – common functionality. This could be own implementations to make screenshots or to check for certain page content or whatever.

A “page-class” could then for example look like this.

public class HomePage extends AbstractPage {
    public HomePage(WebDriver webDriver) {
    public void checkContent() {
    public void gotoPortfolioPage() {

The Pages-class does then nothing else than aggregating all the individual “page-classes” as follows.

public class Pages {
    private final WebDriver webDriver;
    private HomePage homePage;
    private PortfolioPage portfolioPage;
    public Pages(WebDriver webDriver) {
        this.webDriver = webDriver;
    public HomePage homePage() {
        if (homePage == null) {
            homePage = new HomePage(webDriver);
        return homePage;
    public PortfolioPage portfolioPage() {
        if (portfolioPage == null) {
            portfolioPage = new PortfolioPage(webDriver);
        return portfolioPage;

The usage of the Pages-class in the JBehave implementation is described in the following chapter. There is also not much more to say about PageObjects. So let’s continue with JBehave.


Scenarios and Scenario-Implementation

A good starting point to get a general overview on the JBehave concepts could be our previous article on JBehave and its configuration features.

The following figure gives an overview on how tests are implemented using JBehave. The implementation part is on the left-hand side with the Scenario- and Step-classes. While writing the stories in Given/When/Then notation could be done by subject experts in close cooperation with the development team.

JBehave Scenarios

JBehave Scenarios

Whenever Given/When/Then notation is used one has to write that tests can then be written by the subject experts. But trust me, I have never seen a project where this has really worked, but still it is probably the best notation currently available … and one can still hope :-).

Let’s take a look at our fictitious test scenario for the homepage. This would be stored under src/main/resources/codecentric/scenarios/homepage/homepage_menu_scenarios.story.

This is just a very simple example for a JBehave scenario. 
In a real project some more precise information could be put 
here to give a context for the test scenarios.
The following scenarios are testing the Main Menu Entries of the 

Scenario: Check Main Menu Entry Portfolio
Given I opened the codecentric homepage
When I clicked on Portfolio 
Then I see the Portfolio page

Scenario: Check Main Menu Entry Career 
Given I opened the codecentric homepage
When I clicked on Career 
Then I see the Career page

As already mentioned, there must be a Scenario-class for each kind of scenario. In this case a HomepageMenuScenarios.java under src/main/java/codecentric/scenarios/homepage. Scenario-classes are typically very easy to write as they are not containing any real test-implementation but they are building the frame to execute the tests.

package codecentric.scenario.homepage;
import codecentric.common.CommonScenario;
import codecentric.step.homepage.MainMenuSteps;
import org.jbehave.core.steps.InjectableStepsFactory;
import org.jbehave.core.steps.InstanceStepsFactory;
import org.junit.Test;
public class HomepageMenuScenarios extends CommonScenario {
    public InjectableStepsFactory stepsFactory() {
        return new InstanceStepsFactory(configuration(), 
            new MainMenuSteps(pages), new PortfolioSteps(pages));

If you looked carefully at the above code for sure you have noticed that we are using a base class here called CommonScenario. This is the place where for example the configuration is defined and also the Pages-object is instantiated. But let’s have another look at the code above. The given method basically defines which step classes are accessible. What a step-class is will be shown a bit later, but basically that is where the real testing-code is implemented. You can add as many step-classes to the stepsFactory-method as needed. Most of the time that will probably be only that step-class required for the given scenarios, but sometimes you need additional step-classes. You will notice when the time comes. Let’s take a look at the CommonScenario-class.

package dairynet.common;
import codecentric.pages.Pages;
import de.codecentric.jbehave.junit.monitoring.JUnitReportingRunner;
import org.jbehave.core.Embeddable;
import org.jbehave.core.configuration.Configuration;
import org.jbehave.core.embedder.Embedder;
import org.jbehave.core.junit.JUnitStory;
import org.jbehave.core.reporters.Format;
import org.jbehave.core.reporters.StoryReporterBuilder;
import org.jbehave.web.selenium.*;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.phantomjs.PhantomJSDriver;
import org.openqa.selenium.phantomjs.PhantomJSDriverService;
import org.openqa.selenium.remote.DesiredCapabilities;
import java.util.Arrays;
public abstract class CommonWebScenario extends JUnitStory {
    private SeleniumContext context = new SeleniumContext();
    private ContextView contextView = new LocalFrameContextView().sized(500, 100);
    private WebDriver webDriver = null;
    protected Pages pages = null;
    public Configuration configuration() {
        DesiredCapabilities caps = new DesiredCapabilities();
	webDriver = new PhantomJSDriver(caps);
	pages = new Pages(webDriver);
	Class<? extends Embeddable> embeddableClass = this.getClass();
        Configuration configuration = new SeleniumConfiguration()
            .useStoryLoader(new LoadFromClasspath(embeddableClass))
            .useStoryReporterBuilder(new StoryReporterBuilder()
                .withFormats(Format.HTML, Format.STATS, Format.CONSOLE));
        return configuration;
    public Embedder configuredEmbedder() {
        final Embedder embedder = super.configuredEmbedder();
        return embedder;
    public void run() throws Throwable {

Here we see our first interaction with PhantomJS. The rest is kind of boilerplate code for JBehave to be able to run stories from Maven and also as JUnit tests directly from the used IDE. If you are interested in more details on configuring JBehave-scenarios, I would again point out one of our previous blog posts.

Steps and Step-Implementation

The Step-classes are the place where the real testing-functionality is implemented, using the PageObject-classes.
Basically there is a simple mapping from the Given/When/Then clauses in der scenario-files to corresponding annotations in the Step-classes. We have seen beforehand that the Step-classes are loaded by the Scenario-classes and this way they are “found”.


We can also see in the examples that it is possible to introduce variables here which is obviously required to have meaningful and especially reusable Step-classes.

A common mistake is to write @Given(„Given I opened the codecentric homepage“) instead of @Given(„I opened the codecentric homepage“) which leads to rather strange error messages later on when executing the tests.

In the corresponding methods of the Step-classes we are then implementing the required test functionality using our Page-Objects and potentially other classes for checking e.g. database content, etc. There are in principle no limits.

Nevertheless this approach requires discipline and potentially refactorings as we should really try to make our steps reusable and they must work in any Scenario and not only in one! This is a really important point here as only then we will have a set of keywords – or we could call them clauses – that can be used to write new tests without having the need to touch the implementation all the time. Furthermore the proper balance between more concrete and more generic implementatons must be found.


By using PhantomJS some of the obstacles of we testing vanish. This is especially true for setting up CI environments where certain browsers can be started. Downloading and installing PhantomJS can quickly be done.

With PhantomJS the tests are running in headless mode and most of the time this is a good thing. Whoever has worked with tools like Selenium will feel comfortable here right away. The API offers all the usual functionality required for testing web applications.

If you really need to see what is going on for troubleshooting reasons, you can at any time switch to the ChromeDriver for example.

// webDriver = new PhantomJSDriver(caps);
webDriver = new ChromeDriver(caps);

But as it is always possible to take screenshots, there is hardly any need for this. Taking screenshots at key places in the testing can make sense to have the possibility to visually check certain things still. This can be especially useful in the beginning when starting to write new tests.


Using the right tools and the right software design can improve the quality and maintainability of your test code a lot. Of course there are a lot of possible tools and ways to test web applications. But I could really recommend trying out this approach in a small project maybe to get started.

The tools integrate well into the Java ecosystem and they are documented rather good. In addition a lot of blog articles are dealing with the tools. Using PageObjects as an approach helps in organizing the test code and offers a kind of standard for writing web tests.

Just give it a try :-).


Your email address will not be published. Required fields are marked *