Installing Codeception and PhpUnit with Composer

Using the Composer dependency manager to install Codeception and PhpUnit

In the previous article in this series, we looked at installing packages with Composer. In this one, we'll see how to use Composer to install Codeception and PhpUnit.

MODX logo

Installing Codeception

Like Composer, you need to decide whether you want a global or local version of Codeception. Some people put a global vendor directory in a directory higher up like XAMPP, or htdocs. Others create a vendor directory for each project. I have all my extra projects in one MODX install. My vendor directory is at the root of that install. I put any programs that I need globally (like Codeception and Phpdoc) into that vendor directory.

If a specific project requires a package (e.g., Guzzle), I have Composer create a composer.json file and a vendor directory within that project using the composer require vendor_name/package_name command. That way the necessary package(s) will become part of the extra, as will the local autoload.php file in the extras vendor directory.

As the first step for installing those packages necessary for a specific extra, I navigate to the extra's core directory, and then type composer require vendor_name/package_name. That creates the initial composer.json file and the vendor directory in the extra's core directory. For example, some of my packages require Guzzle, so while in that core directory, I might type:

composer require guzzlehttp/guzzle

However you organize things, the command to install Codeception will be:

composer require codeception/codeception --dev

The command above should be made in the directory where you want the Codeception files. A composer.json file and a composer.lock file will also be created or updated in that directory.

(Important: If you use PhpStorm, see the note below on which version of Codeception to install.)

The --dev flag confuses a lot of people. The confusion comes from the fact that Composer assumes that in addition to installing packages your code depends on, you're also planning to distribute your package via Composer and Packagist. If you're not planning to submit your project to Packagist, you don't really care about the --dev specification.

The --dev flag identifies a dependent package as something you don't want to distribute with *your* package (kind of like git ignore). For example, you might want to install Codeception, PhpDoc, and PhpUnit, but it's unlikely that you'd want to include them in your final package when you submit it. In that case they would be listed in the composer.json file in the require-dev section.

Note that this has no effect on MODX transport packages. It only affects packages distributed through Composer. Typically, things you don't want to go in your MODX transport package are installed under the _build directory, which is not included in the package unless you modify the build.transport.php file to include it.

Sometimes you need a Composer-installed package to be packaged in your MODX transport file because the project actually needs it at run time (e.g., Guzzle). In that case, you don't want the vendor directory in the _build directory. Typically, it goes in the project's core directory.

In order to be able to run Codeception anywhere, I created an alias that points to its location. My version of the codeception executable (codecept) is in the vendor/bin directory under my main extra development directory (c:/xampp/htdocs/addons/). Here's the alias I use with the Cmder terminal:

codecept=c:/xampp/htdocs/addons/vendor/bin/codecept $*

The $* at the end passes any command-line parameters to the Codeception executable. The codecept command actually launches codecept.bat, which launches php codecept. Your alias might be different, depending on your platform and terminal. You could also just put the executable in your path, or adjust the path to include the Codeception directory.

Having a single copy of Codeception makes configuration slightly more difficult. In some ways it's easier to have a vendor directory inside every project directory, but I have dozens of projects, so I'd rather not have a complete set of Codeception and PhpUnit files inside each one, all of which might need to be updated periodically.


If you use PhpStorm, it has some built-in methods for installing Composer, Codeception and PhpUnit. You can find the current instructions easily with Google (e.g., search for PhpStorm Composer). You can also use these tools inside PhpStorm if you install them as described above, but some configuration may be necessary. We'll look at that in future articles.

One advantage of using PhpStorm, especially for unit testing, is that the tests can be run in a window inside PhpStorm just by right-clicking on the test file names or the suite directory. Better yet, you can run the test under the debugger (once configured). That lets you set breakpoints and step through your test code while watching what's happening.

Important: If you will be running your tests inside PhpStorm, at this writing, you may want to install Codeception 2.3.9. With later versions PhpStorm, and later versions of PHP, PhpStorm will throw some errors when you try to run Codeception tests. The errors are harmless and the tests will run fine, but beginners might be confused by the errors.

composer require codeception/codeception: 2.3.9 --dev

This issue may be fixed by the time you read this. You can try this to install the latest version of Codeception.

composer remove codeception/codeception --dev
composer require codeception/codeception --dev

If that doesn't work, you can do revert to version 2.3.9 by doing this:

composer remove codeception/codeception --dev
composer require codeception/codeception: 2.3.9 --dev

You can also run Composer from inside PhpStorm (on the Tools menu), though I often use the command-line interface. PhpStorm can generate skeleton unit tests for you very quickly and easily. It also does a very impressive job of error checking your test code as you type it.

Installing PhpUnit

You can install a standalone version of PhpUnit for performing unit tests, but since Codeception is built on top of PhpUnit, it's not necessary. When you install Codeception, PhpUnit will be installed as a dependency. Better yet, Codeception provides a nice wrapper for PhpUnit that makes it more convenient to use. We'll see how to use Codeception to run unit tests in the next article. Both will end up in your vendor directory and once you include the composer autoload.php file, you'll be able run both with no further includes.

If you'll be running these tools from inside PhpStorm, you'll need to modify the run configuration in PhpStorm to set the working directory — more on this when we get to running our tests.

Coming Up

In the next article in this series, we'll create an actual unit test.

For more information on how to use MODX to create a web site, see my web site Bob's Guides, or better yet, buy my book: MODX: The Official Guide.

Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)

Comments (0)

Please login to comment.