Acceptance Testing Drupal Websites with Behat, Mink & Selenium2/Goutte

Tags: Tech Blog Published:

Not so long ago, I was extolling the virtues of Codeception as the logical choice for testing our Drupal sites with - it seemed easier to use for our PHP-familiar developers, without having to learn Behat's "Gherkin" syntax, and the concept of writing "features". But if you want speed and fluency in your test scripts, Behat wins hands down (once you're used to it). Not to mention the fact that you get an awesome little report of all the steps to handover to the client. Here is how to get started:

Getting set up.

Setting up Behat and Mink themselves is actually really easy - especially if you're familiar with composer, which is how i'm going to do it.

First, create yourself a little directory for everything to live in:

mkdir tests  
cd tests

Install composer.

If you don't already have composer installed, you can get it using one easy command:

https://www.dropbox.com/s/nrj7szimehuwesw/Screenshot%202016-08-23%2022.36.44.png?dl=0

You should now see composer.phar in your directory.

Install Behat, Mink & it's dependencies.

Then create a composer.json file, and add the following:

{  
    "require": {  
        "behat/behat": "2.4.*@stable",  
        "behat/mink": "1.4.*@stable",  
        "behat/mink-extension": "*",  
        "behat/mink-goutte-driver": "*",  
        "behat/mink-selenium2-driver": "*"  
    },  
    "minimum-stability": "dev",  
    "config": {  
        "bin-dir": "bin/"  
    }  
} 

Now run composer install, and watch the magic happen.

Once that has finished installing, you need to do a few things to get Behat ready to use Mink to run your tests in a browser.

Init Behat

Run bin/behat --init.

This should create a features folder, a features/bootstrap folder, and a features/bootstrap/FeatureContext.phpfile.

Behat stores test scripts as .feature files - they'll live in the features folder.

Create config file

Create a file in your tests folder called behat.yml, this is a configuration file for behat that it looks for by default, and where we store settings relating to the different browser drivers that we're going to use. In your behat.yml file, put the following:

default:  
  extensions:  
    Behat\MinkExtension\Extension:  
      base_url: *your site url here* 

We'll update this a bit later, but for now, that should work.

Change the context of your tests.

This sounds complicated, but it really isn't, and i'll explain a bit more later:

Open features/bootstrap/FeatureContext.php, and change the following:

/**  
* Features context.  
*/  
class FeatureContext extends BehatContext  
{ 

to this:

use Behat\MinkExtension\Context\MinkContext;  

/**
* Features context.  
*/
class FeatureContext extends MinkContext  
{ 

Now Behat knows to use Mink to run your feature files.

Writing feature files.

Feature files are essentially test scripts that test one single feature of your website, like a contact form, which is what i'll demonstrate testing in this article.

First, create a feature file at features/contact-form.feature, and start by adding the following to it:

Feature: Contact Us form  
  In order for a customer to be able to contact us  
  As a website user  
  I need to be able to successfully submit the form 

The top line defines the title of the feature and is required, the lines of text below it are ignored by Behat, but can be useful to yourself when testing to describe what needs to be checked.

Now you need to add some Scenarios, which are little situations that Behat runs through, think of them as individual test scripts against your feature. Each line of a test script starts with either Given, And, When or Then.

Tests should follow (loosely) the format of:

  • Given I am in a certain situation, like on a certain page.
  • When I do something.
  • Then I should see something.

Note that in Behat feature files, getting capital letters in the right place is really important or your tests won't run. Notice that Given, And,When and Then all have capital letters, and so does the I that comes after each statement.

Here's our contact form test:

Feature: Contact us form
  In order for a customer to be able to contact us
  As a website user
  I need to be able to successfully submit the form

  Scenario: I want to send a message using the contact form.
    Given I am on "/contact-us"
    And I should see "Contact us"
    And I fill in "values[name]" with "Dan Matthews"
    And I fill in "values[email]" with "[email protected]"
    And I fill in "values[message]" with "Hello dan! This is my message"
    When I press "Send"
    Then the url should match "contact-us/thankyou"
    And I should see "Thanks for your enquiry"

Now run this feature by running bin/behat in your terminal, you should see all the steps list in front of you in the terminal window - hopefully they'll be green!

You just ran your first acceptance test in Behat - well done!

The tests you just wrote executed in Goutte - a command-line based browser emulator, which while cool, and quick, is extremely limited. Tests ran in Goutte can't test anything that relies on Javascript - which we'll tackle in the Selenium2 section soon.

Generating reports.

Once you know all your tests are green, this is where the reporting format feature comes into play.

Try running this:

$ bin/behat --format=html --out=report.html

This will generate a HTML document at report.html that will contain a nicely formatted page of each feature, scenario and step:

The next step - automating an actual browser with selenium2

Selenium2 is a fantastic tool that we got introduced to a few years back - it's a Java program that can launch and control actual browser applications like Safari and Firefox. Behat plugs into Selenium2 to run your tests.

Selenium2 Server

First thing we need to do is install a Selenium2 server - this should be nice and easy if you have java installed.

Simply go to the Selium website download page at http://docs.seleniumhq.org/download/.

Extract the archive file, you should get a .jar file sitting in your folder.

Now run the server! Just type java -jar selenium-server-standalone-2.39.0.jar, and you should see your terminal jump to life with activity. Once it's started, it'll tell you how clients can connect to it - usually on port 4444 of your 127.0.0.1 (localhost) address.

That's it! Selenium2 is now running and waiting on us to tell it what to do.

Setup behat to use Selenium2

By default, our Behat and Mink setup uses the Goutte driver, and only uses Selenium2 when you 'tag' a scenario or feature with [email protected] tag.

To use Selenium2 for our tests, make your configuration file, behat.yml, look like this:

default:
    extensions:
        Behat\MinkExtension\Extension:
          base_url: http://mysite.com
          default_session: selenium2
          goutte: ~
          selenium2:
            wd_host: http://127.0.0.1:4444/wd/hub
            browser: firefox

Notice how we're giving it the url that Selenium Server provided us with as the wd_host, and then telling it to use firefox as the test browser.

We're also telling it stop using Goutte as the default, and use Selenium2 instead.

Hopefully, you should see the test unfold in firefox, in front of your eyes, by running bin/behat.

Useful links and tips.

The official Behat website: http://behat.org

The best quick reference resource I've found is this behat cheat sheet:http://blog.lepine.pro/wp-content/uploads/2012/03/behat-cheat-sheet-en…