Geb is described as "bringing together the power of WebDriver, the elegance of jQuery content selection, the robustness of Page Object modelling and the expressiveness of the Groovy language".

Geb is a wrapper for the Selenium WebDriver API and works incredibly well with the testing and specification framework Spock. Being from a .Net background I had never used things like Java (although it feels very familiar), Maven, POM files, etc. so in this series of blog posts I will guide you through the set up process and build a specification based automated testing framework from scratch using Geb, Spock, Maven and the IntelliJ IDE.

UI Automation with Geb & Spock (Part 1): Create New Project

1. Add the Maven Integration plugin you haven't got it: File -> Settings... -> Plugins
2. Create a new Maven project using the gmaven-archetype-basic archetype

Note: You will need to download the Java SDK if you haven't already, and set this in the Project SDK section at the top of the New Project window

Your project structure should look like this (with the sections highlighted in red being different depending on the name you gave your project) :

2. Clean up the project - delete the following:

• Example.groovy
• Helper.groovy
• ExampleTest.groovy
• HelperTest.groovy

3. Set the src/test/groovy directory as the Test Sources Root:

• Right click the groovy folder
• Select Mark Directory As > Test Sources Root

4. Delete the contents of the pom.xml file after the version tag and before the closing project tag so it looks similar to this:

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <groupId>example-project</groupId>
    <artifactId>geb-automation</artifactId>
    <name>ndds-automation project</name>
    <version>1.0-SNAPSHOT</version>

    <!-- PASTE FURTHER XML HERE -->

</project>

Now we want to add in some property variables that will allow us to easily change the version of the geb, selenium and groovy packages. These should be added just below the version tag:

    <properties>
        <gebVersion>2.2</gebVersion>
        <seleniumVersion>3.14.0</seleniumVersion>
        <groovyVersion>2.5.3</groovyVersion>
        <spockVersion>1.2-groovy-2.5</spockVersion>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    </properties>

Below the closing properties tag we now want to add in the package dependencies we will need. These are:

groovy-all - contains the groovy libraries required to write groovy code
spock-core - the testing and specification framework
geb-spock - geb library with spock integration
selenium... - the selenium browser drivers and support code

        <dependencies>
        <dependency>
            <groupId>org.codehaus.groovy</groupId>
            <artifactId>groovy-all</artifactId>
            <version>${groovyVersion}</version>
        </dependency>
        <dependency>
            <groupId>org.spockframework</groupId>
            <artifactId>spock-core</artifactId>
            <version>${spockVersion}</version>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.codehaus.groovy</groupId>
                    <artifactId>groovy-all</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.gebish</groupId>
            <artifactId>geb-spock</artifactId>
            <version>${gebVersion}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.seleniumhq.selenium</groupId>
            <artifactId>selenium-firefox-driver</artifactId>
            <version>${seleniumVersion}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.seleniumhq.selenium</groupId>
            <artifactId>selenium-chrome-driver</artifactId>
            <version>${seleniumVersion}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.seleniumhq.selenium</groupId>
            <artifactId>selenium-java</artifactId>
            <version>${seleniumVersion}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.seleniumhq.selenium</groupId>
            <artifactId>selenium-support</artifactId>
            <version>${seleniumVersion}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

Note: Notice how the variables we added earlier are referenced using ${ } e.g. ${seleniumVersion}

Next underneath the dependencies closing tag add the build section below which includes all the plugins required to get started:

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.0</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>2.22.1</version>
                <configuration>
                    <includes>
                        <include>**/*Test.groovy</include>
                        <include>**/*Spec.groovy</include>
                    </includes>
                    <systemPropertyVariables>
                        <geb.build.reportsDir>target/test-reports/geb</geb.build.reportsDir>
                    </systemPropertyVariables>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-assembly-plugin</artifactId>
                <version>3.1.0</version>
                <executions>
                    <execution>
                        <id>build-assembly</id>
                        <phase>compile</phase>
                        <goals>
                            <goal>single</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.codehaus.gmavenplus</groupId>
                <artifactId>gmavenplus-plugin</artifactId>
                <version>1.6.2</version>
                <type>maven-plugin</type>
            </plugin>
        </plugins>
    </build>

