Testing¶

Install PHPUnit with Composer¶

To install PHPUnit with Composer:

$ php composer.phar require --dev phpunit/phpunit:"^5.7|^6.0"

// Before CakePHP 3.4.1
$ php composer.phar require --dev phpunit/phpunit:"<6.0"

This will add the dependency to the require-dev section of your composer.json, and then install PHPUnit along with any dependencies.

You can now run PHPUnit using:

$ vendor/bin/phpunit

Using the PHAR File¶

After you have downloaded the phpunit.phar file, you can use it to run your tests:

php phpunit.phar

chmod +x phpunit.phar
sudo mv phpunit.phar /usr/local/bin/phpunit
phpunit --version

Filtering Test Cases¶

When you have larger test cases, you will often want to run a subset of the test methods when you are trying to work on a single failing case. With the CLI runner you can use an option to filter test methods:

$ phpunit --filter testSave tests/TestCase/Model/Table/ArticlesTableTest

The filter parameter is used as a case-sensitive regular expression for filtering which test methods to run.

Generating Code Coverage¶

You can generate code coverage reports from the command line using PHPUnit’s built-in code coverage tools. PHPUnit will generate a set of static HTML files containing the coverage results. You can generate coverage for a test case by doing the following:

$ phpunit --coverage-html webroot/coverage tests/TestCase/Model/Table/ArticlesTableTest

This will put the coverage results in your application’s webroot directory. You should be able to view the results by going to http://localhost/your_app/coverage.

If you are using PHP 5.6.0 or greater, you can use phpdbg to generate coverage instead of xdebug. phpdbg is generally faster at generating coverage:

$ phpdbg -qrr phpunit --coverage-html webroot/coverage tests/TestCase/Model/Table/ArticlesTableTest

Combining Test Suites for Plugins¶

Often times your application will be composed of several plugins. In these situations it can be pretty tedious to run tests for each plugin. You can make running tests for each of the plugins that compose your application by adding additional <testsuite> sections to your application’s phpunit.xml.dist file:

<testsuites>
    <testsuite name="app">
        <directory>./tests/TestCase/</directory>
    </testsuite>

    <!-- Add your plugin suites -->
    <testsuite name="forum">
        <directory>./plugins/Forum/tests/TestCase/</directory>
    </testsuite>
</testsuites>

Any additional test suites added to the <testsuites> element will automatically be run when you use phpunit.

If you are using <testsuites> to use fixtures from plugins that you have installed with composer, the plugin’s composer.json file should add the fixture namespace to the autoload section. Example:

"autoload-dev": {
    "psr-4": {
        "PluginName\\Test\\Fixture\\": "tests/Fixture/"
    }
},

Test Connections¶

By default CakePHP will alias each connection in your application. Each connection defined in your application’s bootstrap that does not start with test_ will have a test_ prefixed alias created. Aliasing connections ensures, you don’t accidentally use the wrong connection in test cases. Connection aliasing is transparent to the rest of your application. For example if you use the default connection, instead you will get the test connection in test cases. If you use the replica connection, the test suite will attempt to use test_replica.

PHPUnit Configuration¶

Before you can use fixtures you should double check that your phpunit.xml contains the fixture listener:

<!-- in phpunit.xml -->
<!-- Setup a listener for fixtures -->
<listeners>
    <listener
    class="\Cake\TestSuite\Fixture\FixtureInjector">
        <arguments>
            <object class="\Cake\TestSuite\Fixture\FixtureManager" />
        </arguments>
    </listener>
</listeners>

The listener is included in your application and plugins generated by bake by default.

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 ArticlesFixture.php in your tests/Fixture directory, with the following content:

namespace App\Test\Fixture;

use Cake\TestSuite\Fixture\TestFixture;

class ArticlesFixture extends TestFixture
{
      // Optional. Set this property to load fixtures to a different test datasource
      public $connection = 'test';

