README

Hammock is a stand-alone mocking library for the Hack language. At its core, it uses fb_intercept, which can intercept any function and change its behavior. Hammock aims to provide APIs for mocking public methods and global functions with ease. While it is also possible to mock protected and private methods, it is generally frowned upon to do so. Here are some of Hammock's key features:

Block-scoped mocking, which automatically restores the original behavior of the mocked function at the end of the block.
Tracking the intercepted arguments and number of calls into mocked functions.
Spying on functions without altering their behavior.

Installation

composer require --dev quizlet/hammock

Usage

Mock an object's method:

$dog = new Dog();

$dog->fetch('ball') === 'ball'; // true

using Hammock\mock_object_method($dog, 'fetch', $args ==> 'frisbee');

$dog->fetch('ball') === 'frisbee'; // true

Same thing, but using a block scope:

$dog = new Dog();

using (Hammock\mock_object_method($dog, 'fetch', $args ==> 'frisbee')) {
	$dog->fetch('ball') === 'frisbee'; // true
} // Original behavior is restored at the end of the `using` block.

$dog->fetch('ball') === 'ball'; // true

Use the intercepted arguments and get the number of calls:

$dog = new Dog();

using $fetchMock = Hammock\mock_object_method($dog, 'fetch', $args ==> {
	// Each intercepted argument must be type-asserted.
	// We recommend https://github.com/hhvm/type-assert for this.
	$arg = strval($args[0]);

	if ($arg === 'ball') {
		return 'frisbee';
	}
	
	return $arg;
});

$dog->fetch('ball') === 'frisbee'; // true
$dog->fetch('bone') === 'bone'; // true

// The arguments for each intercepted call can be retrieved later.
$fetchMock->getArgsForCall(0) === vec['ball']; // true
$fetchMock->getArgsForCall(1) === vec['bone']; // true

// The number of calls from the time the function was mocked.
$fetchMock->getNumCalls() === 2; // true

Spy on an object's method without altering its behavior:

$dog = new Dog();

using $fetchSpy = Hammock\spy_object_method($dog, 'fetch');

$dog->fetch('ball') === 'ball'; // true

$fetchSpy->getNumCalls() === 1; // true

Mock a class' method when no instance is available:

using Hammock\mock_class_method(Ball::class, 'bounce', $args ==> false);

Ball::bounce() === false; // true

The full API documentation can be found in MAIN_API.md.

Advanced use cases can be found in ADVANCED.md.

Contributing

If you ever wanted to contribute to an open-source project, now is the chance! Please read CONTRIBUTING.md to understand the process for submitting a pull request.

Acknowledgements

Thanks to the following people who have contributed to Hammock:

Contact

Please reach out to riya.dashoriya@quizlet.com if you have any questions.

quizlet / hammock

Maintainers

Details