Deprecate TestCase::getMockForAbstractClass()

[sebastianbergmann]

PHPUnit can automatically generate test stubs and mock objects (test doubles) based on interfaces and classes.

When it comes to doubling classes, there are limitations:

• final, private, and static methods cannot be doubled; they retain their original behavior except for static methods which will be replaced by a method throwing an exception
• Enumerations (enum) are final classes and therefore cannot be doubled
• readonly classes cannot be extended by classes that are not readonly and therefore cannot be doubled

Not only because of the limitations mentioned above, but also to improve your software design, PHPUnit's documentation recommends to favour the doubling of interfaces over the doubling of classes.

For quite a while, PHPUnit has offered the createStub() and createMock() methods for creating test stubs and mock objects with best practice defaults. Furthermore, alternatives such as getMockForAbstractClass() exist, but not all of them offer the same clear separation between test double and mock object. For instance, no method named getStubForAbstractClass() exists. Such an inconsistency can lead to confusion.

As its name suggests, the getMockForAbstractClass() method can be used to create a mock object for an abstract class: a mock object where all abstract methods of the original class are implemented in such a way that they can be configured to return a specified value, for instance, or to expect an invocation.

Having to use getMockForAbstractClass() to test something is almost always a code smell: something is not quite right with the software design of the system-under-test.

To promote better software design, improve the readability of test code, and to reduce complexity inside PHPUnit's test double functionality, TestCase::getMockForAbstractClass() will be deprecated and then removed:

• soft deprecation in PHPUnit 10.1 (add @deprecated annotation to the method declaration)
• deprecation in PHPUnit 11 (using the method will trigger a deprecation)
• removal in PHPUnit 12

[klausi]

Interesting! Unfortunately neither the docs nor the issue here mention a best practice what to use instead of getMockForAbstractClass().

We often need to test abstract classes outside our control (for example from 3rd party libraries), what is the best approach to do instead?

[klausi]

To answer my own question: you need to specify now all unimplemented methods of the abstract class, which is a bit annoying but not too bad.

Simplified example from Drupal's graphql module:

abstract class SdlSchemaExtensionPluginBase implements SchemaExtensionPluginInterface {}

interface SchemaExtensionPluginInterface {
  public function registerResolvers(ResolverRegistryInterface $registry);
}

Previous test code:

$extensions['graphql_alterable_schema_test'] = $this->getMockBuilder(SdlSchemaExtensionPluginBase::class)
  ->disableOriginalConstructor()
  ->onlyMethods(['getBaseDefinition', 'getExtensionDefinition'])
  ->getMockForAbstractClass();

New test code:

$extensions['graphql_alterable_schema_test'] = $this->getMockBuilder(SdlSchemaExtensionPluginBase::class)
  ->disableOriginalConstructor()
  ->onlyMethods(['getBaseDefinition', 'getExtensionDefinition', 'registerResolvers'])
  ->getMock();

Which gets me thinking now that we could probably mock the interface instead?

[klausi]

Welp, I was right! Because we were smart and built on interfaces anyway (yay interfaces!) we can just mock the interface and the test keeps working:

$extensions['graphql_alterable_schema_test'] = $this->getMockBuilder(SchemaExtensionPluginInterface::class)
  ->getMock();

[klausi]

So the best practice is to replace getMockForAbstractClass() with getMock(). 3 examples: drupal-graphql/graphql#1415