Testing¶

Install via Composer¶

For a long time, CakePHP 2.x supported PHPunit 3.7.x only. To install PHPUnit as a development dependency through Composer, execute the following in the same directory as your composer.json:

php composer.phar require --dev phpunit/phpunit:"3.7.38"

As of CakePHP 2.10.0, basic support for PHPUnit 4.x and 5.x was added. To upgrade PHPUnit and its dependencies for your application, execute the following:

php composer.phar require --dev phpunit/phpunit:"4.* || 5.*" --update-with-dependencies

This will install either PHPUnit 4.x or 5.x, depending on your system setup and your composer.json configuration.

To be able to work with PHP 7, it is required to install the version 5, and you’ll need to setup the autoloader, and work around an issue in Composer’s autoloader. In your Config/bootstrap.php file add the following:

// Load Composer autoload.
require APP . 'Vendor/autoload.php';

// Remove and re-prepend CakePHP's autoloader as Composer thinks it is the
// most important.
// See: http://goo.gl/kKVJO7
spl_autoload_unregister(array('App', 'load'));
spl_autoload_register(array('App', 'load'), true, true);

Install via .phar Package¶

You can also download the file directly. Just make sure you get the correct version from https://phar.phpunit.de/. Make sure /usr/local/bin is in your php.ini file’s include_path:

wget https://phar.phpunit.de/phpunit-3.7.38.phar -O phpunit.phar
chmod +x phpunit.phar
mv phpunit.phar /usr/local/bin/phpunit

Running tests from a browser¶

CakePHP provides a web interface for running tests, so you can execute your tests through a browser if you’re more comfortable in that environment. You can access the web runner by going to http://localhost/your_app/test.php. The exact location of test.php will change depending on your setup. But the file is at the same level as index.php.

Once you’ve loaded up the test runner, you can navigate App, Core and Plugin test suites. Clicking an individual test case will run that test and display the results.

Running tests from command line¶

CakePHP provides a test shell for running tests. You can run app, core and plugin tests easily using the test shell. It accepts all the arguments you would expect to find on the normal PHPUnit command line tool as well. From your app directory you can do the following to run tests:

# Run a model tests in the app
./Console/cake test app Model/Article

# Run a component test in a plugin
./Console/cake test DebugKit Controller/Component/ToolbarComponent

# Run the configure class test in CakePHP
./Console/cake test core Core/Configure

You can also run test shell in the project root directory. This shows you a full list of all the tests that you currently have. You can then freely choose what test(s) to run:

# Run test in project root directory for application folder called app
lib/Cake/Console/cake test app

# Run test in project root directory for an application in ./myapp
lib/Cake/Console/cake test --app myapp app

./Console/cake test core Console/ConsoleOutput --filter testWriteArray

./Console/cake test app Model/Article --coverage-html webroot/coverage

Creating fixtures¶

When creating a fixture you will mainly define two things: how the table is created (which fields are part of the table), and which records will be initially populated to the table. Let’s create our first fixture, that will be used to test our own Article model. Create a file named ArticleFixture.php in your app/Test/Fixture directory, with the following content:

class ArticleFixture extends CakeTestFixture {

      // Optional.
      // Set this property to load fixtures to a different test datasource
      public $useDbConfig = 'test';
      public $fields = array(
          'id' => array('type' => 'integer', 'key' => 'primary'),
          'title' => array(
            'type' => 'string',
            'length' => 255,
            'null' => false
          ),
          'body' => 'text',
          'published' => array(
            'type' => 'integer',
            'default' => '0',
            'null' => false
          ),
          'created' => 'datetime',
          'updated' => 'datetime'
      );
      public $records = array(
          array(
            'id' => 1,
            'title' => 'First Article',
            'body' => 'First Article Body',
            'published' => '1',
            'created' => '2007-03-18 10:39:23',
            'updated' => '2007-03-18 10:41:31'
          ),
          array(
            'id' => 2,
            'title' => 'Second Article',
            'body' => 'Second Article Body',
            'published' => '1',
            'created' => '2007-03-18 10:41:23',
            'updated' => '2007-03-18 10:43:31'
          ),
          array(
            'id' => 3,
            'title' => 'Third Article',
            'body' => 'Third Article Body',
            'published' => '1',
            'created' => '2007-03-18 10:43:23',
            'updated' => '2007-03-18 10:45:31'
          )
      );
 }

The $useDbConfig property defines the datasource of which the fixture will use. If your application uses multiple datasources, you should make the fixtures match the model’s datasources but prefixed with test_. For example if your model uses the mydb datasource, your fixture should use the test_mydb datasource. If the test_mydb connection doesn’t exist, your models will use the default test datasource. Fixture datasources must be prefixed with test to reduce the possibility of accidentally truncating all your application’s data when running tests.