Finally below the closing build tag add in the repositories (these are the locations used to download the dependencies):

    <pluginRepositories>
        <pluginRepository>
            <id>central</id>
            <name>Central Repository</name>
            <url>http://repo.maven.apache.org/maven2</url>
            <layout>default</layout>
            <snapshots>
                <enabled>false</enabled>
                <updatePolicy>never</updatePolicy>
            </snapshots>
            <releases>
                <enabled>false</enabled>
                <updatePolicy>never</updatePolicy>
            </releases>
     </pluginRepository>

     <pluginRepositories>
    <pluginRepository>
        <id>central</id>
        <name>Central Repository</name>
        <url>http://repo.maven.apache.org/maven2</url>
        <layout>default</layout>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
        </releases>
    </pluginRepository>
    </pluginRepositories>

    <repositories>
        <repository>
            <id>central</id>
            <name>Central Repository</name>
            <url>http://repo.maven.apache.org/maven2</url>
            <layout>default</layout>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
            <releases>
                <enabled>true</enabled>
            </releases>
        </repository>
    </repositories>

You may now have to import all the dependencies we've just added. You can do this in IntelliJ by pressing Ctrl-Shift-A to bring up the Action window, then typing reimport and selecting Reimport All Maven Projects:

That's it for Part 1 - We're now ready to start modelling some pages and creating some tests!

Download the project for part 1 on GitHub if you prefer: https://github.com/rushby/geb-example-project-part1

Start by doing the following:

• Create a new Class Library Project
• Add the SpecFlow extension to Visual Studio

• Install the following via NuGet:

  -Selenium.WebDriver
  -Selenium.Support
  -WebDriver.ChromeDriver
  -SpecFlow.NUnit
  -SpecRun.SpecFlow

Your App.Config should look something like this:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="specFlow" type="TechTalk.SpecFlow.Configuration.ConfigurationSectionHandler, TechTalk.SpecFlow" />
  </configSections>
  <specFlow>
    <unitTestProvider name="SpecRun+NUnit" />
    <plugins>
      <add name="SpecRun" />
    </plugins>
</specFlow>
</configuration>

Add the ChromeDriver.exe location to the AppSettings section of the app.config - other browser drivers would be added in the same way, so we only edit one place if we need to change the location:

  <appSettings>
    <add key="chromeDriver" value="C:\Users\Administrator\Documents"/>
  </appSettings>

SpecFlow Attributes

Adding the [Binding] attribute to a class lets SpecFlow know that the class contains Step Definitions. This attribute needs to be on every class that contains code required for the tests to execute correctly.

SpecFlow has a number of attributes or "hooks" that can be used to decorate methods, these allow for methods to be called at certain times. For instances methods decorated with the [BeforeScenario] and [AfterScenario] attributes would be called before and after the scenario has executed.

Multiple attributes of the same name are executed in an unpredictable order, to get around this you can set an order similar to [BeforeScenario(Order=1)].

Attributes can also support tag filtering, meaning only scenarios that are prefixed with an @mytagname in the Feature file will run the decorated method [AfterScenario("mytagname")].

More detail on SpecFlow attributes can be found HERE.

Test Setup

Create a test setup base class - I call mine TestSetup. This class is used in conjunction with a number of SpecFlow's attributes to initialise the browser before the test begins and perform any tasks at the end of the scenario, such as disposing the browser, calling code to take a screenshot if the test failed, and setting the database back to its original state at the end of the test.

    public class TestSetup
    {
        public static IWebDriver Browser { get; private set; }

        [BeforeScenario]
        private void InitialiseScenario()
        {
            try
            {
                var options = new ChromeOptions {BinaryLocation = @"C:\Google\Application\chrome.exe"};
            Browser = new ChromeDriver(ConfigurationManager.AppSettings["chromeDriver"], options);
            }
            catch (Exception ex)
            {
                throw new Exception("Unable to locate chrome driver - check the App.config to   ensure the directory is correct for chromeDriver!");
            }
        }

        [AfterScenario]
        private void TearDownScenario()
        {
            Browser.Dispose();
        }

        [AfterScenario]
        private void ShowErrors()
        {
            if (ScenarioContext.Current.TestError != null)
            {
                //ToDo Add some code to capture screenshot.
            }
        }

        [BeforeScenario("resetDatabase")]
        [AfterScenario("resetDatabase")]
        private void ResetDatabase()
        {
            //ToDo run SQL script to put database in original state.
        }
    }

Note: The [Binding] attribute is not required on the TestSetup class as we are going to inherit it. The derived class will have the [Binding] attribute, if both have it you may find 2 browser instances are created each time you run the tests

