BossBey File Manager
PHP:
7.4.33
OS:
Linux
User:
root
Root
/
home
/
vssraipur
/
public_html
/
pdf
/
vendor
/
phake
/
phake
/
docs
/
_build
/
html
📤 Upload
📝 New File
📁 New Folder
Close
Editing: method-parameter-matchers.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" ""> <html xmlns=""> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Method Parameter Matchers — Phake - PHP Mocking Framework v1.0.3 documentation</title> <link rel="stylesheet" href="_static/default.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '', VERSION: '1.0.3', COLLAPSE_MODINDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <link rel="top" title="Phake - PHP Mocking Framework v1.0.3 documentation" href="index.html" /> <link rel="next" title="Configuration" href="configuration.html" /> <link rel="prev" title="Answers" href="answers.html" /> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="configuration.html" title="Configuration" accesskey="N">next</a> |</li> <li class="right" > <a href="answers.html" title="Answers" accesskey="P">previous</a> |</li> <li><a href="index.html">Phake - PHP Mocking Framework v1.0.3 documentation</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="method-parameter-matchers"> <span id="method-parameter-matchers-section"></span><h1>Method Parameter Matchers<a class="headerlink" href="#method-parameter-matchers" title="Permalink to this headline">¶</a></h1> <p>The verification and stubbing functionality in Phake both rely heavily on parameter matching to help the system understand exactly which calls need to be verified or stubbed. Phake provides several options for setting up parameter matches.</p> <p>The most common scenario for matching parameters as you use mock objects is matching on equal variables For this reason the default matcher will ensure that the parameter you pass to the mock method is equal (essentially using the ‘==’ notation) to the parameter passed to the actual invocation before validating the call or returning the mocked stub. So going back to the card game demonstration from the introduction. Consider the following interface:</p> <div class="highlight-php"><div class="highlight"><pre><span class="x">interface DealerStrategy</span> <span class="x">{</span> <span class="x"> public function deal(CardCollection $deck, PlayerCollection $players);</span> <span class="x">}</span> </pre></div> </div> <p>Here we have a <tt class="docutils literal"><span class="pre">deal()</span></tt> method that accepts two parameters. If you want to verify that <tt class="docutils literal"><span class="pre">deal()</span></tt> was called, chances are very good that you want to verify the the parameters as well. To do this is as simple as passing those parameters to the <tt class="docutils literal"><span class="pre">deal()</span></tt> method on the <tt class="docutils literal"><span class="pre">Phake::verify($deal)</span></tt> object just as you would if you were calling the actual <tt class="docutils literal"><span class="pre">deal()</span></tt> method itself. Here is a short albeit silly example:</p> <div class="highlight-php"><div class="highlight"><pre><span class="x">//I don't have Concrete versions of</span> <span class="x">// CardCollection or PlayerCollection yet</span> <span class="x">$deck = Phake::mock('CardCollection');</span> <span class="x">$players = Phake::mock('PlayerCollection');</span> <span class="x">$dealer = Phake::mock('DealerStrategy');</span> <span class="x">$dealer->deal($deck, $players);</span> <span class="x">Phake::verify($dealer)->deal($deck, $players);</span> </pre></div> </div> <p>In this example, if I were to have accidentally made the call to <tt class="docutils literal"><span class="pre">deal()</span></tt> with a property that was set to null as the first parameter then my test would fail with the following exception:</p> <div class="highlight-python"><pre>Expected DealerStrategy->fooWithArgument(equal to <object:CardCollection>, equal to <object:PlayerCollection>) to be called exactly 1 times, actually called 0 times. Other Invocations: PhakeTest_MockedClass->fooWithArgument(<null>, equal to <object:PlayerCollection>)</pre> </div> <p>Determining the appropriate method to stub works in exactly the same way.</p> <p>There may be cases when it is necessary to verify or stub parameters based on something slightly more complex then basic equality. This is what we will talk about next.</p> <div class="section" id="using-phpunit-matchers"> <h2>Using PHPUnit Matchers<a class="headerlink" href="#using-phpunit-matchers" title="Permalink to this headline">¶</a></h2> <p>Phake was developed with PHPUnit in mind. It is not dependent on PHPUnit, however if PHPUnit is your testing framework of choice there is some special integration available. Any constraints made available by the PHPUnit framework will work seemlessly inside of Phake. Here is an example of how the PHPUnit constraints can be used:</p> <div class="highlight-php"><div class="highlight"><pre><span class="x">class TestPHPUnitConstraint extends PHPUnit_Framework_TestCase</span> <span class="x">{</span> <span class="x"> public function testDealNumberOfCards()</span> <span class="x"> {</span> <span class="x"> $deck = Phake::mock('CardCollection');</span> <span class="x"> $players = Phake::mock('PlayerCollection');</span> <span class="x"> $dealer = Phake::mock('DealerStrategy');</span> <span class="x"> $dealer->deal($deck, $players, 11);</span> <span class="x"> Phake::verify($dealer)</span> <span class="x"> ->deal($deck, $players, $this->greaterThan(10));</span> <span class="x"> }</span> <span class="x">}</span> </pre></div> </div> <p>I have added another parameter to my <tt class="docutils literal"><span class="pre">deal()</span></tt> method that allows me to specify the number of cards to deal to each player. In the test above I wanted to verify that the number passed to this parameter was greater than 10.</p> <p>For a list of the constraints you have available to you through PHPUnit, I recommend reading the PHPUnit’s documentation on assertions and constraints. Any constraint that can be used with <tt class="docutils literal"><span class="pre">assertThat()</span></tt> in PHPUnit can also be used in Phake.</p> </div> <div class="section" id="using-hamcrest-matchers"> <h2>Using Hamcrest Matchers<a class="headerlink" href="#using-hamcrest-matchers" title="Permalink to this headline">¶</a></h2> <p>If you do not use PHPUnit, Phake also supports Hamcrest matchers. This is in-line with the Phake’s design goal of being usable with any testing framework. Here is a repeat of the PHPUnit example, this time using SimpleTest and Hamcrest matchers.</p> <div class="highlight-php"><div class="highlight"><pre><span class="x">class TestHamcrestMatcher extends UnitTestCase</span> <span class="x">{</span> <span class="x"> public function testDealNumberOfCards()</span> <span class="x"> {</span> <span class="x"> $deck = Phake::mock('CardCollection');</span> <span class="x"> $players = Phake::mock('PlayerCollection');</span> <span class="x"> $dealer = Phake::mock('DealerStrategy');</span> <span class="x"> $dealer->deal($deck, $players, 11);</span> <span class="x"> Phake::verify($dealer)->deal($deck, $players, greaterThan(10));</span> <span class="x"> }</span> <span class="x">}</span> </pre></div> </div> </div> <div class="section" id="parameter-capturing"> <h2>Parameter Capturing<a class="headerlink" href="#parameter-capturing" title="Permalink to this headline">¶</a></h2> <p>As you can see there are a variety of methods for verifying that the appropriate parameters are being passed to methods. However, there may be times when the prebuilt constraints and matchers simply do not fit your needs. Perhaps there is method that accepts a complex object where only certain components of the object need to be validated. Parameter capturing will allow you to store the parameter that was used to call your method so that it can be used in assertions later on.</p> <p>Consider the following example where I have defined a <tt class="docutils literal"><span class="pre">getNumberOfCards()</span></tt> method on the <tt class="docutils literal"><span class="pre">CardCollection</span></tt> interface.</p> <div class="highlight-php"><div class="highlight"><pre><span class="x">interface CardCollection</span> <span class="x">{</span> <span class="x"> public function getNumberOfCards();</span> <span class="x">}</span> </pre></div> </div> <p>I want to create new functionality for a my poker dealer strategy that will check to make sure we are playing with a full deck of 52 cards when the <tt class="docutils literal"><span class="pre">deal()</span></tt> call is made. It would be rather cumbersome to create a copy of a <tt class="docutils literal"><span class="pre">CardCollection</span></tt> implementation that I could be sure would match in an equals scenario. Such a test would look something like this.</p> <p>Please note, I do not generally advocate this type of design. I prefer a dependency injection versus instantiation. So please remember, this is not an example of clean design, simply an example of what you can do with argument capturing.</p> <div class="highlight-php"><div class="highlight"><pre><span class="x">class MyPokerGameTest extends PHPUnit_Framework_TestCase</span> <span class="x">{</span> <span class="x"> public function testDealCards()</span> <span class="x"> {</span> <span class="x"> $dealer = Phake::mock('MyPokerDealer');</span> <span class="x"> $players = Phake::mock('PlayerCollection');</span> <span class="x"> $cardGame = new MyPokerGame($dealer, $players);</span> <span class="x"> Phake::verify($dealer)->deal(Phake::capture($deck), $players);</span> <span class="x"> $this->assertEquals(52, $deck->getNumberOfCards());</span> <span class="x"> }</span> <span class="x">}</span> </pre></div> </div> <p>You can also capture parameters if they meet a certain condition. For instance, if someone mistakenly passed an array as the first parameter to the <tt class="docutils literal"><span class="pre">deal()</span></tt> method then PHPUnit would fatal error out. This can be protected against by using the the <tt class="docutils literal"><span class="pre">Phake::capture()->when()</span></tt> method. The <tt class="docutils literal"><span class="pre">when()</span></tt> method accepts the same constraints that <tt class="docutils literal"><span class="pre">Phake::verify()</span></tt> accepts. Here is how you could leverage that functionality to bulletproof your captures a little bit.</p> <div class="highlight-php"><div class="highlight"><pre><span class="x">class MyBetterPokerGameTest extends PHPUnit_Framework_TestCase</span> <span class="x">{</span> <span class="x"> public function testDealCards()</span> <span class="x"> {</span> <span class="x"> $dealer = Phake::mock('MyPokerDealer');</span> <span class="x"> $players = Phake::mock('PlayerCollection');</span> <span class="x"> $cardGame = new MyPokerGame($dealer, $players);</span> <span class="x"> Phake::verify($dealer)->deal(</span> <span class="x"> Phake::capture($deck)</span> <span class="x"> ->when($this->isInstanceOf('CardCollection')),</span> <span class="x"> $players</span> <span class="x"> );</span> <span class="x"> $this->assertEquals(52, $deck->getNumberOfCards());</span> <span class="x"> }</span> <span class="x">}</span> </pre></div> </div> <p>This could also be done by using PHPUnit’s assertions later on with the captured parameter, however this also has a side effect of better localizing your error. Here is the error you would see if the above test failed.</p> <div class="highlight-python"><pre>Exception: Expected MyPokerDealer->deal(<captured parameter>, equal to <object:PlayerCollection>) to be called exactly 1 times, actually called 0 times. Other Invocations: PhakeTest_MockedClass->fooWithArgument(<array>, <object:PlayerCollection>)</pre> </div> <p>It should be noted that while it is possible to use argument capturing for stubbing with <tt class="docutils literal"><span class="pre">Phake::when()</span></tt> I would discourage it. When stubbing a method you should only be concerned about making sure an expected value is return and argument capturing in no way helps with that goal. In the worst case scenario you will have some incredibly difficult test failures to diagnose.</p> </div> <div class="section" id="custom-parameter-matchers"> <h2>Custom Parameter Matchers<a class="headerlink" href="#custom-parameter-matchers" title="Permalink to this headline">¶</a></h2> <p>An alternative to using argument capturing is creating custom matchers. All parameter matchers implement the interface <tt class="docutils literal"><span class="pre">Phake_Matchers_IArgumentMatcher</span></tt>. You can create custom implementations of this interface. This is especially useful if you find yourself using a similar capturing pattern over and over again. If I were to rewriting the test above using a customer argument matcher it would look something like this.</p> <div class="highlight-php"><div class="highlight"><pre><span class="x">class FiftyTwoCardDeckMatcher implements Phake_Matchers_IArgumentMatcher</span> <span class="x">{</span> <span class="x"> public function matches($argument)</span> <span class="x"> {</span> <span class="x"> return ($argument instanceof CardCollection</span> <span class="x"> && $argument->getNumberOfCards() == 52);</span> <span class="x"> }</span> <span class="x"> public function __toString()</span> <span class="x"> {</span> <span class="x"> return '<object:CardCollection with 52 cards>';</span> <span class="x"> }</span> <span class="x">}</span> <span class="x">class MyBestPokerGameTest extends PHPUnit_Framework_TestCase</span> <span class="x">{</span> <span class="x"> public function testDealCards()</span> <span class="x"> {</span> <span class="x"> $dealer = Phake::mock('MyPokerDealer');</span> <span class="x"> $players = Phake::mock('PlayerCollection');</span> <span class="x"> $cardGame = new MyPokerGame($dealer, $players);</span> <span class="x"> Phake::verify($dealer)->deal(new 52CardDeckMatcher(), $players);</span> <span class="x"> }</span> <span class="x">}</span> </pre></div> </div> </div> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="index.html">Table Of Contents</a></h3> <ul> <li><a class="reference external" href="#">Method Parameter Matchers</a><ul> <li><a class="reference external" href="#using-phpunit-matchers">Using PHPUnit Matchers</a></li> <li><a class="reference external" href="#using-hamcrest-matchers">Using Hamcrest Matchers</a></li> <li><a class="reference external" href="#parameter-capturing">Parameter Capturing</a></li> <li><a class="reference external" href="#custom-parameter-matchers">Custom Parameter Matchers</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="answers.html" title="previous chapter">Answers</a></p> <h4>Next topic</h4> <p class="topless"><a href="configuration.html" title="next chapter">Configuration</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/method-parameter-matchers.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="search.html" method="get"> <input type="text" name="q" size="18" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="configuration.html" title="Configuration" >next</a> |</li> <li class="right" > <a href="answers.html" title="Answers" >previous</a> |</li> <li><a href="index.html">Phake - PHP Mocking Framework v1.0.3 documentation</a> »</li> </ul> </div> <div class="footer"> © Copyright 2014, Mike Lively <m@digitalsandwich.com>. Created using <a href="">Sphinx</a> 0.6.6. </div> </body> </html>
Save
Cancel