      public $fields = [
          'id' => ['type' => 'integer'],
          'title' => ['type' => 'string', 'length' => 255, 'null' => false],
          'body' => 'text',
          'published' => ['type' => 'integer', 'default' => '0', 'null' => false],
          'created' => 'datetime',
          'modified' => 'datetime',
          '_constraints' => [
            'primary' => ['type' => 'primary', 'columns' => ['id']]
          ]
      ];
      public $records = [
          [
              'title' => 'First Article',
              'body' => 'First Article Body',
              'published' => '1',
              'created' => '2007-03-18 10:39:23',
              'modified' => '2007-03-18 10:41:31'
          ],
          [
              'title' => 'Second Article',
              'body' => 'Second Article Body',
              'published' => '1',
              'created' => '2007-03-18 10:41:23',
              'modified' => '2007-03-18 10:43:31'
          ],
          [
              'title' => 'Third Article',
              'body' => 'Third Article Body',
              'published' => '1',
              'created' => '2007-03-18 10:43:23',
              'modified' => '2007-03-18 10:45:31'
          ]
      ];
 }

The $connection 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 Cake\Database\Schema\Table. The keys available for table definition are:

type

CakePHP internal data type. Currently supported:

• string: maps to VARCHAR or CHAR

• uuid: maps to UUID

• text: maps to TEXT

• integer: maps to INT

• biginteger: maps to BIGINTEGER

• decimal: maps to DECIMAL

• float: maps to FLOAT

• datetime: maps to DATETIME

• timestamp: maps to TIMESTAMP

• time: maps to TIME

• date: maps to DATE

• binary: maps to BLOB

fixed

Used with string types to create CHAR columns in platforms that support them.

length

Set to the specific length the field should take.

precision

Set the number of decimal places used on float & decimal fields.

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 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 modified timestamps to reflect today’s date you could do the following:

namespace App\Test\Fixture;

use Cake\TestSuite\Fixture\TestFixture;

class ArticlesFixture extends TestFixture
{
    public $fields = [
        'id' => ['type' => 'integer'],
        'title' => ['type' => 'string', 'length' => 255, 'null' => false],
        'body' => 'text',
        'published' => ['type' => 'integer', 'default' => '0', 'null' => false],
        'created' => 'datetime',
        'modified' => 'datetime',
        '_constraints' => [
            'primary' => ['type' => 'primary', 'columns' => ['id']],
        ]
    ];

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

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

Importing Table Information¶

Defining the schema in fixture files can be really handy when creating plugins or libraries or if you are creating an application that needs to be portable between database vendors. Redefining the schema in fixtures can become difficult to maintain in larger applications. Because of this CakePHP provides the ability to import the schema from an existing connection and use the reflected table definition to create the table definition used in the test suite.

Let’s start with an example. Assuming you have a table named articles available in your application, change the example fixture given in the previous section (tests/Fixture/ArticlesFixture.php) to:

class ArticlesFixture extends TestFixture
{
    public $import = ['table' => 'articles'];
}

If you want to use a different connection use:

class ArticlesFixture extends TestFixture
{
    public $import = ['table' => 'articles', 'connection' => 'other'];
}

Usually, you have a Table class along with your fixture, as well. You can also use that to retrieve the table name:

class ArticlesFixture extends TestFixture
{
    public $import = ['model' => 'Articles'];
}

Since this uses TableRegistry::getTableLocator()->get(), it also supports plugin syntax.

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 ArticlesFixture extends TestFixture
{
    public $import = ['table' => 'articles'];
    public $records = [
        [
          'title' => 'First Article',
          'body' => 'First Article Body',
          'published' => '1',
          'created' => '2007-03-18 10:39:23',
          'modified' => '2007-03-18 10:41:31'
        ],
        [
          'title' => 'Second Article',
          'body' => 'Second Article Body',
          'published' => '1',
          'created' => '2007-03-18 10:41:23',
          'modified' => '2007-03-18 10:43:31'
        ],
        [
          'title' => 'Third Article',
          'body' => 'Third Article Body',
          'published' => '1',
          'created' => '2007-03-18 10:43:23',
          'modified' => '2007-03-18 10:45:31'
        ]
    ];
}

Finally, it’s possible to not load/create any schema in a fixture. This is useful if you already have a test database setup with all the empty tables created. By defining neither $fields nor $import, a fixture will only insert its records and truncate the records on each test method.

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 ArticlesTest extends TestCase
{
    public $fixtures = ['app.Articles', 'app.Comments'];
}

public function getFixtures()
{
    return ['app.Articles', 'app.Comments'];
}

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 ArticlesTest extends TestCase
{
    public $fixtures = [
        'plugin.DebugKit.Articles',
        'plugin.MyVendorName/MyPlugin.Messages',
        'core.Comments'
    ];
}

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 Cake\TestSuite\TestCase::$autoFixtures to false and later load them using Cake\TestSuite\TestCase::loadFixtures():

class ArticlesTest extends TestCase
{
    public $fixtures = ['app.Articles', 'app.Comments'];
    public $autoFixtures = false;

