Ticket #2443: tut1.patch

doc/core/howto/trial.xhtml

@@ -20 +20 @@
 
 <h2>Simple (stupid) example</h2>
 
+<h3>Creating an API and writing tests</h3>
+
 <p>Let's say you want to create a calculation library. Create your project
 structure with a directory called calculus, a file called base.py (and a
 __init__.py file too).</p>
 
 <p>Then you write a simple API to your user in base.py. Different strategies
-apply here: some write first the tests, others write first the API. We're
-not going to worry too much about that.</p>
+apply here: some like to write the tests first, others write the API first.
+We're not going to worry too much about that.</p>
 
 <pre class="python">
 # -*- test-case-name: calculus.test.test_base -*-
@@ -47 +49 @@
 
 <p>See, we've written the interface, not the code. Now we'll write what we
 expect the object to do. Create a test directory in the calculus one, with an
-__init__.py file, and a test_base.py file. Open test_base.py.
+__init__.py file, and a test_base.py file.
 </p>
 
 <p>
-To resume you'll have this structure:
+To make a long story short, you'll have this structure:
 <ul>
     <li>
         calculus/
@@ -69 +71 @@
 </ul>
 </p>
 
+<p>Now open test_base.py and fill in the following code:</p>
+
 <pre class="python">
 from calculus.base import Calculation
 from twisted.trial import unittest
@@ -97 +101 @@
 </pre>
 
 <p>To run the tests, call <code>trial calculus.test</code> in the command
-line. You hould have the following output:</p>
+line. You should have the following output:</p>
 
 <pre>
 Running 4 tests.
@@ -175 +179 @@
 if you add additionnal log to your tests.
 </p>
 
-<p>Now that our tests failm when can actually implement the behaviour
-expected:</p>
-
-<pre class="python">
+<h3>Writing code to match the tests' expectations</h3>
+
+<p>Now that our tests fail whe can actually implement the expected behaviour
+in calculus/base.py:</p>
+
+<pre class="python">
+# -*- test-case-name: calculus.test.test_base -*-
+
 class Calculation(object):
     def add(self, a, b):
         return a + b
@@ -193 +201 @@
         return a / b
 </pre>
 
-<p> Run trial again and hopefully your tests should now pass.</p>
+<p>Run trial again and hopefully your tests should now pass.</p>
 
 <pre>
 Running 4 tests.
@@ -210 +218 @@
 PASSED (successes=4)
 </pre>
 
+<h3>Factoring out common test logic</h3>
+
 <p>You may observe that our test file contains a lot of redundant code, which
 is bad. For this purpose, trial defines a setUp method that is called before
 each test methods: this allows you to build some objects that will be use in
 all your tests methods. Also, we'll use a parameterized test method.</p>
 
 <p>Note that the counterpart of setUp is tearDown, which is called after
-each tests (either it succeed or failed); it's mainly useful for cleanups
-purpose.</p>
+each test, wherever it succeeded or failed; it's mainly useful for cleanup
+purposes.</p>
 
 <pre class="python">
 from calculus.base import Calculation
@@ -279 +289 @@
 
 </pre>
 
-<p>The only useful thing here is the <code>assertRaises</code> method,
-which takes the method to run and its arguments and assert it raises the
-given exception.</p>
+<p>The only new thing here is the <code>assertRaises</code> method,
+which takes the function or method to run and its arguments and checks that
+it raises the given exception.</p>
 
 <p>Surprisingly, there are not so much tests that failed. But we still need
-to add some checking.</p>
+to add some checking in our Calculation object:</p>
 
 <pre class="python">
 # -*- test-case-name: calculus.test.test_base -*-
@@ -317 +327 @@
 </pre>
 
 <p>We just need a little trick because <code>int()</code> of a string
-raises a <code>ValueError</code>.</p>
+raises a <code>ValueError</code> when it fails.</p>
 
 <h2>Testing a protocol</h2>
 
-<p>For the example, we'll create a custom protocol to make calculus within a
+<p>We'll now create a custom protocol to invoke calculus within a
 telnet-like session. We'll basically call the command with the arguments and
 then get the commands.</p>
 
-<p>We first write the tests, and then explain what it does. Open the file calculus/test/test_remote.py.</p>
-
-<pre class="python">
+<h3>Creating and testing the server</h3>
+
+<p>First we'll write the tests, and then explain what they do.
+Open the file calculus/test/test_remote.py:</p>
+
+<pre class="python">
+from calculus.remote import RemoteCalculationFactory
+from twisted.trial import unittest
 from twisted.test import proto_helpers
 
 class RemoteCalculationTestCase(unittest.TestCase):
