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.
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
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
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
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.)
--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 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
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
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:
$* 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.
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.
In the next article in this series, we'll create an actual unit test.
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.)