Executing Drupal Behat tests on Vagrant from within PHPStorm

If you've made it past the title, congratulations! There are lots of concepts discussed in this article, I'll mention Vagrant and Behat very briefly, but won't go into details as I'll provide better places to find information on getting started with those tools. This article is mainly for people who use Vagrant for Drupal development, have at least some idea as to how to make a Behat test run on their Vagrant box and want to run those tests from within the PHPStorm IDE.

Vagrant

Vagrant is a tool for creating consistent and portable development environments. The intention is to give all your developers the tools they need to do their job in a single package such as a database and web server. There is work involved in initially setting it up, but once you have a workable receipe you can pass that round to all your developers so they have the consistent development environment. All the tools run from within a Virtual Box, a complete operating system which can be made to be much more like the production environment.

Some helpful people have already done most of the hard work for you so you can start with what they have already done. Popular choices are VLAD and VDD. At Deeson, we tooled the base VDD recipe and added to it to build our own environment which uses a 64 bit version of Ubuntu Trusty64 as well as solr, nginx and a load of other tools. You can find Deeson's VDD recipe at https://github.com/teamdeeson/vdd.

Drupal Behat Tests with Drupalextension

Behat is a PHP tool for creating and running functional tests and, potentially, engaging in something called behaviour driven development (BDD). A functional test describes some function of the finished website. This differs from unit tests, in that a unit test should test some small piece of the code in isolation, whereas a functional test will test a complete path through the system potentially touching many parts of the codebase.

If you are using the Deeson version of VDD linked above then you already have a globally installed copy of Behat. If you are using your own Vagrant box then you will need to add Behat and the Drupal extension to it. The instructions for installing Behat and the Drupalextension can be found at https://behat-drupal-extension.readthedocs.org/en/3.0/globalinstall.html. 

System configuration

I am assuming you have followed the instruction on the Drupalextension site linked above to get a Behat test running on the command line on your Vagrant box. For the rest of the article, I will also assume the following variables, you should subsitute these with you own values where appropriate:

• Project root on the Vagrant box is at /var/www/vhosts/drupal7.dev
• Drupal docroot is within the project root on the Vagrant box at /var/www/vhosts/drupal7.dev/docroot
• Behat tests are on the Vagrant box at /var/www/vhosts/drupal7.dev/behat-tests/features with the behat.yml configuration file at /var/www/vhosts/drupal7.dev/behat-tests/behat.yml
• The project root is also on your local computer at ~/Sites/drupal7.dev such that the drupal docroot is therefore at ~/Sites/drupal7.dev/docroot (Windows users, your milage may vary)
• Your VagrantFile is located on your local computer at ~/Applications/vdd. This is the directory you checked out VDD or the Deeson equivalent if thats what you are using for Vagrant. The VagrantFile is a file in that directory which describes how your Vagrant is configured.

PHPStorm Vagrant Configuration

With the scene set we finally arrive at how to configure your PHPStorm. Within PHPStorm, we want all the tests to execute when we press the play button. Because the tests are running on the remote Vagrant box we need to setup a remote PHP interpreter within PHPStorm and tell PHPStorm this is accessible via Vagrant.

1. PHPStorm -> Preferences
2. Tools -> Vagrant

In the configuration for Vagrant you should set the path to your VagrantFile. This file describes your Vagrant configuration and would be in the folder you checked out VDD or the Deeson equivalent into. My settings are shown below.

PHPStorm PHP Interpreter Configuration

Next you need to tell PHPStorm that PHP is running on the Vagrant instance and can be used to run code with.

1. PHPStorm -> Preferences
2. Languages and Frameworks -> PHP
3. On the Interpreter line click the triple dots button to open the Interpreters configuration screen. 
4. Click the plus (top left) to add a new interpreter
5. Give it a name (e.g. Vagrant PHP)
6. Choose Vagrant
7. Specify the locationt to your VagrantFile (again)
8. Specify the location of PHP on the Vagrant box (e.g. /usr/bin/php). Note that clicking the Reload button here may make PHPStorm work it out for you.

VDD users may get an error about unmatched paths when configuring the Interpreter. You are using a dynamically mounting VagrantFile, and PHPStorm is unable to work out how you project directory maps from your local computer to the Vagrant box. You will need to specify the mappings on a per project basis in your VagrantFile as follows.

Under Vagrant.configure("2") do |config| add the following lines, remebering to replace the local path to the correct path for your system. You'll note that this code will never get run when the VagrantFile is properly used as it is inside an impossible block of code. However, it provides the information PHPStorm needs to work out the mappings from local computer to Vagrant box paths for the project.

Configuring Behat for PHPStorm

1. PHPStorm -> Preferences
2. Languages & Frameworks -> PHP -> Behat
3. Click the plus (top left)
4. Choose the Vagrant PHP Intepreter
5. Specify where behat executable is located within the Vagrant box. If you followed the instructions for drupalextension to install Behat globally then this will be /usr/local/bin/behat
6. Press the reload button (two circular arrows) to have PHPStorm verify the path to Behat is correct
7. Tick Default configuration file
8. Find your behat.yml file in your project on the vagrant box (for me this is /var/www/vhosts/drupal7.dev/behat-tests/behat.yml)

Configuring PHPStorm Run Configuration

We are now ready to configure the run mode in PHPStorm so that the green play button becomes available and pressing it executes the tests

1. Run -> Edit configurations ...
2. Click the plus (top left) then Behat
3. Name: Behat tests
4. Test scope: Defined in configuration file

Press the green play button in PHPStorm and in theory your tests will now be executed on the Vagrant box and the results sent to PHPStorm.

If you would like to just test part of the suite of tests you can do so by tagging the tests and then creating a new Run configuration which specifies which tags to run. Lets say you have tagged some of your scenarios as @justthis

1. Run -> Edit configurations...
2. Press the plus symbol (top left) to add a new configuration and choose Behat
3. Name: Just this
4. Test scope: Defined in the configuration file
5. Test runner options: --tags="justthis"
6. Click OK

Now you have a dropdown choice next to the play button in PHPStorm to choose either Behat tests or Just this. Choose Just this and press play and only the scenarios tagged @justthis will be run.