Here is the current state of the sign-in scenario:

public class SignInAcceptanceScenarios {

   private WebDriver driver;

   @Before   
   public void setup() {
       driver = new HtmlUnitDriver();
   }

   @Test
   public void shouldPresentKnownUserWithTheWelcomePage() {

       Credentials credentials = new Credentials("ryangreenhall", "password");

       givenAnExistingUserWith(credentials);
       whenUserLogsInWith(credentials);
       thenTheUserIsPresentedWithTheWelcomePage();
   }

   private void givenAnExistingUserWith(Credentials credentials) {
       User user = new UserBuilder().withCredentials(credentials).build();

       UserRespository respository = new UserRespository();
       respository.create(user);
   }

   private void whenUserLogsInWith(Credentials credentials) {
       browseToHomePage();
       enterUsernameAndPassword(credentials);
       clickSignInButton();
   }

   private WebDriver browseToHomePage() {
       driver.get("http://www.example.com/sign-in");
       return driver;
   }

   private void enterUsernameAndPassword(Credentials credentials) {       
       driver.findElement(By.id("username")).sendKeys(credentials.getUserName());
       driver.findElement(By.id("password")).sendKeys(credentials.getPassword());
   }

   private void pressSignInButton() {
       driver.findElement(By.id("login")).submit();
   }

   private void thenTheUserIsPresentedWithTheWelcomePage() {
       Assert.assertEquals("Welcome", driver.getTitle());
   }
}

Violating the Single Responsibility Principle

Following the Single Responsibility Principle we know that a class should have only one reason to change. The SignInAcceptanceScenario is responsible for ensuring that the identified sign-in scenarios execute correctly. Let’s consider how many reasons it has to change:

1. The sign in resource changes: e.g. /log-in;
2. We want to replace Web Driver with another web testing framework;
3. The parameter names for username and password change;
4. The title of the welcome page changes;
5. The behaviour of the application changes;

We have identified that our scenario class has five reasons to change! The only valid reason for this class to change is when the behaviour of the sign in process changes. For example, rather than presenting the user with the welcome page they are taken to their profile page, a common feature for most social networking sites these days.

Clearly with so many reasons to change, acceptance scenarios written in this style have the potential to require many changes throughout the lifetime of the application.

Abstraction and Encapsulation to the Rescue

Wouldn’t it be great if we could encapsulate our scenarios from implementation details such as the location of the sign-in resource and the parameter names used to communicate the users credentials? This would allow the implementation of the application to change without modifying our scenarios.

Currently when implementing the sign in scenario we are thinking in terms of the abstractions provided by the Web, for example, browse to the home page and submit parameters to a sign-in resource. Wouldn’t it be great if we could raise the level of abstraction and just sign in to the application using credentials, asking the resulting page if it is the welcome page?

Let’s briefly consider one possible approach.

Fluent Navigation

Rather than exposing the implementation details of how we are interacting with application we need a suitable abstraction. One such abstraction involves representing each page in the application as a Page Object. The Page Object Model, introduced to me by my colleague Dan Bodart and also recommended by the WebDriver team, nicely encapsulates the internal representation of a page and provides methods for appropriate interactions. Another nice feature of the Page Object Model is that we can make use of a fluent interface to allow seamless navigation through any number of pages.

The goal here is to demonstrate the value of introducing a suitable abstraction for interacting with the application. I will therefore leave detailed descriptions of the implementation in the interest of brevity.

SignInPage

Given that the scenario in the example involves signing in to the application we will need a SignInPage that allows credentials to be entered and submitted.

For example:

import com.example.domain.Credentials;

public class SignInPage implements Page {

    public SignInPage() {
    }

    public SignInPage with(Credentials credentials) {        
        // enter the username and password
        return this;
    }

    public Page submit() {        
        // submit the username and password to the sign-in resource
        // and return a Page representation
        // of the response.
    }

    public String getTitle() {        

    }
}

Application Facade

Now that we have a SignInPage how can our SignInAcceptanceScenarios class get hold of one? The SignInPage will be dispensed by a class called MyApp, which acts a facade for the application providing methods to access various pages in the application. This approach nicely decouples the scenario from the URLs used to address pages in the application.

For example:

import com.example.web.pages.HomePage;import com.example.web.pages.Page;import com.example.web.pages.SignInPage;

public class MyApp {

    public static SignInPage signIn() {        
        // GET the sign in page and return a sign in page object
    }
}

Matching Pages

