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.
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?
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
wp-testsdatabase for unit and functional testing
wpdatabase for acceptance testing (this includes manual tests)
- the local url for acceptance tests is
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
--save-config to avoid having to enter the same
pass options over and over.
The command produced two files in the
start.sqlis a dump that Martha will use as her starting fixture for acceptance tests, this will not be pushed to the common repository
start.dist.sqlis a database dump where any occurrence of the
wp.localdomain (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
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
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
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'
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:
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
I will improve the
setup command syntax to add var declaration, break possibility and regex validation.