A less painful local testing set up in Codeception 02

6-minute read

Using the cross-platform local setup solution.

## Another package, more CLI commands The additional CLI commands that will be available in the next version of wp-browser are based on the codeception-setup-local package.
Since the search-replace and setup additional commands might prove useful outside of a WordPress TDD scope I’ve decided to go for a package of its own.
While Codeception current version will not allow to register extra commands the next version will do.
In the meanwhile the wp-browser package has had its own CLI tool, wpcept, for some time and that will allow me to support extra commands before Codeception releases version 2.2. So what can be done with the under development version of wp-browser right now?

Some users, a story

I will try to convey some possible command uses with the story of some users.
These users are not final users though but members of a team working together on a WordPress theme.
Martha and Luca are developers, Andrea is in charge of QA.
The two developers scaffold the theme, the tests and the CI solution of choice that will be in charge of running the tests anytime a commit comes in or once an hour; the CI will run unit, functional and acceptance tests against two databases: tests-db for unit and functional tests and acceptance-db for acceptance tests; internally, the CI server will hit the http://tests.dev URL to run acceptance tests.
While unit and functional testing are developer’s ground acceptance testing will be done using Codeception expressive Cept format; while Andrea might not be a PHP developer by profession he can still find his way around some PHP code.
The base for any acceptance test is a database state where:

  • the theme the team is developing is activated
  • all the theme options are stored in their default state
  • any plugin the theme might require is installed and activated
  • the database has been populated with content using the Theme Unit Test package

The database state, a “fixture” in testing terms, is ready to be shared among the team members.
Martha is in charge of setting up this initial fixture and push it to the team shared repository; she has already installed wp-browser, Codeception and Composer and is ready to take a database snapshot.
Martha’s local setup is the following:

  • local MySQL at 192.168.0.54, username is mysql, password is mysql
  • wp-tests database for unit and functional testing
  • wp database for acceptance testing (this includes manual tests)
  • the local url for acceptance tests is http://wp.local

She snapshots her wp database preparing it for sharing:

wpcept db:snapshot start wp \
 --host=192.168.0.54 --user=mysql --pass=mysql \
 --local-url=http://wp.local --dist-url=http://tests.dev
 --save-config

Martha used --save-config to avoid having to enter the same host, user and pass options over and over.
The command produced two files in the tests/_data folder:

  • start.sql is a dump that Martha will use as her starting fixture for acceptance tests, this will not be pushed to the common repository
  • start.dist.sql is a database dump where any occurrence of the wp.local domain (local to Martha’s machine only) has been replaced with tests.dev (local to the CI, see above); this will be pushed to the common repository

Now the start.dist.sqll fixture could be shared with any team member. For anyone to localize it to his/her local machine the wpcept search-replace command could be used; in Andrea’s case his acceptance testing URL is http://localhost:8080:

wpcept search-replace tests.dev localhost:8080 ./tests/_data/start.dist.sql ./tests/_data/start.sql

The team shares a distribution version of the acceptance.suite.dist.yml file that’s set to match the CI configuration:

# Codeception Test Suite Configuration

# suite for acceptance tests.
# perform tests in browser using the WebDriver or PhpBrowser.
# If you need both WebDriver and PHPBrowser tests - create a separate suite.

class_name: AcceptanceTester
modules:
    enabled:
        - WPBrowser
        - WPDb
        - AcceptanceHelper
    config:
        WPBrowser:
              url: 'http://tests.dev'
              adminUsername: 'admin'
              adminPassword: 'admin'
              adminUrl: '/wp-admin'
        WPDb:
              dsn: 'mysql:host=127.0.0.1;dbname=acceptance-db'
              user: 'root'
              password: 'root'
              dump: 'tests/_data/start.dist.sql'
              populate: true
              cleanup: true
              reconnect: false
              url: 'http://tests.dev'
              tablePrefix: 'wp_'

Leveraging Codeception cascading configuration the CI suite will not need any external intervention to run.
Team members will need to customize the line that suits their local configuration in their local acceptance.suite.yml files.
Andrea’s configuration might be the one below for example;

