Upgrading Yii2 to use Codeception 4.1.6+

The upgrade process from earlier versions of Codeception for Yii2 is very easy.

Upgrading Yii2 to use Codeception 4.1.6+

Codeception is a PHP testing framework that hooks nicely into Yii2.  I've been using Codeception in eVitabu for a while but hadn't updated to the latest version.  This blog post describes how you can do that with Composer.

Codeception version 4 was announced in December 2019.  I was still using version 2 so was two major releases behind.

Why test anyway?

Automated testing is incredibly useful for identifying if the code changes you've just made have broken something.  Tests can also confirm if functionality you think you've built in to your application is actually present.  I became convinced that automated testing was valuable when I ran a set of tests against eVitabu, only to find anonymous access was possible to some parts of the system.  Clearly that wasn't desired!

Screenshot of a terminal window showing the output of automated user tests.  Every test passes.
Running tests against my user functions - all passing is good :) .

I've only worked with Codeception, so can't compare it to other testing frameworks, but I find it nice to work with and the output is very clear.  The screenshot above shows the results of my tests in an easy to understand fashion.  If a test fails then I can look at the HTML output from the point of failure to help me identify the problem.

Update other components first

Before going any further I'd recommend running composer update to update other packages used by your project.  That way our steps later on will not fold in updates you're not expecting.

Warnings from Composer

During package updates with Composer I'd seen warnings about the Codeception package I was using for a while:

Package codeception/base is abandoned, you should avoid using it. No replacement was suggested.

This was a useful nudge to get things sorted.

Removing the old version

The first thing to do was to remove the old version of Codeception, in my case version 2.something.  I'm using Composer to manage my packages so removed codeception/base via the package manager:

$ cd /path/to/project
$ composer remove codeception/base
Using Composer to remove the old package.

Add Codeception version 4

Fortunately there's a Yii2 module for Codeception and installing it pulls in any dependencies required.  Again we use Composer to perform the changes, although I started by editing the require section in my composer.json to require the new Codeception module codeception/module-yii2:

"require": {
        "php": ">=7.3",
        "yiisoft/yii2": "~2.0.5",
        "yiisoft/yii2-bootstrap": "~2.0.0",
        "yiisoft/yii2-swiftmailer": "~2.0.0",
        "bizley/migration": "^2.2",
        "squizlabs/php_codesniffer": "^3.1",
        "yiisoft/yii2-bootstrap4": "^2.0",
        "rmrevin/yii2-fontawesome": "~3.5",
        "codeception/module-yii2": "^1.0.0"
require section of composer.json.

You'll note that I've added codeception/module-yii2 as the last package in my require section.  Next we use Composer to install the changes:

$ cd /path/to/project
$ composer update

(Note this will pull in additional package updates, so you should run an update before starting your Codeception upgrade.)

Post installation upgrade steps

There's a handy upgrade script to migrate you to version 4 and you need to run this after Composer has installed the required modules.  The upgrade script will add required changes to composer.json for you, just run vendor/bin/codecept init upgrade4 and follow the prompts.

$ vendor/bin/codecept init upgrade4
 Welcome to Codeception v4 Upgrade wizard!

Codeception is maintained since 2011, is free & open-source.
To make it better we need your feedback on it!

Please take a minute and fill in a brief survey:

? Did you fill in the survey? (y/n) n
 Adding codeception/module-filesystem for Filesystem to composer.json
 Adding codeception/module-asserts for Asserts to composer.json
2 new packages added to require
? composer.json updated. Do you want to run "composer update"? (y/n) y

Troubleshooting composer update post upgrade

When I ran composer update it failed due to composer.json not meeting the correct schema (rules).  In my case it appears init upgrade4 changed the value of support to be an array:

  "./composer.json" does not match the expected JSON schema:  
   - support : Array value found, but an object is required 

To fix, check the component being referenced (support in this case) and make the relevant change.  For me this meant changing

  "support": [],

back to


After that I could run composer update without issues.

Changes to your tests

Dependant on what you're using in your tests you may need to make changes.  I leave that as an exercise for the reader.

Banner image: the Codeception logo