We use $fields to specify which fields will be part of this table, and how they are defined. The format used to define these fields is the same used with CakeSchema. The keys available for table definition are:

type

CakePHP internal data type. Currently supported:

• string: maps to VARCHAR

• text: maps to TEXT

• biginteger: maps to BIGINT

• smallinteger: maps to SMALLINT

• tinyinteger: maps to TINYINT or SMALLINT depending on the database platform.

• integer: maps to INT

• float: maps to FLOAT

• decimal: maps to DECIMAL

• datetime: maps to DATETIME

• timestamp: maps to TIMESTAMP

• time: maps to TIME

• date: maps to DATE

• binary: maps to BLOB

• boolean: maps to BOOLEAN (or TINYINT(1) on MySQL).

key

Set to primary to make the field AUTO_INCREMENT, and a PRIMARY KEY for the table.

length

Set to the specific length the field should take.

null

Set to either true (to allow NULLs) or false (to disallow NULLs).

default

Default value the field takes.

We can define a set of records that will be populated after the fixture table is created. The format is fairly straight forward, $records is an array of records. Each item in $records should be a single row. Inside each row, should be an associative array of the columns and values for the row. Just keep in mind that each record in the $records array must have a key for every field specified in the $fields array. If a field for a particular record needs to have a null value, just specify the value of that key as null.

Dynamic data and fixtures¶

Since records for a fixture are declared as a class property, you cannot easily use functions or other dynamic data to define fixtures. To solve this problem, you can define $records in the init() function of your fixture. For example if you wanted all the created and updated timestamps to reflect today’s date you could do the following:

class ArticleFixture extends CakeTestFixture {

    public $fields = array(
        'id' => array('type' => 'integer', 'key' => 'primary'),
        'title' => array('type' => 'string', 'length' => 255, 'null' => false),
        'body' => 'text',
        'published' => array('type' => 'integer', 'default' => '0', 'null' => false),
        'created' => 'datetime',
        'updated' => 'datetime'
    );

    public function init() {
        $this->records = array(
            array(
                'id' => 1,
                'title' => 'First Article',
                'body' => 'First Article Body',
                'published' => '1',
                'created' => date('Y-m-d H:i:s'),
                'updated' => date('Y-m-d H:i:s'),
            ),
        );
        parent::init();
    }
}

When overriding init() just remember to always call parent::init().

Importing table information and records¶

Your application may have already working models with real data associated to them, and you might decide to test your application with that data. It would be then a duplicate effort to have to define the table definition and/or records on your fixtures. Fortunately, there’s a way for you to define that table definition and/or records for a particular fixture come from an existing model or an existing table.

Let’s start with an example. Assuming you have a model named Article available in your application (that maps to a table named articles), change the example fixture given in the previous section (app/Test/Fixture/ArticleFixture.php) to:

class ArticleFixture extends CakeTestFixture {
    public $import = 'Article';
}

This statement tells the test suite to import your table definition from the table linked to the model called Article. You can use any model available in your application. The statement will only import the Article schema, and does not import records. To import records you can do the following:

class ArticleFixture extends CakeTestFixture {
    public $import = array('model' => 'Article', 'records' => true);
}

If on the other hand you have a table created but no model available for it, you can specify that your import will take place by reading that table information instead. For example:

class ArticleFixture extends CakeTestFixture {
    public $import = array('table' => 'articles');
}

Will import table definition from a table called ‘articles’ using your CakePHP database connection named ‘default’. If you want to use a different connection use:

class ArticleFixture extends CakeTestFixture {
    public $import = array('table' => 'articles', 'connection' => 'other');
}

Since it uses your CakePHP database connection, if there’s any table prefix declared it will be automatically used when fetching table information. The two snippets above do not import records from the table. To force the fixture to also import its records, change the import to:

class ArticleFixture extends CakeTestFixture {
    public $import = array('table' => 'articles', 'records' => true);
}

You can naturally import your table definition from an existing model/table, but have your records defined directly on the fixture as it was shown on previous section. For example:

class ArticleFixture extends CakeTestFixture {
    public $import = 'Article';
    public $records = array(
        array(
          'id' => 1,
          'title' => 'First Article',
          'body' => 'First Article Body',
          'published' => '1',
          'created' => '2007-03-18 10:39:23',
          'updated' => '2007-03-18 10:41:31'
        ),
        array(
          'id' => 2,
          'title' => 'Second Article',
          'body' => 'Second Article Body',
          'published' => '1',
          'created' => '2007-03-18 10:41:23',
          'updated' => '2007-03-18 10:43:31'
        ),
        array(
          'id' => 3,
          'title' => 'Third Article',
          'body' => 'Third Article Body',
          'published' => '1',
          'created' => '2007-03-18 10:43:23',
          'updated' => '2007-03-18 10:45:31'
        )
    );
}

Loading fixtures in your test cases¶

