slic

The slic (StellarWP Local Interactive Containers) CLI command provides a containerized and consistent environment for running automated tests.

Table of Contents

• Getting started
  • Why use slic?
  • Why use Codeception?
  • Requirements
  • Installation
  • The most important command to know
• Using slic
  • Tell slic how to find your project
  • Preparing your project
  • Adding tests
  • Running tests
• Advanced topics
  • Defaults for your project with slic.json
  • Managing PHP Versions
  • Making composer installs faster
  • Changing your composer version
  • Customizing slic's .env file
  • Xdebug and slic
  • Configuring IDEs for Xdebug
  • Releasing a new version of slic
• Update guide
  • From 1.0 to 2.0

Getting started

Why use slic?

One of the biggest stumbling blocks that engineers face when getting automated testing going for their projects is the complexity of setting up a testing environment. And as your team size grows, the struggles with consistent test running increase.

slic automatically configures a Codeception testing environment so you don't have to.

Plus, it provides a lot of handy development tools and utilities that you can use while developing your project or during Continuous Integration builds!

Why use Codeception?

Codeception is a PHP testing framework that uses PHPUnit under the hood, adding all sorts of extra features to make testing PHP much easier. By using Codeception, you then get the ability to use wp-browser, a module that greatly simplifies testing WordPress plugins, themes, and whole WP sites at all levels of testing.

» Learn more about wp-browser here and get it set up on your project.

You can see examples of what to toss in your composer.json in our stellarwp/schema repository.

Requirements

Docker.

That's the only prerequisite. Get that installed and running on your machine and you'll be good to go!

Installation

1. Clone the repo

These instructions are assuming that you are cloning the slic repository in ~/projects. If you want it in a different location, feel free to tweak the example commands below.

cd ~/projects
git clone git@github.com:stellarwp/slic.git

2. Add slic to your $PATH

Assuming you are cloning the slic repository in ~/projects:

echo "export PATH=$HOME/projects/slic:$PATH" >> ~/.bashrc
source ~/.bashrc

If you are using zsh, change ~/.bashrc to ~/.zshrc.

The most important command to know

slic is well documented within the CLI utility itself. To see all of the available commands, run:

slic help

You can see details and usage on each command by running:

slic help <command>

Using slic

The slic command has many subcommands. You can discover what those are by typing slic or slic help. If you want more details on any of the subcommands, simply type: slic [subcommand] help.

Tell slic how to find your project

The slic command needs a place to look for plugins, themes, and WordPress. By default, slic creates a _plugins and _wordpress directory within the local checkout of slic. In most cases, however, developers like to run automated tests against the paths where they are actively working on code – which likely lives elsewhere.

Good news! You can use the slic here sub-command to re-point slic's paths so it looks in the places you wish. There are two locations you can tell slic to look.

1. Plugins Directory

If you want to defer all of the WP site configuration to a dynamically pulled codebase and just worry about testing plugins, you can run the slic here command right from the parent directory of your project. Doing so will restrict slic to running tests on subdirectories of where you ran the command.

Example:

# Change to your plugin containing dir (likely some path to wp-content/plugins)
cd /path/to/your/wp-content/plugins

slic here

2. WordPress Directory

The second option is to navigate to the root of your site (likely where wp-config.php lives) and run the slic here command.

Note: This is an opinionated option and there are some assumptions that are made:

1. That the WordPress directory is the path you are indicating or in a sub-directory called wp/.
2. That the wp-content/ (or content/) directory is a sub-directory of the location in which you are typing slic here.

# Change to your root directory of your site (where your wp-config.php file lives)
cd /path/to/your/site

slic here

By running slic here at the site level, this allows you to set plugins, themes, or the site itself as the location from which to run tests. This also has the benefit of running tests within the WP version that your site uses.

Preparing your project

Point slic at your project

Before you can do anything productive with slic, you need to tell it which project you wish to use and then you can initialize the project, run tests, and execute other commands to your heart's content!

Assuming you have a plugin called the-events-calendar in the plugins directory where you ran slic here, you can tell slic you want to take actions on that plugin using the following command:

slic use the-events-calendar

For more information on this command, run slic help use.

Initialize your project

With your desired plugin containing directory set, you will need to initialize plugins so that they are prepped and ready for slic-based automated test running. You do that using slic init [plugin].

Example:

slic init event-tickets

What this command does:

1. Generates a .env.testing.slic env file in the plugin.
2. Generates a test-config.slic.php file in the plugin.
3. Generates a codeception.slic.yml file in the plugin.
4. Prompts for confirmation on running composer and npm installs on the plugin.

Adding tests

As mentioned above, you'll need to use Codeception for your automated testing and it is highly recommended that you make use of wp-browser - which adds a lot of WordPress helper functions and utilities.

Running tests

Ok. You have slic set up. It is pointing at your project. Your project has tests. Now you want to run one of your test suites. Let's pretend that your test suite is called wpunit.

You can run the full suite like so:

slic run wpunit

Or, if you want an even more efficient way to do it, you can do:

slic shell

# You'll get a prompt once you are thrown into the shell

> cr wpunit

Advanced topics

Managing PHP Versions

