WPBrowser scaffold WP-CLI command 01

Laying the base for a wp-cli WPBrowser dedicated package.

WP-CLI Packages

Due to the recent work done to allow the use of wp-cli in wp-browser I’ve played with the “swiss army knife” of WordPress developers beyond what’s my day-to-day usage of it.
As I’m still appreciating its versatility and power I stumble on the possibility to add packages to it; packages allow extending its functionalities for far reaching tasks (like a multisite migration ) or utility tasks like code linting the code.
My mind blown by this possibility I cannot let it slip without trying to do something with it.

Scaffolding a package

Starting work on a wp-cli package is as easy as installing the command to scaffold packages and running it, in my case:

wp scaffold package lucatume/wpcli-wpbrowser-tests \
    --description="Scaffold wp-browser based tests for a plugin or theme"

This creates a wpcli-wpbrowser-tests folder in my local wp-cli package folder (/Users/Luca/.wp-cli/packages/vendor/lucatume/wpcli-wpbrowser-tests in my case) and scaffolds Behat based tests in it.
The work should be completed launching Behat install script:

cd /Users/Luca/.wp-cli/packages/vendor/lucatume/wpcli-wpbrowser-tests
sh ./vendor/bin/install-package-tests.sh

That doesn’t work out due to a shell error so I run manually what commands the script should have run for me:

mysql -e 'CREATE DATABASE IF NOT EXISTS wp_cli_test;' -uroot -p
mysql -e 'GRANT ALL PRIVILEGES ON wp_cli_test.* TO "wp_cli_test"@"localhost" IDENTIFIED BY "password1"' -uroot -p
composer require --dev behat/behat='~2.5'

Note: I had wp-cli and Composer already installed on my machine and aliased, respectively, to wp and composer.

I then run Behat from the package root folder with the behat command to make sure everything is working as intended:

Writing the first Behat test

Terms that would apply to a full-blown web application are kind of crammed when referring to Behat features and scenarios based tests for a cli application.
I will call the kind of tests I run with Behat “functional” as I will use Behat tests to check for files, output and generally side-effects of running a command and that the needed tasks will be performed.
In Codeception terms each “feature” would be a cest tests, each test method would roughly be equivalent to a scenario.
The first feature I write covers the scaffolding command existence and definition.
Where wp-cli offers the scaffold plugin-tests command I’d like my package to offer the wpb-scaffold plugin-tests and wpb-scaffold theme-tests commands.
The first feature is to have the command defined and working and I’m exploring it in a test (features/scaffold-base.feature):

Feature: Test that WPBrowser command exists and can help.

  Scenario: the wpb-scaffold command exists
    Given a WP install

    When I run `wp wpb-scaffold`
    Then STDOUT should contain:
      """
      usage: wp wpb-scaffold plugin-tests
         or: wp wpb-scaffold theme-tests
      """

    Scenario: the wpb-scaffold help command displays usage information
      Given a WP install

      When I run `wp wpb-scaffold help`
      Then STDOUT should contain:
      """
      usage: wp wpb-scaffold plugin-tests
         or: wp wpb-scaffold theme-tests
      """

This doesn’t require me to write any steps and puts me on a roll (a downhill one at the moment) on the red-light/green-light roller coaster of TDD.

The command is missing entirely so no surprises here.

Adding a command in a package

To make the command available in the package I update the command.php file, the package entry point, to add the wpb-scaffold command:

<?php

use tad\WPCLI\Commands\Scaffold;

if ( ! class_exists( 'WP_CLI' ) ) {
    return;
}

require_once 'vendor/autoload.php';

$scaffoldCommand = new Scaffold();

WP_CLI::add_command( 'wpb-scaffold', [ $scaffoldCommand, 'help' ] );

Leveraging how command registration works I alias the Scaffold::help() method to handle the wpb-scaffold and wpb-scaffold help commands; the class code is the bare minimum to pass the test:

<?php

namespace tad\WPCLI\Commands;

class Scaffold extends \WP_CLI_Command {

    public function help() {
        \WP_CLI::line( 'usage: wp wpb-scaffold plugin-tests' );
        \WP_CLI::line( '   or: wp wpb-scaffold theme-tests' );
    }
}

Time to run Behat tests again and see them pass:

Next

Now that I have a grasp on the basic mechanics I will develop the package in an iterative TDD way trying to bring home the plugin test scaffold command first.