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.
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:
C:/xampp/htdocs/addons/ mycomponents projectname .git _build (MyComponent config directory here) (standard _build directories here) tests _data _output _support acceptance (test files will go here) functional (test files will go here) integration (test files will go here) unit (test files will go here) acceptance.suite.yml functional.suite.yml unit.suite.yml codeception.yml assets components projectname css js core components projectname docs elements element files lexicon en default.inc.php model projectname.class.php
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
Create the Testing Structure
These commands assume that you have created an alias of
codecept for the Codeception executable. My Alias is
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.
- 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
- Navigate to the
- Issue this command:
- Once bootstrap has finished, type this:
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
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
At the end of the output, you should see all suites listed as
OK. Just above that, you'll see the paths to the
_build directory), the
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.
.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.
_build/codeception.yml file. Add this section at the end if it's not in the file already:
Earlier versions of Codeception put the bootstrap section inside the
settings: section, so if you have trouble, try this older syntax:
settings: bootstrap: _bootstrap.php
Make sure you don't have two
settings: sections. If there already is one, add the line (indented) to it.
_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
Put these lines in the file (adjust the paths to your
< ?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/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
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.
In the next article, we'll look at the various ways to run a unit test from the command line.
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.)