After you’ve created your fixtures, you’ll want to use them in your test cases. In each test case you should load the fixtures you will need. You should load a fixture for every model that will have a query run against it. To load fixtures you define the $fixtures property in your model:

class ArticleTest extends CakeTestCase {
    public $fixtures = array('app.article', 'app.comment');
}

The above will load the Article and Comment fixtures from the application’s Fixture directory. You can also load fixtures from CakePHP core, or plugins:

class ArticleTest extends CakeTestCase {
    public $fixtures = array('plugin.debug_kit.article', 'core.comment');
}

Using the core prefix will load fixtures from CakePHP, and using a plugin name as the prefix, will load the fixture from the named plugin.

You can control when your fixtures are loaded by setting CakeTestCase::$autoFixtures to false and later load them using CakeTestCase::loadFixtures():

class ArticleTest extends CakeTestCase {
    public $fixtures = array('app.article', 'app.comment');
    public $autoFixtures = false;

    public function testMyFunction() {
        $this->loadFixtures('Article', 'Comment');
    }
}

As of 2.5.0, you can load fixtures in subdirectories. Using multiple directories can make it easier to organize your fixtures if you have a larger application. To load fixtures in subdirectories, simply include the subdirectory name in the fixture name:

class ArticleTest extends CakeTestCase {
    public $fixtures = array('app.blog/article', 'app.blog/comment');
}

In the above example, both fixtures would be loaded from App/Test/Fixture/blog/.

Creating a test method¶

Let’s now add a method to test the function published() in the Article model. Edit the file app/Test/Case/Model/ArticleTest.php so it now looks like this:

App::uses('Article', 'Model');

class ArticleTest extends CakeTestCase {
    public $fixtures = array('app.article');

    public function setUp() {
        parent::setUp();
        $this->Article = ClassRegistry::init('Article');
    }

    public function testPublished() {
        $result = $this->Article->published(array('id', 'title'));
        $expected = array(
            array('Article' => array('id' => 1, 'title' => 'First Article')),
            array('Article' => array('id' => 2, 'title' => 'Second Article')),
            array('Article' => array('id' => 3, 'title' => 'Third Article'))
        );

        $this->assertEquals($expected, $result);
    }
}

You can see we have added a method called testPublished(). We start by creating an instance of our Article model, and then run our published() method. In $expected we set what we expect should be the proper result (that we know since we have defined which records are initially populated to the article table.) We test that the result equals our expectation by using the assertEquals method. See the Running Tests section for more information on how to run your test case.

Mocking model methods¶

There will be times you’ll want to mock methods on models when testing them. You should use getMockForModel to create testing mocks of models. It avoids issues with reflected properties that normal mocks have:

public function testSendingEmails() {
    $model = $this->getMockForModel('EmailVerification', array('send'));
    $model->expects($this->once())
        ->method('send')
        ->will($this->returnValue(true));

    $model->verifyEmail('[email protected]');
}

Simulating GET requests¶

As seen in the testIndexPostData() example above, you can use testAction() to test POST actions as well as GET actions. By supplying the data key, the request made to the controller will be POST. By default all requests will be POST requests. You can simulate a GET request by setting the method key:

public function testAdding() {
    $data = array(
        'Post' => array(
            'title' => 'New post',
            'body' => 'Secret sauce'
        )
    );
    $this->testAction('/posts/add', array('data' => $data, 'method' => 'get'));
    // some assertions.
}

The data key will be used as query string parameters when simulating a GET request.

Choosing the return type¶

You can choose from a number of ways to inspect the success of your controller action. Each offers a different way to ensure your code is doing what you expect:

• vars Get the set view variables.

• view Get the rendered view, without a layout.

• contents Get the rendered view including the layout.

• result Get the return value of the controller action. Useful for testing requestAction methods.

The default value is result. As long as your return type is not result you can also access the various other return types as properties in the test case:

public function testIndex() {
    $this->testAction('/posts/index');
    $this->assertInternalType('array', $this->vars['posts']);
}

Using mocks with testAction¶

There will be times when you want to replace components or models with either partially mocked objects or completely mocked objects. You can do this by using ControllerTestCase::generate(). generate() takes the hard work out of generating mocks on your controller. If you decide to generate a controller to be used in testing, you can generate mocked versions of its models and components along with it:

$Posts = $this->generate('Posts', array(
    'methods' => array(
        'isAuthorized'
    ),
    'models' => array(
        'Post' => array('save')
    ),
    'components' => array(
        'RequestHandler' => array('isPut'),
        'Email' => array('send'),
        'Session'
    )
));

The above would create a mocked PostsController, stubbing out the isAuthorized method. The attached Post model will have save() stubbed, and the attached components would have their respective methods stubbed. You can choose to stub an entire class by not passing methods to it, like Session in the example above.

