Mockery for PHP: Test Doubles Without the Boilerplate

What Mockery Solves for PHP Test Suites

Mockery generates test doubles: objects that stand in for real collaborators during a unit test. The README frames the problem directly, saying doubles are used to offer test isolation, to stand in for objects which do not yet exist, and to allow exploratory design of class APIs without an implementation up front. That last case matters more than it sounds. When you are sketching a repository interface and no concrete class exists yet, you still want to test the service that consumes it. Mockery lets you create the double from the interface and move on.

The intended audience is PHP developers writing unit tests, whether with PHPUnit, PHPSpec, or another framework. The README describes Mockery as a drop-in alternative to PHPUnit's phpunit-mock-objects library and says the two can operate alongside each other. That means you do not have to migrate a whole suite to try it. You can introduce Mockery in one test class and leave the rest alone.

How Mockery Creates Doubles and Verifies Calls

The mechanism is a generated class built at runtime from a type hint, plus a configuration layer that records what you expect to happen. You pass an interface or class name to Mockery::mock, and Mockery produces an object satisfying that type. From there the API splits into two ideas.

A stub supplies canned return values and does not care how often the method is called. The README describes stubs as indirect input to the system under test. An expectation is the opposite direction: it asserts that a method was called, with which arguments, and how many times. The README calls expectations a way to verify indirect output.

The verification step is explicit. Mockery does not check expectations automatically when a test method ends. You call Mockery::close, and the README suggests putting it in PHPUnit's tearDown method. If you forget, expectations go unverified and a test can pass while the interaction you meant to assert never happened. That is the single most common way to get a false green with this library.

The v1 API adds allows() and expects() as alternatives to the older shouldReceive() syntax. The README is explicit that one style is not better or worse than the other, and that shouldReceive remains available. Pick one convention per codebase rather than mixing them, because the two read very differently when scanning a diff.

Installing Mockery and Writing a First Expectation

Mockery is distributed through Packagist, so installation is a Composer command. The README gives this exact line. The --dev flag keeps it out of production installs.

composer require --dev mockery/mockery

After that, the README's PHPUnit integration path is to extend Mockery\Adapter\Phpunit\MockeryTestCase instead of PHPUnit\Framework\TestCase. If your tests already extend a custom base class, the README points to traits in the Mockery\Adapter\Phpunit namespace instead, so you can compose the behavior rather than change your inheritance chain.

A first real use is a repository interface with a stubbed method. The README shows a BookRepository interface with find, findAll and add methods, then creates a double from it:

$double = Mockery::mock(BookRepository::class);
$double->allows()->find(123)->andReturns(new Book());
$book = $double->find(123);

Calling $double->find(123) returns the Book instance. The allows() form sets up a stub, so the call count is not checked. If you want the call to be asserted instead, the README shows the equivalent expectation form, which defaults to exactly once:

$double->expects()->add($book)->twice();

There is also a shortcut that creates the double and configures stubs in one call, which the README demonstrates with an array keyed by method name:

$double = Mockery::mock(BookRepository::class, [
    "findAll" => [new Book(), new Book()],
]);

Whichever form you use, add Mockery::close() to tearDown. Without it, the expects() call above is not verified.

Where Mockery Gets in the Way

The explicit close() requirement is a real failure mode, not a stylistic quirk. A test suite that sets expectations but never closes them reports success on interactions that never occurred. The README addresses this by recommending the tearDown hook, and the MockeryTestCase base class exists partly to make that automatic. If your project has its own base test case and you skip the adapter traits, you own that wiring yourself.

Mockery is also the wrong tool for anything above the unit level. If your test exercises a real database, a real HTTP call, or a full request cycle, a generated double replaces the thing you actually wanted to exercise. The README's own framing is isolation and standing in for objects that do not yet exist, not end-to-end coverage.

There is a cost to the DSL itself. allows() and expects() read well, but a test with several expectations chained across lines becomes a small specification that has to be maintained alongside the production code. When the production method signature changes, the double configuration is another place to update, and PHP will not always point you at it before the test runs.

Finally, version compatibility is a moving part. The repository ships separate PHPUnit configuration files for 9.6, 10.5, 11.5, 12.5 and 13.3, which tells you the project tracks multiple PHPUnit majors at once. That is good for coverage, but it also means the version of Mockery you install should be checked against the PHPUnit version you run.

Mockery Versus PHPUnit's Built-In Mock Objects

The most direct alternative is PHPUnit's own mock object support, which the README explicitly names as the thing Mockery is a drop-in replacement for. The difference is in the API surface and the defaults.

PHPUnit's mocking is configured through methods on the test case, such as createMock, and expectations are built with a method-chain API that leans on PHPUnit's own vocabulary. Mockery separates creation (Mockery::mock) from configuration (allows, expects) and from verification (Mockery::close). That separation is the design bet: you can see at a glance whether a given line supplies a return value or asserts a call.

The practical difference shows up in two places. First, the shortcut form that passes an array of method names to return values has no direct equivalent in PHPUnit's API as described here, and it removes a lot of repetitive lines in repository-style tests. Second, Mockery's verification is not automatic, while PHPUnit's mock expectations are checked as part of the test lifecycle. If you value never thinking about verification wiring, PHPUnit's built-in objects have the edge. If you value a readable declaration of interactions and are willing to add one line to tearDown, Mockery is the more expressive option.

Note that the two can coexist. The README says Mockery can operate alongside phpunit-mock-objects, so the choice is per test, not per project.

Maintenance, Releases and the BSD-3-Clause Licence

The repository is not archived, and the last push was on 2026-09-11. The 1.6.x branch is the default branch, and the most recent releases listed are 1.6.15 on 2026-08-19, 1.6.14 on 2026-08-18 and 1.6.13 on 2026-08-15. Three patch releases inside a week suggests active maintenance on that line, though it also means patch versions move quickly and pinning a version in composer.json is worth considering for reproducible builds.

The licence is BSD-3-Clause, also described in the README as a New BSD License. That is a permissive licence, so using Mockery as a development dependency does not impose copyleft obligations on your application code. The repository includes LICENSE and COPYRIGHT.md files. This is a description of what the repository states, not legal advice; if your organisation has licence policy, route it through whoever handles that.

The upgrade cost is mostly the PHPUnit matrix. The Makefile defines PHP_VERSIONS as 7.3 through 8.6 and PHPUNIT_VERSION as 9.6 through 13.3, with a phpunit-% target that runs php vendor/bin/phpunit --config for each configuration file. That is the project's own test strategy, and it tells you the supported combinations are broad. When you upgrade PHPUnit, check whether your pinned Mockery version supports the new major before you bump both at once.

Editorial conclusion

Adopt Mockery if you write PHP unit tests and want stubs and call expectations expressed in a readable DSL instead of hand-written double classes. Skip it if your tests are mostly integration-level or you already rely on PHPUnit's built-in mock objects and see no gap. Before adopting, verify that the latest 1.6.x release matches the PHP and PHPUnit versions in your project, and check the release history on Packagist to judge how current the branch is.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. mockery/mockery on GitHub
3. Project website
4. README
5. Releases