Merge pull request #15 from sirbrillig/add/do-arrays-match

Add helper function `do_arrays_match()`

API.md

@@ -95,6 +95,13 @@ $value = wp_update_post( 'hello' );
 $this->assertEquals( 'hello', $value );
 ```
 
+- `do_arrays_match( $a, $b )`: Compare two arrays allowing usage of `match_array()`.
+
+```php
+$array = [ 'baz' => 'boo', 'foo' => 'bar' ];
+$this->assertTrue( \Spies\do_arrays_match( $array, \Spies\match_array( [ 'foo' => 'bar' ] ) ) );
+```
+
 # Spy
 
 ### Static methods

README.md

@@ -379,6 +379,15 @@ a spy was actually called with:
 
 See the [API document](API.md) for the full list of custom assertions available.
 
+## Assertion Helpers
+
+For any assertion, even those not involving Spies or Stubs, it can be helpful to compare partial arrays in the same manner as `match_array()`. You can use the helper function `do_arrays_match()` to do this:
+
+```php
+$array = [ 'baz' => 'boo', 'foo' => 'bar' ];
+$this->assertTrue( \Spies\do_arrays_match( $array, \Spies\match_array( [ 'foo' => 'bar' ] ) ) );
+```
+
 # Spying and Mocking existing functions
 
 PHP does not allow mocking existing functions. However, there is a library called [Patchwork](http://patchwork2.org/) which allows this. If that library is loaded, it will be used by Spies. The library must be loaded *before* Spies. One way to do this is to use a test bootstrap file.

src/Spies/Helpers.php

@@ -39,4 +39,8 @@ private static function do_vals_match( $a, $b ) {
 		}
 		return false;
 	}
+
+	public static function do_arrays_match( $a, $b ) {
+		return self::do_vals_match( $a, $b );
+	}
 }

src/Spies/functions.php

@@ -54,3 +54,7 @@ function match_array( $array ) {
 function passed_arg( $index ) {
 	return new \Spies\PassedArgument( $index );
 }
+
+function do_arrays_match( $array1, $array2 ) {
+	return \Spies\Helpers::do_arrays_match( $array1, $array2 );
+}

tests/HelpersTest.php

@@ -0,0 +1,28 @@
+<?php
+
+class HelpersTest extends \Spies\TestCase {
+	public function test_do_arrays_match_returns_true_if_arrays_are_the_same() {
+		$array1 = [ 'a', 'b', 'c' ];
+		$array2 = [ 'a', 'b', 'c' ];
+		$this->assertTrue( \Spies\do_arrays_match( $array1, $array2 ) );
+	}
+
+	public function test_do_arrays_match_returns_false_if_arrays_are_different() {
+		$array1 = [ 'a', 'b', 'c' ];
+		$array2 = [ 'b', 'c' ];
+		$this->assertFalse( \Spies\do_arrays_match( $array1, $array2 ) );
+	}
+
+	public function test_do_arrays_match_returns_true_if_using_match_array_and_arrays_match() {
+		$array1 = [ 'a', 'b', 'c' ];
+		$array2 = [ 'b', 'c' ];
+		$this->assertTrue( \Spies\do_arrays_match( $array1, \Spies\match_array( $array2 ) ) );
+	}
+
+	public function test_do_arrays_match_returns_false_if_using_match_array_and_arrays_differ() {
+		$array1 = [ 'a', 'b', 'c' ];
+		$array2 = [ 'd', 'c' ];
+		$this->assertFalse( \Spies\do_arrays_match( $array1, \Spies\match_array( $array2 ) ) );
+	}
+}
+

tests/StubTest.php

@@ -61,6 +61,15 @@ public function test_stub_when_called_with_sets_a_conditional_return_value_on_th
 		$this->assertEquals( 6, test_stub( 'bar' ) );
 	}
 
+	public function test_stub_when_called_with_match_array_sets_a_conditional_return_value_on_the_stub() {
+		\Spies\mock_function( 'test_stub' )->will_return( 4 );
+		\Spies\mock_function( 'test_stub' )->when_called->with( \Spies\match_array( [ 'type' => 'Bokoblin' ] ) )->will_return( 5 );
+		\Spies\mock_function( 'test_stub' )->when_called->with( \Spies\match_array( [ 'type' => 'Moblin' ] ) )->will_return( 6 );
+		$this->assertEquals( 5, test_stub( [ 'name' => 'Bobo', 'type' => 'Bokoblin' ] ) );
+		$this->assertEquals( 6, test_stub( [ 'name' => 'Grup', 'type' => 'Moblin' ] ) );
+		$this->assertEquals( 4, test_stub( [ 'name' => 'Corb', 'type' => 'Lizafos' ] ) );
+	}
+
 	public function test_stub_with_conditional_returns_will_return_unconditional_value_when_called_with_unexpected_parameters() {
 		\Spies\mock_function( 'test_stub' )->when_called->with( 'foo' )->will_return( 5 );
 		\Spies\mock_function( 'test_stub' )->will_return( 7 );