Unit Testing I - Organization and Configuration

Organizing and configuring our testing system

In the previous article in this series, we looked at installing Codeception and PhpUnit with Composer. In this one, we'll look at setting up a directory structure for unit tests with PhpUnit and Codeception.

The rest of this article assumes that you have successfully installed Codeception with Composer, PhpUnit will be installed automatically as part of that process.

MODX logo


You're free to create whatever structure you want for your test files. Here's how I organize things. I have one MODX install and all my projects are inside it. It is created and managed with the MyComponent extra, though Codeception will create all the tests directory and the files under it. The projectname directory below is the the directory for a single MODX extra project:

                (MyComponent config directory here)
                (standard _build directories here)

                        (test files will go here)
                        (test files will go here)
                        (test files will go here)
                        (test files will go here)

                            element files

That's the full structure, but for this series of articles, all you should need is the _build directory (Codeception will create the structure under it, which is best left as is), and a place for the class file or files that you want to test (e.g., projectname/core/model/user.class.php). You will include the class file manually, so it can go anywhere as long as you use the correct path to include it.

I strongly recommend that for this series of articles, you create a _build directory and let Codeception place the files under it, because I'll be referring to the _build directory throughout the articles. The name of the _build directory is arbitrary, but it's a standard for MODX transport packages, and that's the name I'll be using.

I use the _build directory because MODX will typically not include that directory in a transport package. Most people using a MODX extra wouldn't want the test files, and those that do can get them from the GitHub repo for the project.

To repeat, create the _build directory but not the files under it. It's best to have Codeception create most of them with the generate command.

Create the Testing Structure

These commands assume that you have created an alias of codecept for the Codeception executable. My Alias is

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

If not you'll have to use the actual name and possibly the path to that executable. If the PHP executable is not in your path, you may also have modify the path, or modify the codeception.bat file to give the full path to PHP.

  1. Use your terminal or terminal emulator (I use Cmder. Any console will do, (including the built-in command line), but Cmder has some nice features
  2. Navigate to the _build directory
  3. Issue this command: codecept bootstrap
  4. Once bootstrap has finished, type this: codecept build

That will create the tests directory under the current directory and will create almost all the necessary directories and files below it except for the individual test files.

Since we will also be creating integration tests later in this series, give this command as well (still in the _build directory):

codecept generate:suite integration UnitTester

Codeception assumes that the integration tests will also be in the unit/ directory, but I prefer to separate them.

UnitTester is the Codeception "Actor" that will be used in integration tests we generate later. If you look at the integration.yml file, you'll see that that actor has been added at the beginning.

To make sure everything is copacetic, run this command in the _build directory:

codecept config:validate

At the end of the output, you should see all suites listed as OK. Just above that, you'll see the paths to the codecept_root_dir() (the _build directory), the codecept_output_dir() (..._build/tests/_output), and codecept_data_dir() (..._build/tests/_data).

Those three functions are nice to remember because they can be used in the code of your tests. They each produce a full, absolute path to the specified directory.

Some Modifications

The .yml files are in YAML format (often used for configuration files, and easily converted to JSON). YAML stands for "YAML Ain't Markup Language." You can learn more about the YAML format here. Note that unlike PHP or HTML, in YAML, indentation is important.

Edit your _build/codeception.yml file. Add this section at the end if it's not in the file already:

bootstrap: _bootstrap.php

Earlier versions of Codeception put the bootstrap section inside the settings: section, so if you have trouble, try this older syntax:

    bootstrap: _bootstrap.php

Make sure you don't have two settings: sections. If there already is one, add the line (indented) to it.

The _build/codeception.yml file is the master configuration file for all tests in all suites. The setting above tells Codeception to run the _bootstrap.php file before running tests in any suite.

You can also add those lines to the configuration file for a particular suite (e.g. unit/suite.yml) and add a _bootstrap.php file inside the suite directory where you run code that should only be run for tests in that suite. We've used the master config file because you'll want the files we'll load below in all your suites.

Now create a PHP file in the _build/tests/ directory called _bootstrap.php

Put these lines in the file (adjust the paths to your vendor directory):

< ?php  // remove the space before the ? to make this a regular php tag
require_once 'c:/xampp/htdocs/addons/vendor/autoload.php';
require_once 'c:/xampp/htdocs/addons/vendor/phpunit/phpunit/src/Framework/Assert/Functions.php';

Once you've added those lines, run the _bootstrap.php file to make sure the paths are correct. If you don't see any errors, you're in business.

Whenever Codeception runs tests in any suite, it will execute the _bootstrap.php code. This saves us from having to add those lines to every test file in various suites. You can (and usually will) also create a _bootstrap.php file in every suite directory. For example, you'll usually want to load the class files for classes you will be testing.

To use a _bootstrap.php file in a given suite, put the same lines we added to _build/codeception.yml into a .yml file in the tests/ directory named for the suite (e.g., tests/unit.suite.yml or tests/integration.suite.yml). The configuration will apply when you run any test in the given suite.

Later, you can modify any _bootstrap.php file to include other files or perform actions that you need for your tests (for example, instantiating MODX or another CMS platform).

Files and Directories

The unit, integration, functional and acceptance directories are called "test suites." Your individual test files will go inside them. For example, unit tests will go in the unit directory, integration tests will go in the integration directory, and so on.

There are a number of ways to run a test or tests from the command line. You can run all tests in a suite, a single test file, or all tests in all suites. We'll look at how to do that in the next article.

Coming Up

In the next article, we'll look at the various ways to run a unit test from the command line.

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.