    public function testMyFunction()
    {
        $this->loadFixtures('Articles', 'Comments');
    }
}

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 ArticlesTest extends CakeTestCase
{
    public $fixtures = ['app.Blog/Articles', 'app.Blog/Comments'];
}

In the above example, both fixtures would be loaded from tests/Fixture/Blog/.

Fixture Factories¶

As your application grows, so does the number and the size of your test fixtures. You might find it difficult to maintain them and to keep track of their content. The fixture factories plugin proposes an alternative for large sized applications.

The plugin uses its own phpunit listener which will perform the following actions:

1. Run migrations once on the test DB (see the migrator).

2. Truncate dirty tables before each test.

3. Run tests.

The following command will help you bake your factories:

bin/cake bake fixture_factory -h

Once your factories are tuned, you are ready to create test fixtures in no time.

Unnecessary interaction with the database will slow down your tests as well as your application. You can create test fixtures without persisting them which can be useful for testing methods without DB interaction:

$article = ArticleFactory::make()->getEntity();

In order to persist:

$article = ArticleFactory::make()->persist();

The factories help creating associated fixtures too. Assuming that articles belongs to many authors, we can now, for example, create 5 articles each with 2 authors:

$articles = ArticleFactory::make(5)->with('Authors', 2)->getEntities();

Note that the fixture factories do not require any fixture creation or declaration. Still, they are fully compatible with the fixtures that come with cakephp. You will find additional insights and documentation here.

Creating a Test Method¶

Let’s now add a method to test the function published() in the Articles table. Edit the file tests/TestCase/Model/Table/ArticlesTableTest.php so it now looks like this:

namespace App\Test\TestCase\Model\Table;

use App\Model\Table\ArticlesTable;
use Cake\ORM\TableRegistry;
use Cake\TestSuite\TestCase;

class ArticlesTableTest extends TestCase
{
    public $fixtures = ['app.Articles'];

    public function setUp()
    {
        parent::setUp();
        $this->Articles = TableRegistry::getTableLocator()->get('Articles');
    }

