Mockery
A simple yet flexible PHP mock object framework for unit testing with a human-readable DSL.
What is Mockery?
Mockery is a PHP mock object framework used for unit testing with PHPUnit, PHPSpec, or other testing frameworks. It creates test doubles (mocks, stubs, spies) to simulate real object behavior, allowing developers to isolate tests and design APIs without full implementations. Its core goal is to provide a succinct API with a human-readable Domain Specific Language (DSL) for defining object operations.
PHP developers writing unit tests who need to mock dependencies, particularly those using PHPUnit or PHPSpec for testing. It's ideal for teams seeking a flexible, readable alternative to built-in mocking libraries.
Developers choose Mockery for its simple yet flexible API that clearly defines object interactions using a natural language DSL. It integrates seamlessly with PHPUnit, operates alongside phpunit-mock-objects, and supports advanced features like spies and trait testing, making tests more expressive and maintainable.
Overview
Mockery is a simple yet flexible PHP mock object framework for use in unit testing with PHPUnit, PHPSpec or any other testing framework. Its core goal is to offer a test double framework with a succinct API capable of clearly defining all possible object operations and interactions using a human readable Domain Specific Language (DSL).
Use Cases
Best For
- Creating mock objects for unit testing in PHP applications
- Isolating tests by simulating dependencies with stubs and spies
- Designing class APIs exploratorily without full implementation
- Integrating with PHPUnit for enhanced mocking capabilities
- Verifying method calls and parameters in test assertions
- Testing traits with automatically generated abstract method implementations
Not Ideal For
- Projects relying solely on PHPUnit's built-in mocking with no need for advanced features like spies or trait testing
- Teams working with legacy PHP versions below 5.6 or HHVM 4+, as support is limited
- Environments where minimizing test setup boilerplate is critical, as Mockery requires explicit Mockery::close() calls
- Simple unit tests that only require basic stubs, where the overhead of an external library might not be justified
Pros & Cons
Pros
Mockery uses a natural language API with methods like allows() and expects(), making test definitions clear and maintainable, as emphasized in its philosophy for better readability.
It supports mocks, stubs, and spies through a unified interface, enabling comprehensive simulation of object behavior for enhanced test isolation, as shown in the README examples.
Ships with helpers like MockeryTestCase and traits, allowing easy drop-in use with PHPUnit without disrupting existing test suites, as documented in the PHPUnit Integration section.
Offers unique features like spies for post-call verification and automatic handling of abstract methods in traits, detailed in the Spies and Testing Traits sections of the documentation.
Cons
Tests must explicitly call Mockery::close() in tearDown to verify expectations, adding boilerplate code and risk of missed verifications if forgotten, as noted in the Method Call Expectations section.
The README introduces new syntax (allows/expects) alongside the old shouldReceive, which can lead to inconsistency and a steeper learning curve, as admitted in the alternative syntax documentation.
As an external library, it requires Composer installation and configuration, unlike PHPUnit's built-in mocking, adding complexity for projects with simple mocking needs.
Frequently Asked Questions
Related Projects
PHPUnitThe PHP Unit Testing framework.
ProphecyHighly opinionated mocking framework for PHP 5.3+
CodeceptionFull-stack testing PHP framework
FakerFaker is a PHP library that generates fake data for you
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.