By default, slic uses PHP 7.4, but you can easily switch between different PHP versions for your projects.

Checking the Current PHP Version

To see which PHP version slic is configured to use or if a version is staged:

slic php-version

Setting a PHP Version

If you're working with a project and want to test it with a different PHP version, you can manually set the version:

slic php-version set 8.1

This will set the PHP version to 8.1 and prompt you to rebuild the stack. This is useful when you want to test your project against a different PHP version than what's automatically detected.

For CI environments or when you want to pre-configure the PHP version before running slic use:

slic php-version set 8.4 --skip-rebuild

This stages the PHP version change for the next time you run slic use <project>, allowing you to avoid pulling Docker images multiple times.

Automatic PHP Version Detection

When you run slic use <project>, slic will automatically detect and use the PHP version specified in:

1. The project's slic.json file (using the phpVersion property)
2. The project's composer.json file (using the config.platform.php property)

PHP Version Priority

PHP versions are applied in the following priority order:

1. Command line override: SLIC_PHP_VERSION=8.3 slic use <project>
2. Staged version (from slic php-version set <version> --skip-rebuild)
3. A Project's .env.slic.local file
4. Auto-detected version from project configuration

Resetting to Default

To reset slic to the default PHP version (7.4):

slic php-version reset

Making composer installs faster

By default, slic caches composer dependencies within the container and, when the containers are destroyed, so is the cache. The good news is that slic allows you to map your machine's composer cache directory into the slic containers so that repeated slic composer commands can benefit from the cache as well!

# Feel free to change the path to whatever is appropriate for your machine.
slic composer-cache set $HOME/.cache/composer

For more information on this topic, type slic help composer-cache.

Changing your composer version

By default, slic uses composer v1 but you may also choose to use v2 by running the following command:

slic composer set-version 2

If you need to go back, just set the version back to 1:

slic composer set-version 1

If you want to know which version slic is pointed at, you can always call:

slic composer get-version

Installing private packages with composer

If you need to install a private composer package, configure the COMPOSER_AUTH environment variable. For example, to install a package from a private GitHub repository:

Note: You may need to create a Personal Access Token.

export COMPOSER_AUTH='{"github-oauth": {"github.com": "YOUR_TOKEN_HERE"}}'

Then, restart slic and try again:

slic restart; slic composer update

Or, in a GitHub Action, for example:

jobs:
  test:
    runs-on: ubuntu-latest

    env:
      COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{ secrets.GH_BOT_TOKEN }}"}}'

Customizing slic's .env file

The slic CLI command leverages .env.* files to dictate its inner workings. It loads .env.* files in the following order, the later files overriding the earlier ones:

1. .env.slic - this is the default .env file and should not be edited.
2. .env.slic.local in the main slic directory - this file doesn't exist by default. Make overrides to all your projects (e.g. SLIC_GIT_HANDLE) by creating it and adding lines to your heart's content.
3. .env.slic.local in your target's directory - this file doesn't exist by default. Make overrides to a single project (e.g. SLIC_PHP_VERSION).
4. .env.slic.run - this file is generated by slic and includes settings that are set by specific slic commands.

Xdebug and slic

Available Commands

slic xdebug help

List the available Xdebug commands.

slic xdebug status

See if Xdebug is enabled or disabled, the host information, and the path mapping to add to your IDE.

Note that this command cannot be ran within slic shell because you've SSH'd into the Codeception container which has no knowledge of slic.

See also: Configuring Xdebug

Enable/Disable Xdebug

Xdebug can be toggled in both the wordpress and slic containers:

Global commands (requires container restart):

• slic xdebug on - Enable Xdebug in both containers
• slic xdebug off - Disable Xdebug in both containers

When using these commands, slic will prompt you to restart the containers.

Within slic shell (takes effect immediately, no restart needed):

• xon - Enable Xdebug
• xoff - Disable Xdebug

Update Guide

This guide covers the steps needed when upgrading slic between major versions.

From 1.0 to 2.0

Breaking Change:

• MySQL 5.5.62 is now used with PHP 7.4 to match WordPress minimum requirements

MySQL 5.5 Database Changes

• You can opt out of this by setting the SLIC_DB_NO_MIN env var to a non-falsy value
• You can specify the database image to use with the SLIC_DB_IMAGE env var
• Database dump collations might need to be updated in test files

What you need to update:

If your tests use database dumps, they might need updating to be compatible with MySQL 5.5.62.
The change needed is updating the collation of database tables from utf8mb4_unicode_520_ci to utf8mb4_unicode_ci.

Option 1: Use this command:

find ./tests -type f -name "*.sql" | xargs -I{} sed -i.bak 's/utf8mb4_unicode_520_ci/utf8mb4_unicode_ci/g' {} && find ./tests -name "*.sql.bak" -delete

Option 2: Use your IDE's search-and-replace functionality to replace, in the database dump files, occurrences of utf8mb4_unicode_520_ci with utf8mb4_unicode_ci.

Verifying the changes: After updating your SQL files, run a sample test to ensure the database loads correctly. Look for any SQL errors related to collations in your test output.

Acknowledgements

Props to @lucatume, @borkweb, and The Events Calendar team for creating this tool and it's predecessor, tric.