@@ -364 +379 @@
 </p>
 
 <p>This concept is really important for Twisted. Even if there are many tests
-inside Twisted that use network, most good tests don't. The problem with
-unittests and network is that the network isn't reliable enough to be sure
+inside Twisted that use the network, most good tests don't. The problem with
+unittests and networking is that the network isn't reliable enough to be sure
 it'll have a sane behavior all the time. Thus it creates intermittent failures,
-which is a pain for continuous integration.
+which is a pain for continuous integration. By using a fake transport, we are
+able to write 100% reliable tests.
 </p>
 
 <p>Let's now implement this protocol in calculus/remote.py.</p>
 
 <pre class="python">
+# -*- test-case-name: calculus.test.test_remote -*-
+
 from twisted.protocols import basic
 from twisted.internet import protocol
 
@@ -410 +428 @@
 <p>Now if you run the tests, everything should be fine! You can also run
 a server to test it with a telnet client.</p>
 
+<h3>Creating and testing the client</h3>
+
 <p>Of course you can't let your users with this: we'll now build a client
 to our server, to be able to use it inside a python program. And it'll
 serve our next purpose.</p>
+
+<p>We first add the following code at the end of calculus/test/test_remote.py:</p>
 
 <pre class="python">
 class ClientCalculationTestCase(unittest.TestCase):
@@ -453 +475 @@
 </p>
 
 <p>Also, you can see that we assert that we've gone through the callback
-<code>cb</code> using a variable. It's very important, because sometimes, with
-asynchronous code, your tests are passing but because your callbacks are not
-called, which is generally a failure condition.</p>
-
-<p>We would have written the <code>_test</code> method more naturally this way:</p>
+<code>cb</code> using a variable. It's very important, because otherwise, with
+asynchronous code, your tests may pass while your callbacks are not called,
+which should be a failure condition.</p>
+
+<p>Actually, we don't need to do this check explicitly,
+since Trial can do it for us if our test methods return the Deferred objects.
+Thus we could have written the test logic in the following way:</p>
 
 <pre class="python">
     def _test(self, operation, a, b, expected):
@@ -469 +493 @@
         d.addCallback(cb)
         self.proto.dataReceived("%d\r\n" % (expected,))
         return d
-</pre>
-
-<p>In this example, if you remove the <code>dataReceived</code> call, your tests will
-still succeed! That's because the callback is run synchronously, so returning the Deferred
-from the test doesn't help. So in doubt, use the <code>called</code> pattern.</p>
-
-<p>We'll now write the corresponding client.</p>
+
+    def test_add(self):
+        return self._test('add', 7, 6, 13)
+
+    def test_substract(self):
+        return self._test('substract', 82, 78, 4)
+
+    def test_multiply(self):
+        return self._test('multiply', 2, 8, 16)
+
+    def test_divide(self):
+        return self._test('divide', 14, 3, 4)
+</pre>
+
+<p>We'll now write the client code at the end of calculus/remote.py:</p>
 
 <pre class="python">
 class RemoteCalculationClient(basic.LineReceiver):
@@ -510 +542 @@
 <p>The client is really straightforward. We just factor operations,
 everything else should be obvious.</p>
 
-<h2>Good pratices</h2>
+<h2>More good pratices</h2>
 
 <h3>Testing scheduling</h3>
 
-<p>That's one of the tough part of Twisted: having a callLater call hanging
+<p>That's one of the tough parts of Twisted: having a callLater call hanging
 around and be able to determically test it. There's a convenient object for
 that in <code>twisted.task</code> called <code>Clock</code>.</p>
 
-<p>The functionnality we'll use to test it is client request timeout: as it
+<p>As an example we'll test the code for client request timeout: since our client
 uses TCP it can hang for a long time (firewall, connectivity problems, etc...).
 So generally we need to implement timeouts on the client side. Basically it's
-just that we send a request, don't have response and expect a timeout error.
+just that we send a request, don't receive a response and expect a timeout error
+to be triggered after a certain duration.
 </p>
 
 <pre class="python">
@@ -593 +626 @@
 processes created in their tests. If it's still not obvious, you must try to
 avoid that like the plague, because it ends up with a lot of problems, one of
 them being intermittent failures. And intermittent failures are the plague
-to every automated tests.</p>
+of automated tests.</p>
 
 <p>To actually test that, we'll launch a server with our protocol.</p>
 
@@ -624 +657 @@
 <code>stopListening</code> call, which is good.</p>
 
 <p>Also, you should be aware that tearDown will called in any case, after success
-or failure. So don't expect that every objects you create in the test method are
+or failure. So don't expect that every objects you created in the test method are
 present, because your tests may have failed in the middle.</p>
 
 <h3>Resolve a bug</h3>