diff -r e436fc4313f8 doc/core/howto/trial.xhtml --- a/doc/core/howto/trial.xhtml Wed Mar 28 11:38:49 2007 +0200 +++ b/doc/core/howto/trial.xhtml Wed Mar 28 11:39:33 2007 +0200 @@ -20,13 +20,15 @@ Twisted.

Simple (stupid) example

+

Creating an API and writing tests

+

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).

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.

+apply here: some like to write the tests first, others write the API first. +We're not going to worry too much about that.

 # -*- test-case-name: calculus.test.test_base -*-
@@ -47,11 +49,11 @@ class Calculation(object):
 
 
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.
 

 
 

-To resume you'll have this structure:
+To make a long story short, you'll have this structure:
 

 

 
+
Now open test_base.py and fill in the following code:

+
 
 from calculus.base import Calculation
 from twisted.trial import unittest
@@ -97,7 +101,7 @@ class CalculationTestCase(unittest.TestC
 

 
 
To run the tests, call trial calculus.test in the command
-line. You hould have the following output:

+line. You should have the following output:

 
 
 Running 4 tests.
@@ -175,10 +179,14 @@ if you add additionnal log to your tests
 if you add additionnal log to your tests.
 

 
-
Now that our tests failm when can actually implement the behaviour
-expected:

-
-
+
Writing code to match the tests' expectations

+
+
Now that our tests fail whe can actually implement the expected behaviour
+in calculus/base.py:

+
+
+# -*- test-case-name: calculus.test.test_base -*-
+
 class Calculation(object):
     def add(self, a, b):
         return a + b
@@ -193,7 +201,7 @@ class Calculation(object):
         return a / b
 

 
-
 Run trial again and hopefully your tests should now pass.

+
Run trial again and hopefully your tests should now pass.

 
 
 Running 4 tests.
@@ -210,14 +218,16 @@ PASSED (successes=4)
 PASSED (successes=4)
 

 
+
Factoring out common test logic

+
 
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.

 
 
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.

+each test, wherever it succeeded or failed; it's mainly useful for cleanup
+purposes.

 
 
 from calculus.base import Calculation
@@ -279,12 +289,12 @@ class CalculationTestCase(unittest.TestC
 
 

 
-
The only useful thing here is the assertRaises method,
-which takes the method to run and its arguments and assert it raises the
-given exception.

+
The only new thing here is the assertRaises method,
+which takes the function or method to run and its arguments and checks that
+it raises the given exception.

 
 
Surprisingly, there are not so much tests that failed. But we still need
-to add some checking.

+to add some checking in our Calculation object:

 
 
 # -*- test-case-name: calculus.test.test_base -*-
@@ -317,17 +327,22 @@ class Calculation(object):
 

 
 
We just need a little trick because int() of a string
-raises a ValueError.

+raises a ValueError when it fails.

 
 
Testing a protocol

 
-
For the example, we'll create a custom protocol to make calculus within a
+
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.

 
-
We first write the tests, and then explain what it does. Open the file calculus/test/test_remote.py.

-
-
+
Creating and testing the server

+
+
First we'll write the tests, and then explain what they do.
+Open the file calculus/test/test_remote.py:

+
+
+from calculus.remote import RemoteCalculationFactory
+from twisted.trial import unittest
 from twisted.test import proto_helpers
 
 class RemoteCalculationTestCase(unittest.TestCase):
@@ -364,15 +379,18 @@ purpose. This way we can emulate a netwo
 

 
 
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.
 

 
 
Let's now implement this protocol in calculus/remote.py.

 
 
+# -*- test-case-name: calculus.test.test_remote -*-
+
 from twisted.protocols import basic
 from twisted.internet import protocol
 
@@ -410,9 +428,13 @@ what methods you make accessible.
 
Now if you run the tests, everything should be fine! You can also run
 a server to test it with a telnet client.

 
+
Creating and testing the client

+
 
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.

+
+
We first add the following code at the end of calculus/test/test_remote.py:

 
 
 class ClientCalculationTestCase(unittest.TestCase):
@@ -453,11 +475,13 @@ client part, so we instantiate the proto
 

 
 
Also, you can see that we assert that we've gone through the callback
-cb 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.

-
-
We would have written the _test method more naturally this way:

+cb 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.

+
+
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:

 
 
     def _test(self, operation, a, b, expected):
@@ -469,13 +493,21 @@ called, which is generally a failure con
         d.addCallback(cb)
         self.proto.dataReceived("%d\r\n" % (expected,))
         return d
-

-
-
In this example, if you remove the dataReceived 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 called pattern.

-
-
We'll now write the corresponding client.

+
+    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)
+

+
+
We'll now write the client code at the end of calculus/remote.py:

 
 
 class RemoteCalculationClient(basic.LineReceiver):
@@ -510,18 +542,19 @@ class RemoteCalculationClient(basic.Line
 
The client is really straightforward. We just factor operations,
 everything else should be obvious.

 
-
Good pratices

+
More good pratices

 
 
Testing scheduling

 
-
That's one of the tough part of Twisted: having a callLater call hanging
+
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 twisted.task called Clock.

 
-
The functionnality we'll use to test it is client request timeout: as it
+
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.
 

 
 
@@ -593,7 +626,7 @@ processes created in their tests. If it'
 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.

+of automated tests.

 
 
To actually test that, we'll launch a server with our protocol.

 
@@ -624,7 +657,7 @@ class RemoteRunCalculationTestCase(unitt
 stopListening call, which is good.

 
 
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.

 
 
Resolve a bug