suggestions for unit testing exceptions

Question

Consider a method which might throw an exception with some descriptive text:

if ($someCondition) {
    throw new \Whatever\Exception('dilithium exhausted');
}

And elsewhere in the method is another block that might throw the same exception, but with different text:

if ($anotherCondition) {
    throw new \Whatever\Exception('differentialator exploded');
}

While writing unit tests for this class, you create failure cases so that you can verify that these two exceptions get thrown properly. In these failure cases, do you prefer to:

A) Use @exceptionExpected in the test method's docblock to trap the generic \Whatever\Exception class and subsequently ignore the getMessage() text, assuming you got the right one? (Seems like a bad idea.)

or:

B) Use try/catch and then assert that the caught exception's getMessage() text equals the exact descriptive string you're expecting? (More resilient but it means changing your tests whenever you change your error wording.)

or:

C) Create a separate exception for each error case (e.g., \Whatever\DilithiumException and \Whatever\DifferentialatorException) and then use @exceptionExpected for each one.

I'm currently using B but tending toward C. I'm curious what others are doing in this same scenario. Do you have any guidelines that help you determine, "At what point does an error deserve its own exception class versus a more generic shared one?"

Answer 1

All of the above.

A is great, and I use as much as possible because it is simplest. There is another case when A does not work:

/**
 * @exceptionExpected FooException
 */
test() {
  // code that could throw FooException
  ...
  // purpose of the test that throws of FooException
}

In this case, the test could pass when it should have failed because it didn't even get to what I was testing. A good way to deal with this is to use $this->setExpectedException()

B is great when you might actually use information from the exception. Rather than using the text of the exception message I would prefer to use the code. I have a form validation exception that packages up all the problems encountered in the data into one exception. By extending the exception class it becomes easy to transmit a good deal of information from the internal error state to the external handling code.

C accomplishes the same thing as B, but allows for simplifying the code by relying on more classes. The difference between these two is subtle and I tend to rely on design aesthetic to make the decision.

TL; DR: Use exception codes rather than messages, and design to the use case rather than the unit tests.

Answer 2

PHPUnit also provides @expectedExceptionCode and @expectedExceptionMessage when you need this level of detail. Warning: The latter requires the former.

BTW, I also tend toward A. If I need to express more meaning in the exception, I prefer to create a new exception class. I find the message to be too volatile to be worth testing in most applications.