# HG changeset patch
# User Julien Jehannet <julien.jehannet@logilab.fr>
# Date 1291378154 -3600
# Node ID 3ea1f7a6311cc92aa213a063944225356c1ed371
# Parent  253dd28cc35fad6aa6034c4f0929ce381d7f1eb9
[book] Notes about literate testing

diff -r 253dd28cc35f -r 3ea1f7a6311c doc/book/en/devrepo/testing.rst
--- a/doc/book/en/devrepo/testing.rst	Mon Dec 06 19:11:28 2010 +0100
+++ b/doc/book/en/devrepo/testing.rst	Fri Dec 03 13:09:14 2010 +0100
@@ -343,6 +343,60 @@
 therefore making new entity types and relations available to the
 tests. 
 
+Literate programming
+--------------------
+
+CubicWeb provides some literate programming capabilities. The :ref:`cubicweb-ctl`
+`shell` command accepts differents format files. If your file ends with `.txt`
+or `.rst`, the file will be parsed by :mod:`doctest.testfile` with CubicWeb
+:ref:`migration` API enabled in it.
+
+Create a `scenario.txt` file into `test/` directory and fill with some content.
+Please refer the :mod:`doctest.testfile` `documentation`_.
+
+.. _documentation: http://docs.python.org/library/doctest.html
+
+Then, you can run it directly by::
+
+    $ cubicweb-ctl shell <cube_instance> test/scenario.txt
+
+When your scenario file is ready, put it in a new test case to be able to run
+it automatically.
+
+.. sourcecode:: python
+
+      from os.path import dirname, join
+      from logilab.common.testlib import unittest_main
+      from cubicweb.devtools.testlib import CubicWebTC
+
+      class AcceptanceTC(CubicWebTC):
+
+              def test_scenario(self):
+                      self.assertDocTestFile(join(dirname(__file__), 'scenario.txt'))
+
+      if __name__ == '__main__':
+              unittest_main()
+
+Skipping a scenario
+```````````````````
+
+If you want to set up initial conditions that you can't put in your unit test
+case, you have to use a :exc:`KeyboardInterrupt` exception only because of the
+way :mod:`doctest` module will catch all the exceptions internally.
+
+    >>> if condition_not_met:
+    ...     raise KeyboardInterrupt('please, check your fixture.')
+
+Passing paramaters
+``````````````````
+Using extra arguments to parametrize your scenario is possible by prepend them
+by double dashes.
+
+Please refer to the `cubicweb-ctl shell --help` usage.
+
+.. important::
+    Your scenario file must be utf-8 encoded.
+
 Test APIS
 ---------