diff options
Diffstat (limited to 'tests/UnitTests/simpletest/docs/en/expectation_documentation.html')
| -rw-r--r-- | tests/UnitTests/simpletest/docs/en/expectation_documentation.html | 356 |
1 files changed, 0 insertions, 356 deletions
diff --git a/tests/UnitTests/simpletest/docs/en/expectation_documentation.html b/tests/UnitTests/simpletest/docs/en/expectation_documentation.html deleted file mode 100644 index ed1484a9..00000000 --- a/tests/UnitTests/simpletest/docs/en/expectation_documentation.html +++ /dev/null @@ -1,356 +0,0 @@ -<html>
-<head>
-<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
-<title>
- Extending the SimpleTest unit tester with additional expectation classes
- </title>
-<link rel="stylesheet" type="text/css" href="docs.css" title="Styles">
-</head>
-<body>
-<div class="menu_back">
-<div class="menu">
-<h2>
-<a href="index.html">SimpleTest</a>
-</h2>
-<ul>
-<li>
-<a href="overview.html">Overview</a>
-</li>
-<li>
-<a href="unit_test_documentation.html">Unit tester</a>
-</li>
-<li>
-<a href="group_test_documentation.html">Group tests</a>
-</li>
-<li>
-<a href="server_stubs_documentation.html">Server stubs</a>
-</li>
-<li>
-<a href="mock_objects_documentation.html">Mock objects</a>
-</li>
-<li>
-<a href="partial_mocks_documentation.html">Partial mocks</a>
-</li>
-<li>
-<a href="reporter_documentation.html">Reporting</a>
-</li>
-<li>
-<span class="chosen">Expectations</span>
-</li>
-<li>
-<a href="web_tester_documentation.html">Web tester</a>
-</li>
-<li>
-<a href="form_testing_documentation.html">Testing forms</a>
-</li>
-<li>
-<a href="authentication_documentation.html">Authentication</a>
-</li>
-<li>
-<a href="browser_documentation.html">Scriptable browser</a>
-</li>
-</ul>
-</div>
-</div>
-<h1>Expectation documentation</h1>
-<div class="content">
- <p>
-<a class="target" name="mock">
-<h2>More control over mock objects</h2>
-</a>
-</p>
- <p>
- The default behaviour of the
- <a href="mock_objects_documentation.html">mock objects</a>
- in
- <a href="http://sourceforge.net/projects/simpletest/">SimpleTest</a>
- is either an identical match on the argument or to allow any argument at all.
- For almost all tests this is sufficient.
- Sometimes, though, you want to weaken a test case.
- </p>
- <p>
- One place where a test can be too tightly coupled is with
- text matching.
- Suppose we have a component that outputs a helpful error
- message when something goes wrong.
- You want to test that the correct error was sent, but the actual
- text may be rather long.
- If you test for the text exactly, then every time the exact wording
- of the message changes, you will have to go back and edit the test suite.
- </p>
- <p>
- For example, suppose we have a news service that has failed
- to connect to its remote source.
-<pre>
-<strong>class NewsService {
- ...
- function publish(&$writer) {
- if (! $this->isConnected()) {
- $writer->write('Cannot connect to news service "' .
- $this->_name . '" at this time. ' .
- 'Please try again later.');
- }
- ...
- }
-}</strong>
-</pre>
- Here it is sending its content to a
- <span class="new_code">Writer</span> class.
- We could test this behaviour with a
- <span class="new_code">MockWriter</span> like so...
-<pre>
-class TestOfNewsService extends UnitTestCase {
- ...
- function testConnectionFailure() {<strong>
- $writer = &new MockWriter($this);
- $writer->expectOnce('write', array(
- 'Cannot connect to news service ' .
- '"BBC News" at this time. ' .
- 'Please try again later.'));
-
- $service = &new NewsService('BBC News');
- $service->publish($writer);
-
- $writer->tally();</strong>
- }
-}
-</pre>
- This is a good example of a brittle test.
- If we decide to add additional instructions, such as
- suggesting an alternative news source, we will break
- our tests even though no underlying functionality
- has been altered.
- </p>
- <p>
- To get around this, we would like to do a regular expression
- test rather than an exact match.
- We can actually do this with...
-<pre>
-class TestOfNewsService extends UnitTestCase {
- ...
- function testConnectionFailure() {
- $writer = &new MockWriter($this);<strong>
- $writer->expectOnce(
- 'write',
- array(new WantedPatternExpectation('/cannot connect/i')));</strong>
-
- $service = &new NewsService('BBC News');
- $service->publish($writer);
-
- $writer->tally();
- }
-}
-</pre>
- Instead of passing in the expected parameter to the
- <span class="new_code">MockWriter</span> we pass an
- expectation class called
- <span class="new_code">WantedPatternExpectation</span>.
- The mock object is smart enough to recognise this as special
- and to treat it differently.
- Rather than simply comparing the incoming argument to this
- object, it uses the expectation object itself to
- perform the test.
- </p>
- <p>
- The <span class="new_code">WantedPatternExpectation</span> takes
- the regular expression to match in its constructor.
- Whenever a comparison is made by the <span class="new_code">MockWriter</span>
- against this expectation class, it will do a
- <span class="new_code">preg_match()</span> with this pattern.
- With our test case above, as long as "cannot connect"
- appears in the text of the string, the mock will issue a pass
- to the unit tester.
- The rest of the text does not matter.
- </p>
- <p>
- The possible expectation classes are...
- <table>
-<tbody>
- <tr>
-<td><span class="new_code">EqualExpectation</span></td><td>An equality, rather than the stronger identity comparison</td>
-</tr>
- <tr>
-<td><span class="new_code">NotEqualExpectation</span></td><td>An inequality comparison</td>
-</tr>
- <tr>
-<td><span class="new_code">IndenticalExpectation</span></td><td>The default mock object check which must match exactly</td>
-</tr>
- <tr>
-<td><span class="new_code">NotIndenticalExpectation</span></td><td>Inverts the mock object logic</td>
-</tr>
- <tr>
-<td><span class="new_code">WantedPatternExpectation</span></td><td>Uses a Perl Regex to match a string</td>
-</tr>
- <tr>
-<td><span class="new_code">NoUnwantedPatternExpectation</span></td><td>Passes only if failing a Perl Regex</td>
-</tr>
- <tr>
-<td><span class="new_code">IsAExpectation</span></td><td>Checks the type or class name only</td>
-</tr>
- <tr>
-<td><span class="new_code">NotAExpectation</span></td><td>Opposite of the <span class="new_code">IsAExpectation</span></td>
-</tr>
- <tr>
-<td><span class="new_code">MethodExistsExpectation</span></td><td>Checks a method is available on an object</td>
-</tr>
- </tbody>
-</table>
- Most take the expected value in the constructor.
- The exceptions are the pattern matchers, which take a regular expression,
- and the <span class="new_code">IsAExpectation</span> and <span class="new_code">NotAExpectation</span> which takes a type
- or class name as a string.
- </p>
-
- <p>
-<a class="target" name="behaviour">
-<h2>Using expectations to control stubs</h2>
-</a>
-</p>
- <p>
- The expectation classes can be used not just for sending assertions
- from mock objects, but also for selecting behaviour for either
- the
- <a href="mock_objects_documentation.html">mock objects</a>
- or the
- <a href="server_stubs_documentation.html">server stubs</a>.
- Anywhere a list of arguments is given, a list of expectation objects
- can be inserted instead.
- </p>
- <p>
- Suppose we want an authorisation server stub to simulate a successful login
- only if it receives a valid session object.
- We can do this as follows...
-<pre>
-Stub::generate('Authorisation');
-<strong>
-$authorisation = new StubAuthorisation();
-$authorisation->setReturnValue(
- 'isAllowed',
- true,
- array(new IsAExpectation('Session', 'Must be a session')));
-$authorisation->setReturnValue('isAllowed', false);</strong>
-</pre>
- We have set the default stub behaviour to return false when
- <span class="new_code">isAllowed</span> is called.
- When we call the method with a single parameter that
- is a <span class="new_code">Session</span> object, it will return true.
- We have also added a second parameter as a message.
- This will be displayed as part of the mock object
- failure message if this expectation is the cause of
- a failure.
- </p>
- <p>
- This kind of sophistication is rarely useful, but is included for
- completeness.
- </p>
-
- <p>
-<a class="target" name="extending">
-<h2>Creating your own expectations</h2>
-</a>
-</p>
- <p>
- The expectation classes have a very simple structure.
- So simple that it is easy to create your own versions for
- commonly used test logic.
- </p>
- <p>
- As an example here is the creation of a class to test for
- valid IP addresses.
- In order to work correctly with the stubs and mocks the new
- expectation class should extend
- <span class="new_code">SimpleExpectation</span>...
-<pre>
-<strong>class ValidIp extends SimpleExpectation {
-
- function test($ip) {
- return (ip2long($ip) != -1);
- }
-
- function testMessage($ip) {
- return "Address [$ip] should be a valid IP address";
- }
-}</strong>
-</pre>
- There are only two methods to implement.
- The <span class="new_code">test()</span> method should
- evaluate to true if the expectation is to pass, and
- false otherwise.
- The <span class="new_code">testMessage()</span> method
- should simply return some helpful text explaining the test
- that was carried out.
- </p>
- <p>
- This class can now be used in place of the earlier expectation
- classes.
- </p>
-
- <p>
-<a class="target" name="unit">
-<h2>Under the bonnet of the unit tester</h2>
-</a>
-</p>
- <p>
- The <a href="http://sourceforge.net/projects/simpletest/">SimpleTest unit testing framework</a>
- also uses the expectation classes internally for the
- <a href="unit_test_documentation.html">UnitTestCase class</a>.
- We can also take advantage of these mechanisms to reuse our
- homebrew expectation classes within the test suites directly.
- </p>
- <p>
- The most crude way of doing this is to use the
- <span class="new_code">SimpleTest::assertExpectation()</span> method to
- test against it directly...
-<pre>
-<strong>class TestOfNetworking extends UnitTestCase {
- ...
- function testGetValidIp() {
- $server = &new Server();
- $this->assertExpectation(
- new ValidIp(),
- $server->getIp(),
- 'Server IP address->%s');
- }
-}</strong>
-</pre>
- This is a little untidy compared with our usual
- <span class="new_code">assert...()</span> syntax.
- </p>
- <p>
- For such a simple case we would normally create a
- separate assertion method on our test case rather
- than bother using the expectation class.
- If we pretend that our expectation is a little more
- complicated for a moment, so that we want to reuse it,
- we get...
-<pre>
-class TestOfNetworking extends UnitTestCase {
- ...<strong>
- function assertValidIp($ip, $message = '%s') {
- $this->assertExpectation(new ValidIp(), $ip, $message);
- }</strong>
-
- function testGetValidIp() {
- $server = &new Server();<strong>
- $this->assertValidIp(
- $server->getIp(),
- 'Server IP address->%s');</strong>
- }
-}
-</pre>
- It is unlikely we would ever need this degree of control
- over the testing machinery.
- It is rare to need the expectations for more than pattern
- matching.
- Also, complex expectation classes could make the tests
- harder to read and debug.
- These mechanisms are really of most use to authors of systems
- that will extend the test framework to create their own tool set.
- </p>
-
- </div>
-<div class="copyright">
- Copyright<br>Marcus Baker, Jason Sweat, Perrick Penet 2004
- </div>
-</body>
-</html>
|