Merge pull request #6 from FriendsOfCake/ad-compare-trait

Add a compare trait for html, json and xml comparisons

.editorconfig

@@ -0,0 +1,20 @@
+# .editorconfig
+# http://editorconfig.org/
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.html]
+indent_size = 4
+
+[*.php]
+indent_size = 4
+
+[*.xml]
+indent_size = 4

.gitignore

@@ -1,2 +1,3 @@
-vendor
+composer.lock
 phpunit.xml
+vendor

.travis.yml

@@ -0,0 +1,33 @@
+language: php
+
+php:
+  - 7.0
+  - 7.1
+  - 7.2
+
+env:
+  global:
+    - DEFAULT=1
+
+matrix:
+  fast_finish: true
+
+  include:
+    - php: 7.0
+      env: PHPCS=1 DEFAULT=0
+
+    - php: 7.0
+      env: PHPSTAN=1 DEFAULT=0
+
+before_script:
+  - composer install --prefer-dist --no-interaction
+  - if [[ $PHPCS = 1 ]]; then composer require cakephp/cakephp-codesniffer:dev-master; fi
+  - if [[ $PHPSTAN = 1 ]]; then composer require phpstan/phpstan:^0.8; fi
+
+script:
+  - if [[ $DEFAULT = 1 ]]; then vendor/bin/phpunit; fi
+  - if [[ $PHPCS = 1 ]]; then vendor/bin/phpcs -p --extensions=php --standard=vendor/cakephp/cakephp-codesniffer/CakePHP src/; fi
+  - if [[ $PHPSTAN = 1 ]]; then vendor/bin/phpstan analyse -l 5 src; fi
+
+notifications:
+  email: false

README.md

@@ -4,7 +4,8 @@ This package contains support traits to ease unit testing.
 
 ## Installing via composer
 
-You should install this package into your project using composer. To do so you can add the following to your composer.json file:
+You should install this package into your project using composer. To do so you
+can add the following to your composer.json file:
 
 ``` json
 "require-dev": {
@@ -15,14 +16,16 @@ You should install this package into your project using composer. To do so you c
 
 ## Traits
 
-The usage of these traits requires at least PHP 5.4. At this point there are two traits:
+The usage of these traits requires at least PHP 5.4. At this point there are
+two traits:
 
 1. [`AccessibilityHelperTrait`](#accessibilityhelpertrait) : Gain access protected properties and methods.
 2. [`CounterHelperTrait`](#counterhelpertrait) : Uses counters to help with the order of expectations.
 
 ### AccessibilityHelperTrait
 
-This trait gains you access to protected properties and methods. You don't need of a new class with pass-through methods. It uses reflection to achieve this.
+This trait gains you access to protected properties and methods. You don't need
+of a new class with pass-through methods. It uses reflection to achieve this.
 
 #### Setup
 
@@ -32,7 +35,9 @@ Add the trait at the top of your test case:
 use \FriendsOfCake\TestUtilities\AccessibilityHelperTrait;
 ```
 
-Now that you have the trait you need to set which object you want to access. You can do this globally for the entire test in `setUp()` or in your test methods:
+Now that you have the trait you need to set which object you want to access.
+You can do this globally for the entire test in `setUp()` or in your test
+methods:
 
 ``` php
 $object = new ObjectIAmGoingToTest();
@@ -65,6 +70,51 @@ $actual = $this->callProtectedMethod('_myMethod', $parameters, $object);
 $this->assertEquals($expected, $actual);
 ```
 