    public function testFindPublished()
    {
        $query = $this->Articles->find('published');
        $this->assertInstanceOf('Cake\ORM\Query', $query);
        $result = $query->enableHydration(false)->toArray();
        $expected = [
            ['id' => 1, 'title' => 'First Article'],
            ['id' => 2, 'title' => 'Second Article'],
            ['id' => 3, 'title' => 'Third Article']
        ];

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

You can see we have added a method called testFindPublished(). We start by creating an instance of our ArticlesTable class, and then run our find('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.

Using the fixture factories, the test would now look like this:

namespace App\Test\TestCase\Model\Table;

use App\Model\Table\ArticlesTable;
use App\Test\Factory\ArticleFactory;
use Cake\TestSuite\TestCase;

class ArticlesTableTest extends TestCase
{
    public function setUp(): void
    { ... }

    public function testFindPublished(): void
    {
        // Persist 3 published articles
        $articles = ArticleFactory::make(['published' => 1], 3)->persist();
        // Persist 2 unpublished articles
        ArticleFactory::make(['published' => 0], 2)->persist();

        $result = $this->Articles->find('published')->find('list')->toArray();

        $expected = [
            $articles[0]->id => $articles[0]->title,
            $articles[1]->id => $articles[1]->title,
            $articles[2]->id => $articles[2]->title,
        ];

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

No fixtures need to be loaded. The 5 articles created will exist only in this test.

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 table classes. It avoids issues with reflected properties that normal mocks have:

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

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

In your tearDown() method be sure to remove the mock with:

TableRegistry::clear();

Setting up the Request¶

The IntegrationTestTrait trait comes with a number of helpers to make it easy to configure the requests you will send to your application under test:

// Set cookies
$this->cookie('name', 'Uncle Bob');

// Set session data
$this->session(['Auth.User.id' => 1]);

// Configure headers
$this->configRequest([
    'headers' => ['Accept' => 'application/json']
]);

The state set by these helper methods is reset in the tearDown() method.

Testing Actions That Require Authentication¶

If you are using AuthComponent you will need to stub out the session data that AuthComponent uses to validate a user’s identity. You can use helper methods in IntegrationTestTrait to do this. Assuming you had an ArticlesController that contained an add method, and that add method required authentication, you could write the following tests:

public function testAddUnauthenticatedFails()
{
    // No session data set.
    $this->get('/articles/add');

    $this->assertRedirect(['controller' => 'Users', 'action' => 'login']);
}

public function testAddAuthenticated()
{
    // Set session data
    $this->session([
        'Auth' => [
            'User' => [
                'id' => 1,
                'username' => 'testing',
                // other keys.
            ]
        ]
    ]);
    $this->get('/articles/add');

    $this->assertResponseOk();
    // Other assertions.
}

Testing Stateless Authentication and APIs¶

To test APIs that use stateless authentication, such as Basic authentication, you can configure the request to inject environment conditions or headers that simulate actual authentication request headers.

When testing Basic or Digest Authentication, you can add the environment variables that PHP creates automatically. These environment variables used in the authentication adapter outlined in Using Basic Authentication:

public function testBasicAuthentication()
{
    $this->configRequest([
        'environment' => [
            'PHP_AUTH_USER' => 'username',
            'PHP_AUTH_PW' => 'password',
        ]
    ]);

    $this->get('/api/posts');
    $this->assertResponseOk();
}

If you are testing other forms of authentication, such as OAuth2, you can set the Authorization header directly:

public function testOauthToken()
{
    $this->configRequest([
        'headers' => [
            'authorization' => 'Bearer: oauth-token'
        ]
    ]);

    $this->get('/api/posts');
    $this->assertResponseOk();
}

The headers key in configRequest() can be used to configure any additional HTTP headers needed for an action.

Testing Actions Protected by CsrfComponent or SecurityComponent¶

When testing actions protected by either SecurityComponent or CsrfComponent you can enable automatic token generation to ensure your tests won’t fail due to token mismatches:

public function testAdd()
{
    $this->enableCsrfToken();
    $this->enableSecurityToken();
    $this->post('/posts/add', ['title' => 'Exciting news!']);
}

It is also important to enable debug in tests that use tokens to prevent the SecurityComponent from thinking the debug token is being used in a non-debug environment. When testing with other methods like requireSecure() you can use configRequest() to set the correct environment variables:

// Fake out SSL connections.
$this->configRequest([
    'environment' => ['HTTPS' => 'on']
]);

If your action requires unlocked fields you can declare them with setUnlockedFields():

$this->setUnlockedFields(['dynamic_field']);

Integration Testing PSR-7 Middleware¶

Integration testing can also be used to test your entire PSR-7 application and Middleware. By default IntegrationTestTrait will auto-detect the presence of an App\Application class and automatically enable integration testing of your Application. You can toggle this behavior with the useHttpServer() method:

public function setUp()
{
    // Enable PSR-7 integration testing.
    $this->useHttpServer(true);

    // Disable PSR-7 integration testing.
    $this->useHttpServer(false);
}

You can customize the application class name used, and the constructor arguments, by using the configApplication() method:

public function setUp()
{
    $this->configApplication('App\App', [CONFIG]);
}

After enabling the PSR-7 mode, and possibly configuring your application class, you can use the remaining IntegrationTestTrait features as normal.

You should also take care to try and use Application::bootstrap() to load any plugins containing events/routes. Doing so will ensure that your events/routes are connected for each test case. Alternatively if you wish to load plugins manually in a test you can use the loadPlugins() method:

use Cake\Routing\Router;

public function testRouteCount()
{
    // Assert the amount of routes from the application, without loading plugins
    $this->assertCount(35, Router::routes(), 'App route count does not match');

    // Assert the amount of routes from the application including a specific plugin "SomePlugin"
    $this->loadPlugins(['SomePlugin']);
    $this->assertCount(40, Router::routes(), 'App & SomePlugin route count does not match');

    // Assert the amount of routes from the application including all plugins
    $this->loadPlugins();
    $this->assertCount(60, Router::routes(), 'App & plugin route count does not match');
}

Testing with Encrypted Cookies¶

If you use the Cake\Controller\Component\CookieComponent in your controllers, your cookies are likely encrypted. As of 3.1.7, CakePHP provides helper methods for interacting with encrypted cookies in your test cases:

// Set a cookie using AES and the default key.
$this->cookieEncrypted('my_cookie', 'Some secret values');

// Assume this action modifies the cookie.
$this->get('/bookmarks/index');

$this->assertCookieEncrypted('An updated value', 'my_cookie');

Testing Flash Messages¶

If you want to assert the presence of flash messages in the session and not the rendered HTML, you can use enableRetainFlashMessages() in your tests to retain flash messages in the session so you can write assertions:

$this->enableRetainFlashMessages();
$this->get('/bookmarks/delete/9999');

$this->assertSession('That bookmark does not exist', 'Flash.flash.0.message');

As of 3.7.0 there are additional test helpers for flash messages:

$this->enableRetainFlashMessages();
$this->get('/bookmarks/delete/9999');

// Assert a flash message in the 'flash' key.
$this->assertFlashMessage('Bookmark deleted', 'flash');

// Assert the second flash message, also  in the 'flash' key.
$this->assertFlashMessageAt(1, 'Bookmark really deleted');

// Assert a flash message in the 'auth' key at the first position
$this->assertFlashMessageAt(0, 'You are not allowed to enter this dungeon!', 'auth');

// Assert a flash messages uses the error element
$this->assertFlashElement('Flash/error');

// Assert the second flash message element
$this->assertFlashElementAt(1, 'Flash/error');

Testing a JSON Responding Controller¶

JSON is a 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 function initialize()
    {
        parent::initialize();
        $this->loadComponent('RequestHandler');
    }

    public function view($id)
    {
        $marker = $this->Markers->get($id);
        $this->set([
            '_serialize' => ['marker'],
            'marker' => $marker,
        ]);
    }
}

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

class MarkersControllerTest extends IntegrationTestCase
{
    public function testGet()
    {
        $this->configRequest([
            'headers' => ['Accept' => 'application/json']
        ]);
        $result = $this->get('/markers/view/1.json');

        // Check that the response was a 200
        $this->assertResponseOk();

        $expected = [
            ['id' => 1, 'lng' => 66, 'lat' => 45],
        ];
        $expected = json_encode($expected, JSON_PRETTY_PRINT);
        $this->assertEquals($expected, (string)$this->_response->getBody());
    }
}

We use the JSON_PRETTY_PRINT option as CakePHP’s built in JsonView will use that option when debug is enabled.

Disabling Error Handling Middleware in Tests¶

When debugging tests that are failing because your application is encountering errors it can be helpful to temporarily disable the error handling middleware to allow the underlying error to bubble up. You can use disableErrorHandlerMiddleware() to do this:

public function testGetMissing()
{
    $this->disableErrorHandlerMiddleware();
    $this->get('/markers/not-there');
    $this->assertResponseCode(404);
}

In the above example, the test would fail and the underlying exception message and stack trace would be displayed instead of the rendered error page being checked.

Assertion methods¶

The IntegrationTestTrait trait provides a number of assertion methods that make testing responses much simpler. Some examples are:

// Check for a 2xx response code
$this->assertResponseOk();

// Check for a 2xx/3xx response code
$this->assertResponseSuccess();

// Check for a 4xx response code
$this->assertResponseError();

// Check for a 5xx response code
$this->assertResponseFailure();

// Check for a specific response code, e.g. 200
$this->assertResponseCode(200);

// Check the Location header
$this->assertRedirect(['controller' => 'Articles', 'action' => 'index']);

// Check that no Location header has been set
$this->assertNoRedirect();

// Check a part of the Location header
$this->assertRedirectContains('/articles/edit/');

// Added in 3.7.0
$this->assertRedirectNotContains('/articles/edit/');

// Assert not empty response content
$this->assertResponseNotEmpty();

// Assert empty response content
$this->assertResponseEmpty();

// Assert response content
$this->assertResponseEquals('Yeah!');

// Assert response content doesn't equal
$this->assertResponseNotEquals('No!');

// Assert partial response content
$this->assertResponseContains('You won!');
$this->assertResponseNotContains('You lost!');

// Assert file sent back
$this->assertFileResponse('/absolute/path/to/file.ext');

// Assert layout
$this->assertLayout('default');

// Assert which template was rendered (if any)
$this->assertTemplate('index');

// Assert data in the session
$this->assertSession(1, 'Auth.User.id');

// Assert response header.
$this->assertHeader('Content-Type', 'application/json');
$this->assertHeaderContains('Content-Type', 'html');

// Added in 3.7.0
$this->assertHeaderNotContains('Content-Type', 'xml');

// Assert view variables
$user =  $this->viewVariable('user');
$this->assertEquals('jose', $user->username);

// Assert cookies in the response
$this->assertCookie('1', 'thingid');

// Check the content type
$this->assertContentType('application/json');

In addition to the above assertion methods, you can also use all of the assertions in TestSuite and those found in PHPUnit.

Comparing test results to a file¶

For some types of test, it may be easier to compare the result of a test to the contents of a file - for example, when testing the rendered output of a view. The StringCompareTrait adds a simple assert method for this purpose.

Usage involves using the trait, setting the comparison base path and calling assertSameAsFile:

use Cake\TestSuite\StringCompareTrait;
use Cake\TestSuite\TestCase;

class SomeTest extends TestCase
{
    use StringCompareTrait;

    public function setUp()
    {
        $this->_compareBasePath = APP . 'tests' . DS . 'comparisons' . DS;
        parent::setUp();
    }

    public function testExample()
    {
        $result = ...;
        $this->assertSameAsFile('example.php', $result);
    }
}

The above example will compare $result to the contents of the file APP/tests/comparisons/example.php.

A mechanism is provided to write/update test files, by setting the environment variable UPDATE_TEST_COMPARISON_FILES, which will create and/or update test comparison files as they are referenced:

phpunit
...
FAILURES!
Tests: 6, Assertions: 7, Failures: 1

UPDATE_TEST_COMPARISON_FILES=1 phpunit
...
OK (6 tests, 7 assertions)

git status
...
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#   modified:   tests/comparisons/example.php

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 > config/app_local.php <<'CONFIG'
<?php
return [
    'Datasources' => [
        'test' => [
            'datasource' => 'Database/Mysql',
            'host'       => 'localhost',
            'database'   => 'jenkins_test',
            'username'      => 'jenkins',
            'password'   => 'cakephp_jenkins',
            'encoding'   => 'utf8'
        ]
    ]
];
CONFIG

Then uncomment the following line in your config/bootstrap.php file:

//Configure::load('app_local', 'default');

By creating an app_local.php file, you have an easy way to define configuration specific to Jenkins. You can use this same configuration file to override any other configuration files you need on Jenkins.

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 install your dependencies and 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:

# Download Composer if it is missing.
test -f 'composer.phar' || curl -sS https://getcomposer.org/installer | php
# Install dependencies
php composer.phar install
vendor/bin/phpunit --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.