PHPUnit Migration Hints

Migrating your test cases to PHPUnit 3.7 will hopefully be a fairly pain free transition. However, there are a few known differences between test cases under PHPUnit and SimpleTest.

Differences between SimpleTest

There are a number of differences between SimpleTest and PHPUnit. The following is an attempt to list the most frequently encountered differences.

startCase() and endCase()

These methods are no longer supported. Use the static methods PHPUnit provides: setupBeforeClass and tearDownAfterClass.

start(), end(), before() and after()

These methods were part of SimpleTest’s test case initialization. start() and end() have no replacements. You can use setUp() and tearDown() to replace before() and after().

setUp() and tearDown()

In the past the methods setUp, tearDown, startTest and endTest where supported, and caused confusion as they looked almost like the same thing but in some cases you should use one or the other.

In the new CakePHP test suite, it is recommended to use only setUp and tearDown. The methods startTest and endTest are still supported but are deprecated.

getTests

The method getTests is no longer supported. You can use filters instead. The web test runner now takes an additional query string parameter that allows you to specify a basic regular expression. This regular expression is used to restrict the methods that are run:

e.g. filter=myMethod

Only tests containing the string myMethod will be run on the next refresh. The cake test shell also supports a –filter option to filter methods.

Assertion methods

Many of the assertion methods have slightly different names between PHPUnit and SimpleTest. Where possible CakeTestCase provides a wrapper for the SimpleTest method names. These compatibility wrappers will be removed in 2.1.0. The following methods will be affected.

  • assertEqual -> assertEquals
  • assertNotEqual -> assertNotEquals
  • assertPattern -> assertRegExp
  • assertIdentical -> assertSame
  • assertNotIdentical -> assertNotSame
  • assertNoPattern -> assertNotRegExp
  • assertNoErrors -> no replacement
  • expectError -> setExpectedException
  • expectException -> setExpectedException
  • assertReference -> assertSame
  • assertIsA -> assertType

Some methods take their arguments in different orders, be sure to check the methods you are using when updating them.

Mock expectations

Mock objects are dramatically different between PHPUnit and SimpleTest. There is no compatibility wrapper between them. Updating mock object usage can be a painful process but we hope the following tips help you in your migration. It’s highly recommended you familiarize yourself with the PHPUnit Mock object documentation.

Replacing method calls

The following regular expressions should help update some of your more straightforward mock object expectations.

Replace expectOnce() no params
expectOnce\(([^\)]+)\);
expects(\$this->once())->method($1);
Replace expectOnce() with params
expectOnce\(([^,]+), array\((.+)\)\);
expects(\$this->once())->method($1)->with($2);
Replace expectAt()
expectAt\((\d+), (.+), array\((.+)\)\);
expects(\$this->at($1))->method($2)->with($3);
Replace expectNever
expectNever\(([^\)]+)\);
expects(\$this->never())->method($1);
Replace setReturnValue
setReturnValue\(([^,]+), (.+)\);
expects(\$this->once())->method($1)->will($this->returnValue($2));
Replace setReturnValueAt
setReturnValueAt((\d+), ([^,]+), (.+));
expects(\$this->at($1))->method($2)->will($this->returnValue($3));

Group tests

Group tests have been removed as PHPUnit treats individual test cases and test suites as composable entities in the runner. You can place group tests inside the cases directory and use PHPUnit_Framework_TestSuite as a base class. An example Testsuite would look like:

class AllJavascriptHelpersTest extends PHPUnit_Framework_TestSuite {

/**
 * Suite define the tests for this suite
 *
 * @return void
 */
    public static function suite() {
        $suite = new PHPUnit_Framework_TestSuite('JsHelper and all Engine Helpers');

        $helperTestPath = CORE_TEST_CASES . DS . 'View' . DS . 'Helper' . DS;
        $suite->addTestFile($helperTestPath . 'JsHelperTest.php');
        $suite->addTestFile($helperTestPath . 'JqueryEngineHelperTest.php');
        $suite->addTestFile($helperTestPath . 'MootoolsEngineHelperTest.php');
        $suite->addTestFile($helperTestPath . 'PrototypeEngineHelperTest.php');
        return $suite;
    }
}

TestManger no longer has methods to add tests to group tests either. It is recommended that you use the methods PHPUnit offers.