Exception assertion tweaks

[theofidry]

Two common use cases I encounter with the exception expectations API is:

Exact message check instead of partial

As of now expectExceptionObject() uses expectExceptionMessage() which uses the ExceptionMessageIsOrContains() constraint. It would be nice to have the option for both to make it stricter.

Ideally, we could have expectExceptionMessage() + expectExceptionMessageIsOrContains() and make the former stricter, but that's more annoying BC wise. But either way, for expectExceptionObject() this would require an additional parameter at least...

I'm a bit conflicted because I do like to use expectExceptionObject(), but if there is not choice but to use the underlying method and use expectExceptionMessageIs() or however a new method would be called, so be it.

Exact exception instance.

Sometimes it makes more sense to check that the exception thrown is the exact one previously configured:

$exception = new FancyExceptionType();

// reset of the setup

$this->expectExceptionIdentical($exception);

// act

Kinda lost at what the name should be there but that's the idea.

[sebastianbergmann]

The only comment I can give is that I never used expectExceptionObject(), regret adding it, and would prefer deprecating/removing it then changing (or adding to) it.

[theofidry]

Interesting, personally I primarily use it, because I like to test not only the exception class but the message too. So I end up with something like that:

#[DataProvider('inputProvider')]
function test_it_does_something(string $input, string|Exception $expected): void {
  if ($expected instanceof Exception) {
    $this->expectExceptionObject($expected);
  }

  $actual = f($input);

  if (!$expected instanceof Exception) {
    self::assertSame($expected, $actual);
  }
}

I'm not a huge fan of the form of the failure branches, those if statements are a bit ugly, but I really like being able to provide all the scenarios in one data provider.

Sometimes if the success and failure path are too different and it gets too confusing, I still do one data provider, but I then introduce a success & failure provider which are basically filtering the primary one. It's more boilerplate though hence not my default.