Back to Site

Getting started

Meet WP Setup

WP Setup is a simple and powerful tool to create WordPress environments using Docker and Docker Compose, providing a simple CLI tool that allows you to create a new project in a few seconds.

With WP Setup you can easily create a local installation to plugin/theme development or add it to a custom CI/CD process to leverage an advanced test environment with PestPHP and WordPress.

Pre requisites

To use WP Setup you only need to have installed:

  • Node 18+
  • Docker

Yes, you do not need any server, MySQL database or even PHP. All will run from our custom docker environment.

Installation

Although it is possible and in some cases recommended to install WP Setup globally, we recommend to install at project basis. This way all configuration will bee keep in your project and can be easily replicate by all your team members. It can drastically reduce new tem members onboarding and facilitate project replication and testing.

So to add it in your project, first ensure you have a npm package started. If not you just need to run the following command in our project directory:

npm init -y

Then you can simply add WP Setup as a development dependency to your project and call the init command to create your setup file.

npm install wp-setup --save-dev
npx wp-setup init

This commands will install WP Setup and will create a file called wp-setup.json in your project root directory. This file is responsible for all your configurations.

As you can see in the commands above, after install the WP Setup as dependency, you can run our CLI calling npx wp-setup <comand…>. To simplify some usual commands, we recommend that you also add the following scripts to your package.json file (created after npm init).

"scripts": {
    "env:start": "wp-setup start",
    "env:stop": "wp-setup stop",
    "env:destroy": "wp-setup destroy",
    "env:composer": "wp-setup run wp-cli --workdir . composer",
    "env:pest": "wp-setup run wp-test-cli --workdir . global-pest"
}

Now you can simply start your new environment just calling:

npm run env:start
# or
npx wp-setup start

And to stop the environment:

npm run env:stop
# or
npx wp-setup stop

Also you can destroy the current environmend installation with all volumes running:

npx wp-setup destroy

Configuring Tests

Now that you have your environment configured, you can start testing your plugin with PestPHP. This will give you access to a modern and powerfull tool to improve your code quality and reliability.

To setup your environment at the root directory of your project, you just need to run:

npx wp-setup init --tests

This will create a phpunit.xml file and a ./tests directory with all configurations needed to start your tests. Then you can simply run your tests with:

npx wp-setup run wp-test-cli --workdir . global-pest
# Or with our recommended scripts above
npm run env:pest

Be aware that this setup expects some things on your environment and current can’t generate coverage repports by default.

Firstly, it expects your plugin at the root directory of your project, if it is not the case you have two options:

  1. Moove the created files and directory to your plugin root directory.
  2. Ensure that the root directory is configured in wp-setup.json and ensures that the file tests/bootstrap.php loads your plugin at line 40.

Other assumption of the default configuration is that your plugin follows the naming pattern dir-name/dir-name.php for the main plugin file. If this is not the case you just need to change the file tests/bootstrap.php at line 40, adding the correct name of your plugin main file.

Another situation can be if you are developing a WordPress theme. In this case you will probably need to force load your code as a theme to correct load your theme during tests. To do this you also should change the file tests/bootstrap.php at line 40, but in this case registering your theme and loading it:

/**
 * Manually load the theme being tested.
 */
function _manually_load_plugin() {
	register_theme_directory( dirname( __FILE__ ) . '/../../' );
	switch_theme('your-theme');
}

At last, every good software keeps a track of it tests coverage, allowing viewing and mesure what exactly is being tested. As you can see in the command to run the tests above, we are using a wrap through PestPHP to allow it to run globally but current this prevents the report generation. To fix this you need to require and load PestPHP from your project directly:

For the following commands, you can run from our devcontainer in case you do not have composer installed with the followng command (this will start VSCode from the development environment):

npx wp-setup code .

Now, use the first command here to start a composer project (if it’s not one already) then require PestPHP and Yoast Pollyfills with the second:

composer init
composer require --dev pestphp/pest yoast/phpunit-polyfills

Then you can run your tests locally (we recommend that you add this in your package.json scripts):

npx wp-setup run -w . wp-test-cli ./vendor/bin/pest
# To generate a coverage repport just run
npx wp-setup run -w . wp-test-cli ./vendor/bin/pest --coverage

Global Installation

You can install WP Setup globally using npm. This method offers some advantages, particularly when working with development containers. By installing WP Setup globally, you avoid the need for a node_modules directory within your project. This allows the node_modules directory to be dedicated to your devcontainer, preventing potential conflicts when installing npm packages on the host system versus within the container.

To install WP Setup globally, run the following command:

npm install -g wp-setup

Important Note

When using WP Setup with a global installation, you should run commands directly using wp-setup instead of npx wp-setup. This difference is crucial for the correct functioning of the tool in a global setup.

For example, instead of running:

npx wp-setup start

you would run:

wp-setup start

Downsides of Global Installation

While global installation has its benefits, there are also some potential drawbacks to consider:

  1. Version Control: Managing different versions of WP Setup across projects can be challenging. A project-specific installation ensures that each project uses the exact version it requires.
  2. Environment Consistency: Differences in global npm package versions between team members’ systems can lead to inconsistencies and potential issues during development.