We now have the ability to navigate to the sign-in page, enter the users credentials and submit, receiving a resultant page. The only remaining functionality required by the sign-in scenario is to ensure that the page returned as a result of submitting user credentials is the welcome page. How can we encapsulate the sign-in scenario from knowing the internals of the welcome page? This sounds like a job for a Hamcrest matcher. We will create a WelcomePageMatcher that knows if a given page is the welcome page by inspecting the title of the page.

For example:

import org.hamcrest.BaseMatcher;
import org.hamcrest.Description;
import com.example.web.pages.Page;

public class WelcomePageMatcher extends BaseMatcher {

    public boolean matches(Object actualPage) {
        return "Welcome".equals(((Page)actualPage).getTitle());
    }

    public void describeTo(Description description) {
    }

    public static WelcomePageMatcher isWelcomePage() {
        return new WelcomePageMatcher();
    }
}

Bringing Everything Together

The application facade, SignInPage and WelcomePageMatcher can be combined to provide a very concise specification of the behaviour required when users sign-in to the example application.

import com.example.domain.builders.UserBuilder;
import com.example.domain.Credentials;
import com.example.domain.User;
import com.example.persistence.UserRespository;
import static com.example.web.MyApp.signIn;
import com.example.web.pages.Page;
import static com.example.web.pages.matchers.WelcomePageMatcher.isWelcomePage;
import org.junit.Test;

public class SignInAcceptanceScenarios {

   @Test
   public void shouldPresentKnownUserWithTheWelcomePage() {
       Page pageAfterLogIn = null;
       Credentials credentials = new Credentials("ryangreenhall", "password");

       givenAnExistingUserWith(credentials);
       whenUserLogsInWith(credentials, pageAfterLogIn);
       thenUserIsPresentedWithTheWelcomePage(pageAfterLogIn);
   }

   // Alternatively we could have:
   @Test
   public void shouldPresentKnownUserWithTheWelcomePage() {
       Credentials credentials = new Credentials("ryangreenhall", "password");

       // Given
       givenAnExistingUserWith(credentials);

       // When
       Page pageAfterLogin = signIn().with(credentials).submit();

       // Then
       ensureThat(pageAfterLogin, isWelcomePage());
   }

   // Alternatively we can combine the when and then steps in a single line:   
   @Test
   public void shouldPresentKnownUserWithTheWelcomePage() {
       Credentials credentials = new Credentials("ryangreenhall", "password");

       givenAnExistingUserWith(credentials);

       ensureThat(signIn().with(credentials).submit(), respondsWithWelcomePage());
   }

   private void givenAnExistingUserWith(Credentials credentials) {
       User user = new UserBuilder().withCredentials(credentials).build();

       UserRespository respository = new UserRespository();
       respository.create(user);
   }

   private void whenUserLogsInWith(Credentials credentials, Page pageAfterLogIn) {
       pageAfterLogIn = signIn().with(credentials).submit();
   }

   private void thenUserIsPresentedWithTheWelcomePage(Page pageAfterLogin) {
       ensureThat(page, isWelcomePage());
   }
}

Summary

We have seen that the introduction of a simple internal DSL to interact with the application has greatly improved the readability of this scenario. Furthermore the SignInAcceptanceScenarios class is now completely decoupled from the implementation of the application making it less susceptible to change.

We can now change the following concerns without modifying the SignInAcceptanceScenario:

1. Location of the sign in resource (encapsulated in the SignInPage class);
2. Web testing framework (encapsulated in both the Application Facade and Page classes);
3. The parameter names for username and password (encapsulated in the SignInPage);
4. The title of the welcome page changes (encapsulated in the WelcomePageMatcher);

The SignInAcceptanceScenarios class now has only one responsibility; defining the behaviour of the application and thus should only require modification when the behaviour of the application changes.

Noisy scenario methods can generally be identified by the presence of long methods, which fail to highlight the important interactions with the application clearly. The code driving the application will typically be at a low level of abstraction adding to the noise. For web applications this will involve requesting resources, posting parameters and ensuring the expected response is returned. For example:

    public class SignInAcceptanceScenarios {

        @Test
        public void shouldPresentKnownUserWithTheWelcomePage() {

            User user = new UserBuilder().withUsername("ryangreenhall").withPassword("password").build();

            UserRespository respository = new UserRespository();            r
            respository.create(user);

            WebDriver driver = new HtmlUnitDriver();
            driver.get("http://www.example.com");

            driver.findElement(By.id("username")).sendKeys("ryangreenhall");
            driver.findElement(By.id("password")).sendKeys("password");
            driver.findElement(By.id("login")).submit();

            Assert.assertEquals("Welcome", driver.getTitle());
     }
}