Generated controllers are automatically used as the testing controller to test. To enable automatic generation, set the autoMock variable on the test case to true. If autoMock is false, your original controller will be used in the test.

The response object in the generated controller is always replaced with a mock that does not send headers. After using generate() or testAction() you can access the controller object at $this->controller.

A more complex example¶

In its simplest form, testAction() will run PostsController::index() on your testing controller (or an automatically generated one), including all of the mocked models and components. The results of the test are stored in the vars, contents, view, and return properties. Also available is a headers property which gives you access to the headers that would have been sent, allowing you to check for redirects:

public function testAdd() {
    $Posts = $this->generate('Posts', array(
        'components' => array(
            'Session',
            'Email' => array('send')
        )
    ));
    $Posts->Session
        ->expects($this->once())
        ->method('setFlash');
    $Posts->Email
        ->expects($this->once())
        ->method('send')
        ->will($this->returnValue(true));

    $this->testAction('/posts/add', array(
        'data' => array(
            'Post' => array('title' => 'New Post')
        )
    ));
    $this->assertContains('/posts', $this->headers['Location']);
}

public function testAddGet() {
    $this->testAction('/posts/add', array(
        'method' => 'GET',
        'return' => 'contents'
    ));
    $this->assertRegExp('/<html/', $this->contents);
    $this->assertRegExp('/<form/', $this->view);
}

This example shows a slightly more complex use of the testAction() and generate() methods. First, we generate a testing controller and mock the SessionComponent. Now that the SessionComponent is mocked, we have the ability to run testing methods on it. Assuming PostsController::add() redirects us to index, sends an email and sets a flash message, the test will pass. A second test was added to do basic sanity testing when fetching the add form. We check to see if the layout was loaded by checking the entire rendered contents, and checks the view for a form tag. As you can see, your freedom to test controllers and easily mock its classes is greatly expanded with these changes.

When doing controller tests using mocks that use static methods you’ll have to use a different method to register your mock expectations. For example if you wanted to mock out AuthComponent::user() you’d have to do the following:

public function testAdd() {
    $Posts = $this->generate('Posts', array(
        'components' => array(
            'Session',
            'Auth' => array('user')
        )
    ));
    $Posts->Auth->staticExpects($this->any())
        ->method('user')
        ->with('id')
        ->will($this->returnValue(2));
}

By using staticExpects you will be able to mock and manipulate static methods on components and models.

Testing a JSON Responding Controller¶

JSON is a very friendly and common format to use when building a web service. Testing the endpoints of your web service is very simple with CakePHP. Let us begin with a simple example controller that responds in JSON:

class MarkersController extends AppController {
    public $autoRender = false;
    public function index() {
        $data = $this->Marker->find('first');
        $this->response->body(json_encode($data));
    }
}

Now we create the file app/Test/Case/Controller/MarkersControllerTest.php and make sure our web service is returning the proper response:

class MarkersControllerTest extends ControllerTestCase {
    public function testIndex() {
        $result = $this->testAction('/markers/index.json');
        $result = json_decode($result, true);
        $expected = array(
            'Marker' => array('id' => 1, 'lng' => 66, 'lat' => 45),
        );
        $this->assertEquals($expected, $result);
    }
}

Create a job¶

Start off by creating a job for your application, and connect your repository so that jenkins can access your code.

Add test database config¶

Using a separate database just for Jenkins is generally a good idea, as it stops bleed through and avoids a number of basic problems. Once you’ve created a new database in a database server that jenkins can access (usually localhost). Add a shell script step to the build that contains the following:

cat > app/Config/database.php <<'DATABASE_PHP'
<?php
class DATABASE_CONFIG {
    public $test = array(
        'datasource' => 'Database/Mysql',
        'host'       => 'localhost',
        'database'   => 'jenkins_test',
        'login'      => 'jenkins',
        'password'   => 'cakephp_jenkins',
        'encoding'   => 'utf8'
    );
}
DATABASE_PHP

This ensures that you’ll always have the correct database configuration that Jenkins requires. Do the same for any other configuration files you need to. It’s often a good idea to drop and re-create the database before each build as well. This insulates you from chained failures, where one broken build causes others to fail. Add another shell script step to the build that contains the following:

mysql -u jenkins -pcakephp_jenkins -e 'DROP DATABASE IF EXISTS jenkins_test; CREATE DATABASE jenkins_test';

Add your tests¶

Add another shell script step to your build. In this step run the tests for your application. Creating a junit log file, or clover coverage is often a nice bonus, as it gives you a nice graphical view of your testing results:

app/Console/cake test app AllTests \
--stderr \
--log-junit junit.xml \
--coverage-clover clover.xml

If you use clover coverage, or the junit results, make sure to configure those in Jenkins as well. Failing to configure those steps will mean you won’t see the results.

Run a build¶

You should be able to run a build now. Check the console output and make any necessary changes to get a passing build.