README

When function-mocker is overkill.

Code example

<?php

use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Assert;
use function tad\FunctionMockerLe\define;
use function tad\FunctionMockerLe\defineWithMap;
use function tad\FunctionMockerLe\defineWithValueMap;
use function tad\FunctionMockerLe\defineAll;
use function tad\FunctionMockerLe\undefineAll;

class MyOrmTest extends TestCase {
		
	public function test_query_parameters_are_preserved(){
		// define a non existing function
		define('get_posts', function(array $args){
			Assert::assertEquals(['post_type' => 'book','paginated' => 2, 'posts_per_page' => 6], $args);
			
			return [];
		});
		
		$orm = new MyOrm('book');
		
		$orm->query()
			->page(2)
			->perPage(6)
			->fetch();
	}
	
	public function test_users_cannot_fetch_posts_they_cannot_read(){
		// define a number of functions using a <function> => <callback> map
		defineWithMap([
			'is_user_logged_in' =>  function(){
				return true;
			},
			'get_posts' => function(){
				return[
					['ID' => 1, 'post_title' => 'One'],
					['ID' => 2, 'post_title' => 'Two'],
					['ID' => 3, 'post_title' => 'Three'],
					['ID' => 4, 'post_title' => 'Four']
				];
			},
		'current_user_can' => function($cap, $id){
				// a post ID to 'can' map
				$map  = [
					1 => true,
					2 => true,
					3 => false,
					4 => true
				];
				
				return $map($id);
				}
		]);
		
		$orm = new MyOrm('book');
		
		$books = $orm->query()
			->fetch();
		
		$expected = [
				['ID' => 1, 'post_title' => 'One'],
				['ID' => 2, 'post_title' => 'Two'],
				['ID' => 4, 'post_title' => 'Four']
		];
		
		$this->assertEquals($expected, $books);
	}
	
	public function test_sticky_posts_are_not_prepended_if_not_home_archive_or_tag(){
		// define a number of functions all with the same callback...
		defineAll(['is_home', 'is_archive', 'is_tag'], function(){
			return false;
		});
		define('get_posts', function(array $args){
			Assert::arrayHasKey('ignore_sticky_posts,', $args);
			Assert::assertEquals('1', $args['ignore_sticky_posts']);
		});
		
		$orm = new MyOrm('book');
		$orm->query()->fetch();
		
		// ...and then redefine them
		defineWithValueMap([
			'is_home' => true,
			'is_archive' => false,
			'is_tag' => false
		]);
		
		// redefine as needed
		define('get_posts', function(array $args){
			Assert::arrayNotHasKey('ignore_sticky_posts,', $args);
		});
		
		$orm->query()->fetch();
	}
	
	public function tearDown()
    {
    	// undefine all the functions after each test to avoid test dependencies
    	undefineAll();
	}
}

Installation

Use Composer to require the library in the project

composer require --dev lucatume/function-mocker-le

Why mocking functions? What problem does this solve?

The library provides a lightweight and dependency-free function mocking solution.
The reason one might want to mock a function in the tests is to test any code that depends on a framework based on functions (e.g. WordPress).
The difference between this library and function-mocker is that this will only work when none of the function it defines are defined during the execution; function-mocker will allow instead monkey-patching the functions at runtime even if those are already defined.
Where function mocker depends on the Patchwork library to allow for user-land monkey-patching this library has a minimal code footprint and only provides a handful of functions.
Patchwork or function-mocker should be used if really loading the mocked functions source cannot be avoided in the tests.

Usage

The library core function is the define($function, $callback) one: it defines a function and sets its content to a callback; in its basic usage it allows setting up a mocked function return value in the tests:

public function test_current_user_can(){
	tad\FunctionMockerLe\define('current_user_can', function(){
		return true;
	});
	
	$this->assertTrue(current_user_can('read_posts'));
}

The $callback argument can be a callable of any kind, in this example I'm using the Prophecy mocking engine to use set complex expectations:

public function test_prophecy(){
	$pr = $this->prophesize(User::class);
	$pr->can('read_posts')->shouldBeCalled();
	$pr->can('edit_posts')->shouldNotBeCalled();
	
	tad\FunctionMockerLe\define('current_user_can', [$pr->reveal(), 'can']);
	
	current_user_can('read_posts');
	current_user_can('edit_posts'); // this will trigger a failure: not expected
	current_user_can('read_posts');
}

Relying on basic assertions provided by hte PhpUnit library is another option:

public function test_prophecy(){
	tad\FunctionMockerLe\define('current_user_can', function($cap){
		PHPUnit\Framework\Assert::assertNotEquals('edit_posts', $cap);
	});
	
	current_user_can('read_posts');
	current_user_can('edit_posts'); // this will trigger a failure: not expected
	current_user_can('read_posts');
}

Where function-mocker tries to provide a feature-reach solution to the problem of mocking functions (and more); this project tries to provide just a basic starting point with no opinionated choices about its usage.
The other functions provided by the libary are just sugar wrappers around the define core; see the example and the /tests folder for clarity.
The undefine($function) and undefineAll() methods will "undefine" functions managed by the Function Mocker LE library; in this context "undefine" means that calling the undefined function will trhow an tad\FunctionMockerLe\UndefinedFunctionException.

Tests

To run the tests install the composer dependencies and run PHPUnit:

composer install
vendor/bin/phpunit