When reading scenarios I like to see clear descriptions of the steps that are taken when interacting with the application. The main problem with noisy scenario methods is that the reader has to filter through the noise to figure out the following: what is the starting state of the system? What interactions occur? An additional problem is that the reader is required to think at a low level of abstraction. Rather than thinking about signing in to the application we are forced to think in terms of posting parameters representing the username and password to a sign-in resource.

Discovering the Scenario Steps

Reading the example scenario we can see that ensuring a known user is presented with the welcome page requires the following steps:

1. Create a user
2. Navigate to the applications home page
3. Fill in the sign in form with known credentials
4. Submit the signin form
5. Ensure that the user is taken to the welcome page

Some would argue that the example scenario could be improved with the introduction of comments prior to each step. However, I favour scenarios that are composed of small methods, whose names clearly describe: the starting state of the application, the interactions with the application and the expected outcomes. This allows the scenario to be expressed in terms of the domain without distracting the reader with the implementation details.

The Given-When-Then scenario format popularised by Behaviour Driven Development is a good starting point for structuring scenarios.

Making Your Code Read Like a Scenario

The following example shows how the original scenario has been improved using a series of Extract Method refactorings in order to communicate the important steps in the scenario, namely: create a new user, sign in with known credentials and ensure that the user is presented with the welcome page.

     public class SignInAcceptanceScenarios {

        private WebDriver driver;

        @Before        
        public void setup() {
            driver = new HtmlUnitDriver();
        }

        @Test
        public void shouldPresentKnownUserWithTheWelcomePage() {

            Credentials credentials = new Credentials("ryangreenhall", "password");

            givenAnExistingUserWith(credentials);
            whenUserLogsInWith(credentials);
            thenTheUserIsPresentedWithTheWelcomePage();
        }

        private void givenAnExistingUserWith(Credentials credentials) {
            User user = new UserBuilder().withCredentials(credentials).build();

            UserRespository respository = new UserRespository();
            respository.create(user);
        }

        private void whenUserLogsInWith(Credentials credentials) {
            browseToHomePage();
            enterUsernameAndPassword(credentials);
            clickSignInButton();
        }

        private WebDriver browseToHomePage() {
            driver.get("http://www.example.com/sign-in");
            return driver;
        }

        private void enterUsernameAndPassword(Credentials credentials) {
            driver.findElement(By.id("username")).sendKeys(credentials.getUserName());            
            driver.findElement(By.id("password")).sendKeys(credentials.getPassword());
        }

        private void pressSignInButton() {
            driver.findElement(By.id("login")).submit();
        }

        private void thenTheUserIsPresentedWithTheWelcomePage() {
            Assert.assertEquals("Welcome", driver.getTitle());
        }
    }

Structuring scenario methods in this style allows the reader to quickly understand the behaviour expected of the application in the context of a given scenario. Furthermore given that they read like written scenarios in terms of the problem domain they can be used to assist in conversations with QAs and Business Analysts, in addition to serving as useful documentation for future maintainers.

These days, if you are lucky, you may encounter code bases with large suites of both unit and functional tests (perhaps I should say examples, specs or scenarios these days!). However, in some cases, although these tests serve as a reliable regression suite guarding against defects being introduced when adding new features, they may fail to clearly describe the desired behaviour of the system clearly.

In my opinion modern legacy code is code that has good functional and unit test coverage, but where the tests (especially functional) fail to clearly communicate the desired behaviour of the application increasing the cost of maintenance. This is a shame as with a little care and focus on readability it is possible to write functional tests that really do serve as documentation describing the behaviour of the application.

Should the concept of modern legacy be used as an excuse to not write functional tests? Absolutely not. Modern legacy should be a term that is used both to encourage teams to search for better ways to express their tests with the goal of improving readability and to seek out approaches that make functional tests easier to write. Modern legacy is a huge improvement over traditional legacy but there is still plenty of room for improvement in how we ensure that our applications are behaving themselves.

In a future post I plan to identify common functional test smells that I have encountered and to provide practical advice on how to spruce them up so that they describe the behaviour of the application more clearly.

In the meantime have a look at the functional tests in your application. Do they clearly describe the behaviour of your application? A good acid test is to ask a developer from another team if they can understand what your application is supposed to do by reading the functional tests for a given functional area. If you observe a puzzled stare followed by a series of WTFs then you may have some modern legacy code.