The e2e test infrastructure was recently introduced to WordPress Core, using Docker to create a local WordPress environment for running the tests.
Almost immediately, folks started trying to use it as a full local development environment, which is a pretty good indication that we should make that easier. 🙂 #47767 is a complete rebuild of the e2e environment, turning it into a dedicated development environment, that also happens to function as an e2e environment. 🎉
The Goal
As we discovered with the Gutenberg local environment, trying to make a shell script based do-it-all tool results in a sub-par experience for everyone. It’s difficult for such a tool to work well across all use cases: if it tries to handle common problems automatically, it will cause problems for regular contributors. If it does the bare minimum, it will be unusable for infrequent contributors. There doesn’t appear to be a happy middle ground.
As such, the idea with this new tool is to allow setting up a local development environment by running as few commands as possible, providing sensible defaults, but allowing as much customisation as possible. This gives a solid base for regular contributors to work from (particularly when testing against uncommon configurations), but also provides room for an external tool that provides new contributors with a seamless experience.
Infrastructure
In order to make this work as cleanly as possible, there are custom Docker images configured for running WordPress. They work for all versions of PHP from 5.2 to 7.3, allowing easy testing of different PHP versions. The image definitions are generated and committed to the wpdev-docker-images GitHub repository, they’re then built and deployed to Docker Hub by Travis.
These images aren’t intended for folks that wish to host Docker-based WordPress sites. Their primary focus is on creating a WordPress development environment.
Using
This tool currently isn’t optimised for inexperienced contributors. Setting it up and using it requires some familiarity with both Docker and the command line.
First off, you’ll need to install Docker.
You’ll also need a recent version of Node. We rarely bump the minimum version of Node required, so if you don’t have a particular need for switching Node versions, installing the latest LTS version is probably the easiest option.
Following that, you’ll need to run npm install to download some build tools that WordPress needs, then npm run env:start will start the server at http://localhost:8889. npm run env:install will set up a clean installation, with the user admin and the password password.
Congratulations! You can now work on WordPress! Here are some extra commands that will help you along the way:
npm run env:stop
If you prefer to stop your Docker containers when you’re not using them, this command will stop them. You can always restart them by running npm run env:start again.
npm run env:clean / npm run env:reset
These can be used to clean up your development environment if things aren’t working correctly. The former will delete the database and some temporary files, while the latter will remove all images, so the next time you run npm run env:start, they’ll be downloaded fresh.
npm run env:logs
Shows the logs server logs.
npm run env:cli
This will run WP-CLI. Where the WP-CLI documentation mentions running wp, run npm run env:cli instead. For example, npm run env:cli help.
npm run test:php / npm run test:e2e
These commands will run the PHPUnit and E2E test suites, respectively.
Configuring
You can also customise the development environment by setting particular environment variables before starting it. After changing any of these settings, you’ll need to run npm run env:stop then npm run env:start before they take effect.
Each OS has a slightly different way of setting environment variables. In these examples, substitute VARIABLE_NAME for the name of the setting you want to change, and value for the value you want to set it to.
Linux, macOS, and WSL: export VARIABLE_NAME=value
Windows (DOS/CMD.exe): SET VARIABLE_NAME=value
Windows (PowerShell): Set-Item Env:VARIABLE_NAME=value
LOCAL_PORT
Change the port number that the site will be available on. You’ll need to run npm run env:install after changing this.
LOCAL_DIR
Change whether the site runs from the src or build directory.
LOCAL_PHP
The PHP version to use when running the site. Valid options are ‘latest’, and ‘{version}-fpm’, where ‘{version}’ is any x.y PHP version from 5.2 onwards.
LOCAL_PHP_XDEBUG
Set to true or false to enable or disable the XDebug module in PHP.
LOCAL_MYSQL
The MySQL version to use. See https://hub.docker.com/_/mysql/ for valid versions. If you downgrade the MySQL version, you may need to run npm run env:clean to reset the MySQL data files.
LOCAL_WP_DEBUG / LOCAL_WP_DEBUG_LOG / LOCAL_WP_DEBUG_DISPLAY / LOCAL_SCRIPT_DEBUG
The debug settings to add to wp-config.php. Set to true or false to change their corresponding debug setting. If you already have a site up and running, it may be easier to just edit these in the wp-config.php file.
What’s Next?
Right now, this has only been committed to trunk. It can soak there for a bit, ensuring it works well for everyone.
Following that, it will be backported to all branches back to WordPress 3.7. Since this is the oldest version we still occasionally make releases for, there’s no value in porting it further back. Importantly, since the Security Team is evaluating ceasing backporting of security fixes to WordPress 3.7, it’s likely that we’ll need to be doing work on that branch to both inform and help site owners upgrade. Having a working development environment makes this a much less painful task.
I’ve been sporadically working on a tool called TestPress, which is intended to make the experience of contributing to WordPress as seamless as possible, particularly for new and non-developer contributors. It hasn’t been updated to make use of this new local environment yet, but that’s high on my todo list. For folks who aren’t comfortable downloading and installing Docker, managing Node versions, or working on the command line, TestPress manages all of that for you. I’ll have more to write about TestPress when it’s in a more usable state. 🙂
That’s about it! Please test and report bugs as you find them! 🐛
#core
