Merge pull request #88 from bbatsche/method-docs

Method Docs

Author: bbatsche

CHANGELOG.md

@@ -6,7 +6,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased](https://github.com/bbatsche/Verify/compare/3.0.0...master)
 
-## [3.1.0](https://github.com/bbatsche/Verify/compare/3.0.0...3.1.0) - 2022-10-DD
+## [3.1.0](https://github.com/bbatsche/Verify/compare/3.0.0...3.1.0) - 2022-10-07
 
 ### Added
 

docs/attributes.rst

@@ -1,6 +1,8 @@
 .. role:: php(code)
    :language: php
 
+.. _attributes:
+
 ====================
 Attribute Assertions
 ====================

docs/extending.rst

@@ -10,52 +10,27 @@ BeBat/Verify includes almost all the assertions built into PHPUnit, and all the
 Custom Constraint
 =================
 
-Constraints are the building blocks for both PHPUnit and BeBat/Verify's assertions. It is possible to write your own constraints by extending PHPUnit's `Constraint class <https://github.com/sebastianbergmann/phpunit/blob/9.5.20/src/Framework/Constraint/Constraint.php>`__.
+Constraints are the building blocks for both PHPUnit and BeBat/Verify's assertions. It is possible to write your own constraints by extending PHPUnit's `Constraint class <https://github.com/sebastianbergmann/phpunit/blob/9.5.25/src/Framework/Constraint/Constraint.php>`__.
 
-To assert a constraint, pass it to BeBat/Verify's :php:`constraint()` method after a conjunction, just like any other assertion. For example, if you had the package `helmich/phpunit-json-assert <https://packagist.org/packages/helmich/phpunit-json-assert>`__ installed:
+To assert a constraint, pass it to BeBat/Verify's :php:`constraint()` method after a conjunction, just like any other assertion. For example, if you had the package `coduo/php-matcher <https://packagist.org/packages/coduo/php-matcher>`__ installed:
 
 .. code-block:: php
 
-    use Helmich\JsonAssert\Constraint\JsonValueMatches;
-    use Helmich\JsonAssert\Constraint\JsonValueMatchesSchema;
-    use PHPUnit\Framework\Constraint\IsEqual;
+    use Coduo\PHPMatcher\PHPUnit\PHPMatcherConstraint;
 
     use function BeBat\Verify\verify;
 
-    // ...
-
-    $jsonDocument = [
-        'id'          => 1000,
-        'username'    => 'mhelmich',
-        'given_name'  => 'Martin',
-        'family_name' => 'Helmich',
-        'age'         => 27,
-        'hobbies'     => [
-            "Heavy Metal",
-            "Science Fiction",
-            "Open Source Software"
-        ]
-    ];
-
-    $schema = [
-        'type'       => 'object',
-        'required'   => ['username', 'age'],
-        'properties' => [
-            'username' => ['type' => 'string', 'minLength' => 3],
-            'age'      => ['type' => 'number']
-        ]
-    ];
-
-    verify($jsonDocument)->has()->constraint(new JsonValueMatchesSchema($schema))
-        ->and()->constraint(new JsonValueMatches('$.username', new IsEqual('mhelmich')));
-
+    verify('{"name": "Norbert"}')->has()
+        ->constraint(new PHPMatcherConstraint('{"name": "@string@"}'));
 
 .. phpref:: extending.withVerifier
 
 Custom Verifier
 ===============
 
-If there are multiple assertions you want to create, or your assertions involve more than one step, you should create your own *verifier* class. A verifier extends :php:`BeBat\Verify\API\Base` and includes one or more assertion methods. You can inject your verifier to BeBat/Verify by passing its class to :php:`withVerifier()`. BeBat/Verify will instantiate your verifier, passing it the current subject and its name, and then allow you to call your custom assertions from it.
+Using a custom constraint works well if your assertion is a one off and relatively simple. For anything more complicated though you should create your own *verifier* class. A verifier extends :php:`BeBat\Verify\API\Base` and includes one or more assertion methods.
+
+To use your verifier in an assertion chain, pass its class name to :php:`withVerifier()`. BeBat/Verify will instantiate your verifier and pass it the subject and its name. If the constructor requires any additional arguments they can be passed to :php:`withVerifier()`.
 
 The :php:`withVerifier()` method can also be used to switch between the value and file verifiers. For example, suppose you were testing a method that created a file and returned its path. If you wanted to write assertions about both the file contents and its name, you could do so by switching between verifiers with the :php:`withVerifier()` method:
 
@@ -65,7 +40,7 @@ The :php:`withVerifier()` method can also be used to switch between the value an
 
     // ...
 
-    verify($subject->writeFile())->will()->endWith('.log')                     // assertion about the file path
-        ->and()->withVerifier(File::class)->will()->contain('My Log Message'); // assertion about the file contents
+    verify($subject->writeFile())->will()->endWith('.log')      // assertion about the file path
+        ->withVerifier(File::class)->contain('My Log Message'); // assertion about the file contents
 
 For more details about writing your own verifier, see its :ref:`API documentation <verifier-api>`.

docs/index.rst

@@ -14,6 +14,7 @@ BeBat/Verify is a small wrapper for PHPUnit's assertions, intended to make your
    modifiers
    chaining
    attributes
+   methods
 
 .. toctree::
    :maxdepth: 2

docs/methods.rst

@@ -0,0 +1,55 @@
+.. role:: php(code)
+   :language: php
+
+=================
+Method Assertions
+=================
+
+Just like with :ref:`attributes <attributes>`, assertions can be made about an object's methods by adding the method call after :php:`verify()`. You can write assertions about either a method's return value or an exception that the method throws.
+
+Return Values
+=============
+
+A simple example might look like:
+
+.. code-block:: php
+
+    verify($calculator)->add(2, 3)->will()->returnValue()->identicalTo(5);
+
+In :php:`returnValue()`, BeBat/Verify will call :php:`add()` on the :php:`$calculator` object, passing it :php:`2` and :php:`3`, and then cache its result internally. This means you can write multiple assertions about the return value, just like other verifiers, without the method needing to be called again.
+
+If your method name conflicts with part of the verifier API, you can use :php:`method()` and :php:`with()` to explicitly set a method name and arguments:
+
+.. code-block:: php
+
+    verify(new ArrayObject([]))
+        ->method('empty')->will()->returnValue()->true()
+        ->method('count')->will()->returnValue()->identicalTo(0);
+
+The :php:`with()` method can also be used to set up multiple example arguments for a single method:
+
+.. code-block:: php
+
+    verify($calculator)->add()
+        ->with(1, $someValue)->will()->returnValue()->greaterThan($someValue)
+        ->with(0, $someValue)->will()->returnValue()->identicalTo($someValue)
+        ->with(-1, $someValue)->will()->returnValue()->lessThan($someValue);
+
+Exceptions
+==========
+
+If you need to test an exception thrown by your method, you may do so with :php:`throwException()` like so:
+
+.. code-block:: php
+
+    verify($calculator)->divide($someValue, 0)
+        ->will()->throwException()->instanceOf(DivideByZeroException::class);
+
+You can drill into more detail of your exception by using the :php:`withMessage()` and :php:`withCode()` methods:
+
+.. code-block:: php
+
+    verify($calculator)->add(1, 'two')
+        ->will()->throwException()->instanceOf(InvalidArgumentException::class)
+        ->withMessage()->startWith('Invalid argument passed')
+        ->withCode()->identicalTo(2);

docs/verifier-api.rst

@@ -17,7 +17,7 @@ You can add functionality to BeBat/Verify by creating a custom assertion class,
 
       :returns: :php:class:`BeBat\\Verify\\API\\Assert` (extends :php:class:`PHPUnit\\Framework\\Assert`)
 
-      Get an instance of PHPUnit's `Assert class <https://github.com/sebastianbergmann/phpunit/blob/9.5.20/src/Framework/Assert.php>`__. This class exposes much of PHPUnit's functionality for writing tests & assertions, such as causing a test to fail if an error occurs.
+      Get an instance of PHPUnit's `Assert class <https://github.com/sebastianbergmann/phpunit/blob/9.5.25/src/Framework/Assert.php>`__. This class exposes much of PHPUnit's functionality for writing tests & assertions, such as causing a test to fail if an error occurs.
 
    .. php:method:: constraintFactory()
 
@@ -74,7 +74,7 @@ You can add functionality to BeBat/Verify by creating a custom assertion class,
 
       :returns: :php:`mixed`
 
-      Resolve the actual value of the subject. If the subject is an attribute of a class, this method will resolve the actual value under test and cache it locally.
+      Resolve the actual value of the subject. You may override this method in your verifier if there is some additional logic to resolving your subject's value, such as reading the result from an object property or function call.
 
    .. php:method:: resetParams()
 

src/API/Method.php

@@ -128,7 +128,7 @@ protected function callMethod()
             // @phpstan-ignore-next-line
             return $this->actual->{$this->methodName}(...$this->methodArgs);
         }
-        if ($reflector->hasMethod('__callStatic')) {
+        if (\is_string($this->actual) && $reflector->hasMethod('__callStatic')) {
             $this->methodCalled = true;
 
             // @phpstan-ignore-next-line