The IWebDriver property is the WebDriver interface which controls the browser and allows you to interact with elements on the page. You will also notice that the InitialiseScenario() method assigns this interface to a new ChromeDriver instance, which utilises the App.Config setting we previously set up. Any change to driver type would be made here (as additional app settings in the config).

We will come back to this base class once we create the Page Objects.

Page Objects

Using Page Objects allows you to separate the implementation from the specification - this makes your tests less brittle and easier to read. A Page Object represents a web page (or part of a web page) and by utilising a Page Object you can place all the logic required to interact with part of a web page into a single location, improving maintainability.

The Page Object encapsulates all the logic surrounding page interactions, allowing your tests to concentrate on what to do rather than how to do it.

For this example we will use Wikipedia.com. I've added the default url into the App.config as follows(under the chromeDriver setting I added earlier):

    <add key="MainPageUrl" value="https://www.wikipedia.org/"/>

Begin by creating an abstract class, I call it PageObject. This class will contain common web page properties such as its Title and URL. This class can also contain methods to fill out all fields with values detailed in the test, or with default values for each field on the page - useful to progress through a multi page website, and also move most form filling actions into a single method containing a switch statement to decide how each field is selected (I'll blog about this in the future).

For now I've created the following:

    public abstract class PageObject
    {
        internal string Title
        {
            get { return Browser.Title; }
        }

        internal static string Url { get; set; }
        protected static IWebDriver Browser { get; set; }

        protected PageObject(IWebDriver driver)
        {
            Url = ConfigurationManager.AppSettings[(GetType().Name) + "Url"];
            Browser = driver;
            GotoPageUrl();
        }

        public void GotoPageUrl()
        {
            try
            {
                Browser.Navigate().GoToUrl(Url);
            }
            catch (Exception e)
            {
                throw new Exception(GetType().Name + " could not be loaded. Check page url is correct in app.config." +
                                    " " + e.Message);
            }
        }
    }

NOTE: you may need to add a reference to System.configuration.dll if it's not added automatically

This class retrieves the relevant page URL from the App.config using (GetType().Name) + "Url" so if we have an inheriting class called MainPage, GetType().Name will retrieve the class name as a String and the code then concatenates this class name and "Url" to become MainPageUrl. This then matches the app setting we just added to the App.Config.

Next I create a Page Object to represent the Wikipedia main page, called MainPage, which inherits from PageObject:

    public class MainPage : PageObject
    {
        public MainPage(IWebDriver driver) : base(driver)
        {

        }
    }

Notice that the MainPage constructor passes the WebDriver instance to its base PageObject which will in turn navigate the browser to the pages Url.

IWebElement & FindsBy

Now I've created a Page Object to represent the Wikipedia main page I need to add the elements (fields, buttons, etc.) as properties. This is achieved by firstly adding an appropriately named IWebElement property to the MainPage class:

private IWebElement _searchField;

I then decorate the property with the FindsBy attribute. This attribute is part of the OpenQA.Selenium.Support.PageObjects namespace and allows an element to be located on the web page by a number of means including Id, CssSelector, ClassName or Xpath and assigned to the property. You can also create a custom method if required.

[FindsBy(How = How.Id, Using = "searchInput")]
 private IWebElement _searchField;

For this example I will use only 2 elements on the page, so I've added a second property for the search button:

[FindsBy(How = How.Name, Using = "go")]
 private IWebElement _searchButton;

In reality your web page will have many elements, your Page Objects might then represent sections of the page rather than whole pages in order to improve maintainability.

Now we need 2 methods, one to enter text into the Search field and one to click the Search button:

public void EnterSearchText(string searchText)
{
    _searchField.SendKeys(searchText);
}

public void ClickSearchButton()
{
    _searchButton.Click();
}

Again for this example I'll keep it simple and add these methods to the MainPage object, but once you start creating additional Page Objects you will want to pull this common functionality out, possibly into the base PageObject class, for reusability and maintainability. This will be covered in the next blog post.

SpecFlow Feature File & Scenario

The next step is to add a Feature file to the project and add a new Scenario:

Feature: MainPage
    In order to further my test automation knowledge
    As an automation tester
    I want to search for information on Wikipedia

Scenario: Search for Test Automation on Wikipedia
    Given I am on the main Wikipedia page
    And I enter Test Automation into the Search field
    When I click the Search button
    Then the Test automation wikipedia page is displayed

Right click the scenario text and select Generate Step Definitions, you can now either copy the methods to clipboard and paste them into your own class (make sure you add the [Binding] attribute to the class) or click the Generate button . This will create a new class (mine is called MainPageSteps.cs) that contains the following:

        [Given(@"I am on the main Wikipedia page")]
        public void GivenIAmOnTheMainWikipediaPage()
        {
            ScenarioContext.Current.Pending();
        }

        [Given(@"I enter Test Automation into the Search field")]
        public void GivenIEnterTestAutomationIntoTheSearchField()
        {
            ScenarioContext.Current.Pending();
        }

        [When(@"I click the Search button")]
        public void WhenIClickTheSearchButton()
        {
            ScenarioContext.Current.Pending();
        }

        [Then(@"the Test Automation wikipedia page is displayed")]
        public void ThenTheTestAutomationWikipediaPageIsDisplayed()
        {
            ScenarioContext.Current.Pending();
        }

I can now make some changes to the methods which should allow reuse in the future:

 [Given(@"I am on the main Wikipedia page")]
        public void GivenIAmOnTheMainWikipediaPage()
        {
            ScenarioContext.Current.Pending();
        }

        [Given(@"I enter (.*) into the Search field")]
        public void GivenIEnterTestAutomationIntoTheSearchField(string input)
        {
            ScenarioContext.Current.Pending();
        }

        [When(@"I click the (.*) button")]
        public void WhenIClickTheSearchButton(string butt)
        {
            ScenarioContext.Current.Pending();
        }

        [Then(@"the (.*) wikipedia page is displayed")]
        public void ThenTheTestAutomationWikipediaPageIsDisplayed(string page)
        {
            ScenarioContext.Current.Pending();
        }

The wildcards added mean as long as the Given, When or Then statement wording matches then the (.*) will be taken as an input parameter into the method.

Now to finish off the Scenario all the ScenarioContext.Current.Pending() lines are replaced with actual logic to perform the test and your class should look like this:

    [Binding]
    public class MainPageSteps : TestSetup
    {
        private MainPage PageToTest { get; set; }

        [Given(@"I am on the main Wikipedia page")]
        public void GivenIAmOnTheMainWikipediaPage()
        {
            PageToTest = new MainPage(Browser);
        }

        [Given(@"I enter (.*) into the Search field")]
        public void GivenIEnterTestAutomationIntoTheSearchField(string input)
        {
            PageToTest.EnterSearchText(input);
        }

        [When(@"I click the (.*) button")]
        public void WhenIClickTheSearchButton(string butt)
        {
            PageToTest.ClickSearchButton();
        }

        [Then(@"the (.*) wikipedia page is displayed")]
        public void ThenTheTestAutomationWikipediaPageIsDisplayed(string page)
        {
            Assert.AreEqual(page + " - Wikipedia, the free encyclopedia", PageToTest.Title);
        }

That's it for now, these tests should run by right clicking within the Feature file and selecting "Run SpecFlow Scenarios". In my next blog post i'll reuse this code, refactor further and implement a Selenium wrapper called Coypu.

I'll be uploading the source code over the weekend for anyone who's interested and will provide a link here.

The creation of Acceptance Criteria should be a collaborative approach between the development team and the business, utilising a common language. Too often language used by the business and that used by development teams and found within code differ and lead to confusion/misinterpretation of requirements. Acceptance Criteria can help bridge this divide.

Acceptance Criteria should include both functional and non-functional criteria. Non-functional requirements such as performance, usability and security criteria may not be defined by the stakeholder and as such the initial Acceptance Criteria will be enhanced by the development teams before being signed off by the stakeholder.

The language used during the creation of Acceptance Criteria also becomes important if you are creating automated tests using a BDD tool such as SpecFlow. Not only must you use the Given-When-Then gherkin syntax you also need to consider reusability, carefully wording steps so that the code behind can be reused.

For instance generating the step definitions in SpecFlow for the step "When I click the Submit button" will produce a method like so:

[When(@"I click the Submit button")]
public void WhenIClickTheSubmitButton()
{
     //Some code.
}

As clicking buttons is a common step you would then want to make this reusable by replacing the button name with a wildcard, also changing the method name to be more generic:

[When(@"I click the (.*) button")]
public void WhenIClickAButton()
{
      //Some code.
}

This method is now reusable, but only if you ensure the Acceptance Criteria uses the same language. This is where reviews should take place to spot issues such as using
"When I click on the Cancel button" rather than "When I click the Cancel button". As it stands those two sentences would generate two different methods (Step Definitions) because one contains the word "on" thus creating two identical tests with the only difference being the wording.

Note: You can combine criteria that are worded slightly differently, but ask yourself if it's truly necessary...

[When(@"I click the (.*) button")]
[When(@"I click on the (.*) button")]
public void WhenIClickAButton()
{
      //Some code.
}   

Here's a few pieces of guidance when taking a BDD approach with Acceptance Criteria and SpecFlow:

Acceptance criteria should be written in the 1st person
Write it as if the person using the system is stating what happens:

When I click the Search button
Then I see the Search Results screen.

There are four possible components to an acceptance test
These are all mandatory except the 'Given' line:

Scenario (or Scenario Outline): Describes the test
Given: Describes any preconditions that would allow you to start the test from a particular point
When: Describes the action to be tested
Then: Describes the expected outcome

Each of the sections (Given, When, Then) can be enhanced using the keywords And and But.

Given I am on the Search screen
And I have entered "lolcat"into the Search field
When I click the Search button
Then I see search results related to my search
And the first result is “whatever”

But and And are interchangeable in terms of functionality.

Given I have searched for "cats"
But there are no results

…will have the same effect as

Given I have searched for "cats"
And there are no results

There will obviously be times where one makes more sense than the other.

Use consistent screen names
To enable test re-use and to avoid confusion, screens should be referenced in the same way throughout the acceptance criteria and should be specific to the app where necessary. However, you need to check this with your developers, as common test code may have been written which can be reused across different apps.

An Acceptance Criteria dictionary which for instance contains reusable names for commonly-referenced screens and controls is definitely a useful resource for the entire team.

Use consistent wording
To enable test re-use and to avoid confusion, common actions should be worded in the same way. E.g. instead of sometimes writing When I press “next” and other times writing When I click ‘Next’ or When the NEXT button is clicked or When I press the Next button you should pick one and let the team know what you've decided so that a consistent approach can be used throughout the tests (consider adding this to your Acceptance Criteria dictionary).

Know the difference between single quotes and double quotes.
Whenever words are surrounded by double quotes they are interpreted as inputs to the test. For instance:

When I click "Next"
When I click "Back"

Behind the scenes this is just one WhenIClick test, which will have different values ("Back" or "Next") passed into it. However, single quotes are ignored and can therefore be used for emphasis.

Impact Analysis: Always review the relevant acceptance tests that already exist
As with any type of test some may need to be updated, such as when writing acceptance criteria for changes to a screen that already exists (rather than a new screen). If you're developing iteratively you should expect many changes to the software and the tests.

Review the initial draft of the Acceptance Criteria
Developers and Testers should review the criteria as the developer sometimes needs to make small tweaks to the acceptance criteria for code purposes, and the tester may think of scenarios you have not considered. These changes should then be agreed by the stakeholder.

The concept of “or” does not exist.
You cannot say “When I click A or B, Then…”
In fact, this is two tests:

“When I click A, Then…”
“When I click B, Then…”

However, you may well be able to use a Scenario Outline.

Know when to use Scenario Outlines and when to use table parameters
Scenario Outlines allow the same test to be run repeatedly but with different data each time. For instance, you may want to visit the same page several times, and each time select a different item from a dropdown:

Scenario Outline: As a customer I can add differing amounts of the same item to my shopping basket
 Given I am on the ‘Product’ screen
 When I select <number of items> from the Quantity dropdown for <product>
 Then <product> is added to my basket with a quantity of <number of items>
 Examples:
 | product| number of items |
 | cake | 2 |
 | game | 1 |

Table Parameters allow several pieces of data to be passed to one test. For example, you may want to visit one page and enter several different pieces of invalid data into the various inputs. These can all be entered into the same page. If you used a Scenario Outline for this, you would end up visiting the same page several times (possibly via a complicated and lengthy flow) when you could get away with visiting it once:

Scenario: If I attempt to pay without completing a required field I am shown a validation error
Given I am on the Payment screen
And I click the Next button without filling in any details
Then I see the following errors
| fieldLabel           | errorMessage                          |
| Card Number          | You need to provide a card number     |
| Cardholder Name      | You need to provide a name            |
| Card Security Number | You need to provide a security number |

Multiple Parameters are a lot like table parameters, but are written instead using a colon and a comma-separated list of values enclosed in straight quotes:

Scenario: As a customer I see the Payment Failure screen when payment is unsuccessful
When I visit the Payment Failure screen
Then I see the following options: "Try again", "Edit card details", "Choose different payment option"