Skip to content

This is the documentation for version 3 of the project. The current version is version 4 and the documentation can be found here.

Extensions

The Codeception testing framework can be extended in a number of ways.

The one this project leverages the most are modules but [extensions are another way].

Modules extend the functionality of Codeception in the context of the tests, while extensions extend its interaction capacities; this is by no means a strict rule but that's usually the case.

The package contains two additional extensions to facilitate testers' life.

Symlinker

The tad\WPBrowser\Extension\Symlinker extension provides an automation to have the Codeception root directory symbolically linked in a WordPress local installation.

Since version 3.9 WordPress supports this feature (with some precautions) and the extension takes charge of:

  • symbolically linking a plugin or theme folder in the specified destination before any suite boots up
  • unlinking that symbolic link after all of the suites did run

It's the equivalent of doing something like this from the command line (on a Mac):

ln -s /my/central/plugin/folder/my-plugin /my/local/wordpress/installation/wp-content/plugins/my-plugin
/my/central/plugin/folder/my-plugin/vendor/bin/codecept run
rm -rf /my/local/wordpress/installation/wp-content/plugins/my-plugin

The extension needs small configuration in the codeception.yml file:

extensions:
    enabled:
        - tad\WPBrowser\Extension\Symlinker
    config:
        tad\WPBrowser\Extension\Symlinker:
            mode: plugin
            destination: /my/local/wordpress/installation/wp-content/plugins
            rootFolder: /some/plugin/folder

The arguments are:

  • mode - can be plugin or theme and indicates whether the current Codeception root folder being symlinked is a plugin or a theme one
  • destination - the absolute path to the WordPress local installation plugins or themes folder; to take the never ending variety of possible setups into account the extension will make no checks on the nature of the destination: could be any folder.
  • rootFolder - optional absolute path to the WordPress plugin or theme to be symlinked root folder; will default to the Codeception root folder

Copier

The tad\WPBrowser\Extension\Copier extension provides an automation to have specific files and folders copied to specified destination files and folders before the suites run.

While WordPress handles symbolic linking pretty well there are some cases, like themes and drop-ins, where there is a need for "real" files to be put in place.

One of such cases is, currently, one where Docker is used to to host and serve the code under test: symbolically linked files cannot be bound inside a container and Docker containers will fail to start in this case.

The extension follows the standard Codeception extension activation and has one configuration parameter only:

extensions:
    enabled:
        - tad\WPBrowser\Extension\Copier
    config:
        tad\WPBrowser\Extension\Copier:
            files:
                tests/_data/required-drop-in.php: /var/www/wordpress/wp-content/drop-in.php
                tests/_data/themes/dummy: /var/www/wordpress/wp-content/themes/dummy
                /Users/Me/Repos/required-plugin: /var/www/wordpress/wp-content/plugins/required-plugin.php
                /Users/Me/Repos/mu-plugin.php: ../../../../wp-content/mu-plugins/mu-plugin.php

The extension will handle absolute and relative paths for sources and destinations and will resolve relative paths from the project root folder.

When copying directories the extension will only create the destination folder and not the folder tree required; in the example configuration above the last entry specifies that a mu-plugin.php file should be copied to the mu-plugins folder: that mu-plugins folder must be there already.

Environments support

Being able to symlink a plugin or theme folder into a WordPress installation for testing purposes could make sense when trying to test, as an example, a plugin in a single site and in multi site environment.

Codeception supports environments and the extension does as well specifying a destination for each.

As an example the acceptance.suite.yml file might be configured to support single and multisite environments:

env:
    single:
        modules:
            config:
                WPBrowser:
                    url: 'http://wp.dev'
                WPDb:
                    dsn: 'mysql:host=127.0.0.1;dbname=wp'
    multisite:
        modules:
            config:
                WPBrowser:
                    url: 'http://mu.dev'
                WPDb:
                    dsn: 'mysql:host=127.0.0.1;dbname=mu'

In the codeception.yml file specifying a destination for each supported environment will tell the extension to symbolically link the plugin or theme file to different locations according to the current environment:

extensions:
    enabled:
        - tad\WPBrowser\Extension\Symlinker
    config:
        tad\WPBrowser\Extension\Symlinker:
            mode: plugin
            destination:
                single: /var/www/wp/wp-content/plugins
                multisite: /var/www/mu/wp-content/plugins

If no destination is specified for the current environment the extension will fallback to the first specified one.

A default destination can be specified to override this behaviour.

extensions:
    enabled:
        - tad\WPBrowser\Extension\Symlinker
    config:
        tad\WPBrowser\Extension\Symlinker:
            mode: plugin
            destination:
                default: /var/www/default/wp-content/plugins
                single: /var/www/wp/wp-content/plugins
                multisite: /var/www/mu/wp-content/plugins

When running a suite specifying more than one environment like

codecept run acceptance --env foo,baz,multisite

Then the extension will use the first matched one, in the case above the multisite destination will be used.

The rootFolder parameter too can be set to be environment-aware and it will follow the same logic as the destination:

extensions:
    enabled:
        - tad\WPBrowser\Extension\Symlinker
    config:
        tad\WPBrowser\Extension\Symlinker:
            mode: plugin
            rootFolder:
                dev: /
                dist: /dist
                default: /
            destination:
                default: /var/www/dev/wp-content/plugins
                dev: /var/www/dev/wp-content/plugins
                dist: /var/www/dist/wp-content/plugins

When running a suite specifying more than one environment like

codecept run acceptance --env dist

Then the extension will symlink the files from /dist into the /var/www/dist/wp-content/plugins folder.

Events

Due to some internal changes in Codeception 4.0, the internal API (really a collection of low-level hacks on my part) that allowed wp-browser to dispatch, and listen for, events in the modules has been removed.

If you want to leverage [the event system wp-browser provides] with Codeception default events (e.g. suite.init or test.before), then you will need to use this extension.

You will not need this extension if you're not using Codeception version 4.0.

You will need to enable it in your Codeception main configuration file (e.g. codeception.dist.yml).

extensions:
    enabled:
        - tad\WPBrowser\Extension\Events
    config:
      tad\WPBrowser\Extension\Events:
        suites: ['acceptance']

The extension only configuration is the suites parameter that allows specifying the suites the extension should apply to.
If the suites parameter is not specified, then the extension will apply to all suites.