+### CompareTrait
+
+This trait helps with comparing test results as string
+
+#### Setup
+
+Add the trait at the top of your test case and define the `_compareBasePath`
+property so the trait knows where to look for comparison files:
+
+``` php
+...
+use \FriendsOfCake\TestUtilities\CompareTrait;
+
+class MyTest extends TestCase
+{
+    use CompareTrait;
+
+    public function setUp()
+    {
+        parent::setUp();
+        $this->_compareBasePath = 'comparisons/MyTest/';
+    }
+}
+
+#### Usage
+
+Each of the methods acts similar to the core `assertSameAsFile` method:
+
+```
+public function testExample()
+{
+    $html = '<p>Some html</p>';
+    $xml = '<?xml version="1.0" encoding="UTF-8"?><thing>...</thing>';
+    $json = ['actually' => 'this is an array'];
+
+    $this->assertHtmlSameAsFile('some.html', $html);
+    $this->assertXmlSameAsFile('some.xml', $xml);
+    $this->assertJsonSameAsFile('some.json', $json);
+}
+```
+
+See [Cake's docs](https://book.cakephp.org/3.0/en/development/testing.html#comparing-test-results-to-a-file)
+for more details on usage of `assertSameAsFile` on which these methods are
+based.
+
 ### CounterHelperTrait
 
 This trait helps with defining expectations that are order specific.
@@ -81,7 +131,8 @@ That's it.
 
 #### Single mock objects
 
-Usually you would do something similar to this to set orders for your mock objects:
+Usually you would do something similar to this to set orders for your mock
+objects:
 
 ``` php
 $mock->expects($this->at(0))
@@ -95,41 +146,45 @@ $mock->expects($this->at(1))
     ->will($this->returnValue('mySecondReturnValue'));
 ```
 
-Instead this trait implements a `CounterHelperTrait::next()` method. It will track the indices for you, so you can easily switch calls or add some later, without having to change them. Example:
+Instead this trait implements a `CounterHelperTrait::next()` method. It will
+track the indices for you, so you can easily switch calls or add some later,
+without having to change them. Example:
 
 ``` php
-$mock->expects($this->next()) // = $this->at(0)
+$mock->expects($this->nextCounter()) // = $this->at(0)
     ->method('myMethod')
     ->with('myParameter')
     ->will($this->returnValue('myFirstReturnValue'));
 
-$mock->expects($this->next()) // = $this->at(1)
+$mock->expects($this->nextCounter()) // = $this->at(1)
     ->method('myMethod')
     ->with('myParameter')
     ->will($this->returnValue('mySecondReturnValue'));
 ```
 
 #### Multiple mock objects
 
-If you have multiple mock objects you need to use multiple independent counters. For this to work you need to identify which counter you want to use by passing an object (or a string):
+If you have multiple mock objects you need to use multiple independent
+counters. For this to work you need to identify which counter you want to use
+by passing an object (or a string):
 
 ``` php
-$mock1->expects($this->next($mock1)) // = $this->at(0)
+$mock1->expects($this->nextCounter($mock1)) // = $this->at(0)
     ->method('myMethod')
     ->with('myParameter')
     ->will($this->returnValue('myFirstReturnValue'));
 
-$mock2->expects($this->next($mock2)) // = $this->at(0)
+$mock2->expects($this->nextCounter($mock2)) // = $this->at(0)
     ->method('myMethod')
     ->with('myParameter')
     ->will($this->returnValue('myFirstReturnValue'));
 
-$mock1->expects($this->next($mock1)) // = $this->at(1)
+$mock1->expects($this->nextCounter($mock1)) // = $this->at(1)
     ->method('myMethod')
     ->with('myParameter')
     ->will($this->returnValue('mySecondReturnValue'));
 
-$mock2->expects($this->next($mock2)) // = $this->at(1)
+$mock2->expects($this->nextCounter($mock2)) // = $this->at(1)
     ->method('myMethod')
     ->with('myParameter')
     ->will($this->returnValue('mySecondReturnValue'));

composer.json

@@ -25,10 +25,12 @@
             "FriendsOfCake\\TestUtilities\\Test\\": "tests"
         }
     },
-    "require": {
-        "php": ">=5.4"
-    },
     "require-dev": {
-        "phpunit/phpunit": "~4.0"
+        "phpunit/phpunit": "^5.7.14|^6.0"
+    },
+    "require": {
+        "php": "^5.6 || ^7.0",
+        "cakephp/cakephp": "^3.4",
+        "cakephp/cakephp-codesniffer": "dev-master"
     }
 }