Best way to organize parameters when adding your own asserts to phpUnit

Question

Almost all of the phpUnit asserts are three parameters:

1. Expected result
2. Actual value
3. Optional message to print on failure

(Some, such as assertTrue() , have an implicit expected result, so just have two parameters.)

But, what to do if expected result is not so clean? It may be optional parameters, or it may simply be that there is more to test than one value. As one concrete example, I have assertTimestamp($expected_time,$actual_time,$tolerance=0,$msg='') where tolerance allows for a bit of clock drift. (I also use it to test a created timestamp in a database, to assert that the record was created in the last 30 seconds, ie by a previous function in the current unit test run.)

Does that look reasonable? Ie always push $msg to the end, and keep actual as the second parameter. assertTag has a isHTML flag, which comes last, after $msg .

As a more complex example I've a function that takes a json string for the $actual parameter. It runs json_decode , extracts a few values, and checks each of them. I currently have something like this:

function assertJsonPersonFromDBResponse($name,$gender,$age,$actual,$expectSomething=false,$msg='')

Would you do it differently? I am now wondering if it might be better to squeeze all expected parameters (including optional flags) into the first parameter, which would be an associative array:

function assertJsonPersonFromDBResponse($expected,$actual,$msg='')
...
$this->assertJsonPersonFromDBResponse(array('name'=>'Darren','age'=>21,
    'gender'=>'M','expectSomething'=>true),$s);

That feels cleaner. But is there an existing convention for these kind of situations?

Answer 1

The pattern I see throught the phpunit code base is:

[$expected (if needed)], $actual, $message = '', [other optional paramters]

For exaples take a look at the Framework/Assert.php file

public static function assertEquals(
    $expected, 
    $actual, 
    $message = '', 
    $delta = 0, 
    $maxDepth = 10, 
    $canonicalize = FALSE, 
    $ignoreCase = FALSE
)

Or to be more precisce since $actual can be composed of more than one variable (class & attribute for example):

[$allExpectedParamsIfNeeded], $allActualParams, $message='', [$allOtherSwitches]

For example:

public static function assertAttributeInternalType(
    $expected,
    $attributeName,
    $classOrObject,
    $message = ''
)

or

public static function assertSelectRegExp(
    $selector,
    $pattern,
    $count,
    $actual,
    $message = '',
    $isHtml = TRUE
)

---

General advice for assertions:

Try to minimize the amount of parameters and use more assert functions if possible:

$this->assertStuff($a, $b, true, false, 'Oh dear', 6, true);

is just not readable and confusing to me.

Having

$this->assertStuffForSpecificCaseWithSubcaseSix($a, $b, 'Oh dear'); 

at least is "inline documentation" at every place it's used.