VVV, Codeception and wp-browser quick setup guide

6-minute read

Setting up wp-browser in a VVV installation.

Why VVV?

The VVV project provides a “a Vagrant configuration for developing with WordPress” and accomplishes the fundamental objective very well.
I’ve recently held a workshop about test-driven development in WordPress with Codeception and wp-browser at “Future WP” and, having to take into account different machines, setups and local servers configurations, VVV proved to be a perfect starting point.
Configuring it to run WordPress tests is quite easy, so here is a setup guide.

The setup base

This walk-through starts after VVV has been installed and is running on the host machine; the installation guide is clear and simple to follow and I’m not duplicating it here.
In the context of this guide I’m assuming VVV lives in the ~/VVV folder, that we are working on the my-plugin project and that the plugin is being developed in the default WordPress installation provided by the box.
After completing the installation and setup of VVV the default WordPress site should be available at http://local.wordpress.dev; should this not be the case something during VVV setup did not go according to the plan and that should be fixed before proceeding.
If the sanity check above is complete it’s time to move to the following part specific to Codeception and wp-browser.

In and out, host and guest

The Vagrant box provided by VVV goes beyond a simple MySQL, PHP and Ngnix server stack and provides a ready to use and fairly complete WordPress development installation; tools like Composer, grunt-cli, and wp-cli are installed and ready to use.
This allows the entire development, when it comes to the CLI tools, to happen in the virtual machine and not outside of it.
“Inside the virtual machine” means the first CLI instruction to run from the ~/VVV folder (assuming that is the folder where VVV was installed) is this:

vagrant ssh

This will connect, via SSH, to the virtual machine as the vagrant user.
Any further instruction I’m showing here, beside the code editing that will happen in a dedicated PHP IDE like PHPStorm or Sublime Text on the host machine, will then happen “inside the virtual machine”.
When I say “host machine” I mean my laptop, desktop or whatever computer I’m working on, when I say “guest machine” I mean the VVV virtual machine; this is usually the case for any virtual-ish setup (Vagrant, Docker and the like).

Scaffolding the project folder

I’m assuming the scope of the development is to create the my-plugin plugin.
The first step is to create the bare minimum code required to make the plugin show up among the available WordPress plugin in the local.wordpress.dev installation in the ~/VVV/www/wordpress-default/public_html/wp-content/plugins/my-plugin/my-plugin.php file:

/*
Plugin Name: My plugin
Plugin URI: https://wordpress.org/plugins/my-plugin
Description: My plugin
Version: 0.1.0
Author: Me
Author URI: http://example.com
Text Domain: my-plugin
*/

The plugin should now show up, activate and deactivate correctly, among the plugins listed in the VVV default WordPress installation at http://local.wordpress.dev/wp-admin/plugins.php.

Getting wp-browser

Since Composer is provided from VVV and ready to use in the PATH pulling requires entering the virtual machine:

cd ~/VVV
vagrant ssh

Once inside navigate to the plugins folder; the path is now relative to VVV filesystem so it won’t be the same as the one used above:

cd /vagrant/www/wordpress-default/public_html/wp-content/plugins/word-counter
composer init

Composer will ask some questions to initialize the project, for the sake of this small guide the answers are not relevant but here is an example composer.json file:

{
    "name": "lucatume/my-plugin",
    "description": "My plugin",
    "type": "wordpress-plugin",
    "license": "GPL-2.0",
    "authors": [
        {
            "name": "theAverageDev (Luca Tumedei)",
            "email": "luca@theaveragedev.com"
        }
    ],
    "require": {}
}

After initializing the project Composer file require lucatume/wp-browser as a development dependency:

composer require --dev lucatume/wp-browser

Composer will put any dependency binary file, an executable file, in the project vendor/bin folder: to avoid having to type vendor/bin/<command> each time I usually prepend the vendor/bin path to the PATH environment variable:

export PATH=vendor/bin:$PATH \
&& echo "export PATH=vendor/bin:$PATH" >> ~/.bashrc

I am modifying the VVV guest machine here, so no worries about messing up the PATH of my own host machine.

Setting up wp-browser

Many get lost while trying to set up wp-browser for the first time and the VVV context provides an excellent base to understand the process.
At its base wp-browser needs to:

  • know where the WordPress installation files are located; they will be loaded in integration and “WordPress unit” tests
  • know how to connect to the WordPress site “normal” database; this is the database that stores the data of the site I would see when visiting the local installation URL (http://local.wordpress.dev in the case of the VVV default installation)
  • know how to connect to the database dedicated to the integration and “WordPress unit” tests; this database will be used to install WordPress during integration and “WordPress unit” tests

Any test suite using a database should never run on a database containing data of any value; this means that if I am using VVV for my day to day WordPress development my first step should be to backup the site database.
VVV comes with wp-cli too so I can run this command to backup the current database state before wp-browser touches it:

(cd /vagrant/www/wordpress-default/public_html; wp db export backups/backup.sql)

After the backup is done it’s time to configure wp-browser using it interactive mode:

codecept init wpbrowser

The initialization guide will ask a number of questions; the questions will come with a default answer: leave the answer to its default value save for the questions below:

  • Where is WordPress installed? - /vagrant/www/wordpress-default/public_html
  • What’s the name of the database used by the WordPress installation? - wordpress_default
  • Use root and root for database username and password
  • What’s the name of the database WPLoader should use? - wordpress_unit_tests
  • What’s the URL the WordPress installation? - http://local.wordpress.dev
  • What is the folder/plugin.php name of the plugin? - my-plugin/my-plugin.php

Codeception will build the suites for the first time and should be good to go.

Setting up the starting database fixture

To make sure any test relying on a starting database dump will, in fact, start from an empty WordPress installation where only the plugin under development is active the WordPress database needs some setup before an export to the dump wp-browser will look for, from the plugin root folder, inside the virtual machine, run:

wp plugin deactivate $(wp plugin list --status=active --field=name)
wp site empty --yes
wp plugin activate word-counter
wp db export tests/_data/dump.sql

After this Codeception and wp-browser are ready to run and the test-drive development can start scaffolding a first test:

codecept generate:cept acceptance First

A code peek

I’ve pushed a demonstrative repository to GitHub for the “Future WP” event that contains all the files and code I’ve shown at the “Future WP” event.
There is the code I’ve developed for and during the workshop with wp-browser, Codeception and Composer setup files I’ve used on the VVV machine.
This small guide is the short version of the presentation document I’ve used at the workshop.