class_name: AcceptanceTester
modules:
    enabled:
        - WPBrowser
        - WPDb
        - AcceptanceHelper
    config:
        WPBrowser:
              url: 'http://localhost:8080'
              adminUsername: 'andrea'
              adminPassword: 'andrea'
        WPDb:
              dsn: 'mysql:host=127.0.0.1;dbname=wp-db'
              user: 'root'
              password: ''
              dump: 'tests/_data/start.sql'
              url: 'http://localhost:8080'

Local setup

As time passes the development requires another person on QA and the team database fixtures collection has gone from a simple starting point to complex fixtures simulating active conflicting plugins, options, user settings and post situations.
The common version controlled tests/_data folder contains now the following dump files:

  • start.dist.sql
  • no-posts.dist.sql
  • a-lot-of-posts.dist.sql
  • foo-commerce-active.dist.sql
  • bad-plugins-activated.dist.sql

that the new QA person should each “localize” to his/her own testing environment.
Plus each dump is being used as a Codeception environment base, the tests/acceptance.suite.dist.yml file has grown accordingly:

class_name: AcceptanceTester
modules:
    enabled:
        - WPBrowser
        - WPDb
        - AcceptanceHelper
    config:
        WPBrowser:
              url: 'http://tests.dev'
              adminUsername: 'admin'
              adminPassword: 'admin'
              adminUrl: '/wp-admin'
        WPDb:
              dsn: 'mysql:host=127.0.0.1;dbname=acceptance-db'
              user: 'root'
              password: 'root'
              dump: 'tests/_data/start.dist.sql'
              populate: true
              cleanup: true
              reconnect: false
              url: 'http://tests.dev'
              tablePrefix: 'wp_'
env:
    noposts:
        modules:
            config:
                WPDb:
                    dump: 'tests/_data/no-posts.dist.sql'
    alotofposts:
        modules:
            config:
                WPDb:
                    dump: 'tests/_data/a-lot-of-posts.dist.sql'
    foocommerce:
        modules:
            config:
                WPDb:
                    dump: 'tests/_data/foo-commerce-active.dist.sql'
    badplugins:
        modules:
            config:
                WPDb:
                    dump: 'tests/_data/bad-plugins-activated.dist.sql'

The new QA person, Lucia, should create her local version of this file too to be able to run the acceptance tests.
Martha decides it’s time to put some local setup solution in place and adds a local.yml file to the repository:

acceptance-testing-environment:
    message: This wizard will help you set up your local acceptance testing environment.
    message: You can re-run this anytime to update/correct your local setup.
    var:
        name: localUrl
        question: What is the URL used for acceptance tests? (e.g "http://wp.dev")
        validate: url
    var:
        name: dbName
        question: What is the name of the database used for acceptance tests?
    var:
        name: dbHost
        question: What is the host of the database used for acceptance tests?
        default: localhost
    var:
        name: dbUser
        question: What is the username of the database used for acceptance tests?
        default: root
    var:
        name: dbPass
        question: What is the password of the database used for acceptance tests?
        default: root
    message: Localizing database dumps...
    command:
        for: dump in start,no-posts,a-lot-of-posts,foo-commerce-active,bad-plugins-activated
        value: search-replace http://tests.dev $localUrl ./tests/_data/$dump.dist.sql ./tests/_data/$dump.sql
    message:
        for: dump in start,no-posts,a-lot-of-posts,foo-commerce-active,bad-plugins-activated
        value: Localized [./tests/_data/$dump.dist.sql] to [./tests/_data/$dump.sql]
    message: Localizing the acceptance suite configuration...
    command: search-replace http://tests.dev $localUrl ./tests/acceptance.suite.dist.yml ./tests/acceptance.suite.yml
    command:
        for: dump in start,no-posts,a-lot-of-posts,foo-commerce-active,bad-plugins-activated
        value: search-replace $dump.dist.sql $dump.sql ./tests/acceptance.suite.yml
    message: Localized the acceptance suite configuration file.
    message: You should be able to run acceptance tests using "./vendor/codecept run acceptance"
    message: Test responsibly

Lucia is left with a simple steps guide to install Composer, pull the latest version of the theme repository and navigate to the theme root folder.
Once there run:

composer require lucatume/wp-browser
./vendor/wpcept setup local

and answer the questions. wpcept setup command

Next

I will improve the setup command syntax to add var declaration, break possibility and regex validation.