Deprecate TestCase::getMockForTrait()

[sebastianbergmann]

PHPUnit can automatically generate test stubs and mock objects (test doubles) based on interfaces and 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 getMockForTrait() exist, but not all of them offer the same clear separation between test double and mock object. For instance, no method named getStubForTrait() exists. Such an inconsistency can lead to confusion.

The getMockForTrait() method returns a mock object for an otherwise empty class that uses a specified trait. All abstract methods of the given trait are mocked. This allows for testing the concrete methods of a trait.

Having to use getMockForTrait() 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::getMockForTrait() 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

[MegaChriz]

To convert existing tests without requiring a redesign of your code, adding a class that implements the trait and mock that seems to work.

Before:

namespace MyProject\Tests;

use PHPUnit\Framework\TestCase;

class MyTest extends TestCase {

  public function test() {
    $mock = $this->getMockForTrait('\MyProject\MyTrait');
  }

}

After:

namespace MyProject\Tests;

use MyProject\MyTrait;
use PHPUnit\Framework\TestCase;

class MyTest extends TestCase {

  public function test() {
    $mock = $this->createMock(MyTraitMock::class);
  }

}

/**
 * Mock for MyTrait.
 */
class MyTraitMock {

  use MyTrait;

}

[websmurf]

Or a bit more dynamic with the help of an anonymous class:

    /**
     * Create an anonymous class for the provided trait.
     *
     * @param trait-string $traitName Name of the trait to create a mock for.
     */
    public function createMockForTrait(string $traitName)
    {
        return eval('return new class { use ' . $traitName . '; };');
    }

[ralflang]

I think createMock won't like being handed an anonymous class. It wants a string class name.