viff

changeset 790:5525b9b98415

Imported documentation from viff.dk repository. The exact order and placement of the files in the document tree is very much up for debate -- I just wanted to include them somewhere. Feel free to edit and rearrange things in better ways.
author Martin Geisler <mg@daimi.au.dk>
date Mon, 26 May 2008 22:16:45 +0200
parents 2f1b9576d413
children c7afb6fcc418
files doc/bibliography.txt doc/coding-style.txt doc/development.txt doc/implementation.txt doc/index.txt doc/presentations.txt doc/unit-testing.txt
diffstat 7 files changed, 605 insertions(+), 0 deletions(-) [+]
line diff
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/doc/bibliography.txt	Mon May 26 22:16:45 2008 +0200
     1.3 @@ -0,0 +1,56 @@
     1.4 +.. -*- coding: utf-8 -*-
     1.5 +
     1.6 +==============
     1.7 + Bibliography
     1.8 +==============
     1.9 +
    1.10 +.. note::
    1.11 +
    1.12 +   This list is far from complete. If you find more relevant
    1.13 +   references then please `send us a mail`__ with the information.
    1.14 +
    1.15 +   .. __: mailto:viff-devel@viff.dk
    1.16 +
    1.17 +The algorighms used by VIFF are published in various academic papers.
    1.18 +Here we will try to point out which parts of the code uses which
    1.19 +papers.
    1.20 +
    1.21 +* The ``viff.shamir`` module is obviously based on [Shamir79]_.
    1.22 +
    1.23 +*  ``apps/millionaires.py``: Inspired by [Yao82]_.
    1.24 +
    1.25 +* The default comparison operation (``Runtime.greater_than_equal``) is
    1.26 +  based on the comparison protocol from [Toft05]_.
    1.27 +
    1.28 +* Broadcast (``Runtime.broadcast``) is based on the original paper by
    1.29 +  [Bracha84]_ and on the explanation by [Cachin05]_.
    1.30 +
    1.31 +* The pseudo-random secret sharing (PRSS) in ``viff.prss`` is
    1.32 +  described in [CDI05]_.
    1.33 +
    1.34 +
    1.35 +.. [Bracha84] G. Bracha, *An asynchronous [(n-1)/3]-resilient
    1.36 +   consensus protocol*, Proc 3rd ACM Symposium on Principles of
    1.37 +   Distributed Computing (PODC), 1984, 154-162.
    1.38 +
    1.39 +.. [Cachin05] Christian Cachin, *Security and Fault-tolerance in
    1.40 +   Distributed Systems*, ETHZ, 2005, PDF__.
    1.41 +
    1.42 +   .. __: http://www.zurich.ibm.com/~cca/sft05/agreement.pdf
    1.43 +
    1.44 +.. [CDI05] Ronald Cramer, Ivan Damgård, and Yuval Ishai, *Share
    1.45 +   Conversion, Pseudorandom Secret-Sharing and Applications to Secure
    1.46 +   Computation*, Proc of TCC 2005, LNCS 3378, PS__.
    1.47 +
    1.48 +   .. __:  http://www.cs.technion.ac.il/~yuvali/pubs/CDI05.ps
    1.49 +
    1.50 +.. [Shamir79] Adi Shamir, *How to share a secret*, Communications of
    1.51 +   the ACM, 22 (11): 612-613.
    1.52 +
    1.53 +.. [Toft05] Tomas Toft, *Secure Integer Computation with Applications
    1.54 +   in Economics*, PhD Progress Report, July 2005, PDF__.
    1.55 +
    1.56 +   .. __: http://www.daimi.au.dk/~tomas/publications/progress.pdf
    1.57 +
    1.58 +.. [Yao82] Andrew Chi-Chih Yao, *Protocols for Secure Computations*,
    1.59 +   FOCS 1982, 160-164.
     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/doc/coding-style.txt	Mon May 26 22:16:45 2008 +0200
     2.3 @@ -0,0 +1,62 @@
     2.4 +.. -*- coding: utf-8 -*-
     2.5 +
     2.6 +===================
     2.7 + VIFF Coding Style
     2.8 +===================
     2.9 +
    2.10 +The VIFF code tries to follow the coding style laid out in `PEP 8`_,
    2.11 +which you should read or at least skim over. You can check your code
    2.12 +against by running the pep8.py_ checker.
    2.13 +
    2.14 +.. TODO: change PEP 8 link into using the :PEP:`8` role when Sphinx
    2.15 +.. doesn't crash on it anymore. See
    2.16 +..
    2.17 +..   http://groups.google.com/group/sphinx-dev/msg/bc99090aa52b87af
    2.18 +..
    2.19 +.. for the bug report.
    2.20 +
    2.21 +.. _PEP 8: http://www.python.org/dev/peps/pep-0008
    2.22 +.. _pep8.py: http://svn.browsershots.org/trunk/devtools/pep8/pep8.py
    2.23 +
    2.24 +
    2.25 +The VIFF Coding Style in Short
    2.26 +------------------------------
    2.27 +
    2.28 +A summary of the rules:
    2.29 +
    2.30 +* Use four spaces for indention, never tabs.
    2.31 +
    2.32 +* Use a single space around binary operators.
    2.33 +
    2.34 +* Name classes using ``CamelCase``.
    2.35 +
    2.36 +* Name variables, function, and methods using lowercase words like
    2.37 +  ``foo_bar``.
    2.38 +
    2.39 +* Write docstrings for your functions and methods. Include test for
    2.40 +  doctest_ if possible.
    2.41 +
    2.42 +  .. _doctest: http://docs.python.org/lib/module-doctest.html
    2.43 +
    2.44 +* Try to be consistent.
    2.45 +
    2.46 +These rules are there to make the source code more readable for both
    2.47 +old and new people.
    2.48 +
    2.49 +The Twisted Coding Style
    2.50 +------------------------
    2.51 +
    2.52 +VIFF uses Twisted_ and their code follows a slightly different coding
    2.53 +style. Their style is closer to the style used in Java where functions
    2.54 +and methods are named ``fooBar`` instead of ``foo_bar``.
    2.55 +
    2.56 +When writing code which is close to Twisted code, you might want to
    2.57 +follow that style too. If you subclass a Twisted class to override
    2.58 +some behavior, you might be forced to follow their style.
    2.59 +
    2.60 +If you have a choice, then you should only use the Twisted style if
    2.61 +you expect people to call both your code and the Twisted code — if
    2.62 +people will only call your code, then please follow the standard VIFF
    2.63 +coding style.
    2.64 +
    2.65 +.. _Twisted: http://twistedmatrix.com/
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/doc/development.txt	Mon May 26 22:16:45 2008 +0200
     3.3 @@ -0,0 +1,160 @@
     3.4 +.. -*- coding: utf-8 -*-
     3.5 +
     3.6 +==================
     3.7 + VIFF Development
     3.8 +==================
     3.9 +
    3.10 +This page explains what you need to know if you want to start hacking
    3.11 +on VIFF. In addition to these instructions you will want to read up on
    3.12 +the `coding style`_ used by VIFF (it is the normal Python style,
    3.13 +nothing fancy there).
    3.14 +
    3.15 +.. _coding style: coding-style.html
    3.16 +
    3.17 +
    3.18 +Getting the Source Code
    3.19 +-----------------------
    3.20 +
    3.21 +VIFF is developed using Mercurial_ (also known as ``hg`` after its
    3.22 +command line program). This is a distributed revision control system
    3.23 +which allows you to participate fully in the development even if you
    3.24 +do not have what is traditionally known as "commit access". You can
    3.25 +also work offline and take advantage of the many fast operations
    3.26 +offered by Mercurial.
    3.27 +
    3.28 +.. _Mercurial: http://www.selenic.com/mercurial/
    3.29 +
    3.30 +After installing Mercurial you can checkout a copy of the source using
    3.31 +this command line::
    3.32 +
    3.33 +   hg clone http://hg.viff.dk/viff/
    3.34 +
    3.35 +This will create a directory called ``viff/`` where you will find the
    3.36 +source code. Please test that VIFF works as expected on your computer
    3.37 +by following the instructions on `unit testing`_.
    3.38 +
    3.39 +.. _unit testing: unit-testing.html
    3.40 +
    3.41 +
    3.42 +Contributing Changes
    3.43 +--------------------
    3.44 +
    3.45 +When you have created a new feature or fixed a bug, then you need to
    3.46 +send your changes to one of the VIFF developers. If you share a file
    3.47 +system with one of the developers, then the easiest way to get your
    3.48 +changes back into VIFF is to ensure that one of the developers has
    3.49 +read access on the repository files. He can then simply pull the
    3.50 +changesets over and eventually push them out to the VIFF repository.
    3.51 +
    3.52 +Alternatively, you can setup a Mercurial repository where one of the
    3.53 +developers can ``hg pull`` from. You can do this by uploading your
    3.54 +clone on some public web server (any webserver works for this since
    3.55 +the developers can pull using ``hg pull static-http://...``) or by
    3.56 +running::
    3.57 +
    3.58 +   hg serve -p 8000
    3.59 +
    3.60 +which creates a web server on port 8000 just like the one running at
    3.61 +http://hg.viff.dk/viff/. The default port number is 8000, so you can
    3.62 +leave that out.
    3.63 +
    3.64 +A final option is the patchbomb_ extension for Mercurial, which will
    3.65 +allow you to use::
    3.66 +
    3.67 +   hg email -t viff-devel@viff.dk -o
    3.68 +
    3.69 +to send the changesets not present in the VIFF repository (``-o``) to
    3.70 +the VIFF development list (``-t viff-devel@viff.dk``). You will
    3.71 +probably want to test using a ``-n`` flag or by sending the patches to
    3.72 +your own address first to make sure everything looks okay. You can get
    3.73 +the full list of options using ``hg help email``.
    3.74 +
    3.75 +.. _patchbomb: http://www.selenic.com/mercurial/
    3.76 +                      wiki/index.cgi/PatchbombExtension
    3.77 +
    3.78 +The advantage of using patchbomb is that allows everybody to go over
    3.79 +the code and comment on it before the changesets are pulled into the
    3.80 +repository. The mails sent out by patchbomb contain all the metadata
    3.81 +needed (name of committer, date, parent changeset, etc.) for importing
    3.82 +the changes into the repository, just as if the changesets had been
    3.83 +pulled using ``hg pull``.
    3.84 +
    3.85 +
    3.86 +Revising Changes
    3.87 +----------------
    3.88 +
    3.89 +When developing your changes you will probably make many commits
    3.90 +representing contained steps. Even though you have made a commit, you
    3.91 +can still change it *as long as you have not shared it with anybody*.
    3.92 +The idea is that you are allowed to rewrite history as you see fit in
    3.93 +your own private repository, but if your changes have been pulled to
    3.94 +the outside, then you can no longer change them.
    3.95 +
    3.96 +Also, you can only change commits in a linear history back from your
    3.97 +repository tip. This means that if you pull in changes from the main
    3.98 +VIFF repository and merge them periodically, then you can no longer
    3.99 +edit changesets past the last merge. We therefore recommend that you
   3.100 +develop your feature until you are satisfied with it and only merges
   3.101 +with whatever new changesets there might be in the VIFF repository
   3.102 +when the feature is done and debugged.
   3.103 +
   3.104 +Now, to change a past commit you use the `Mercurial Queues extension`_
   3.105 +also known as MQ. It gives you a powerful set of tools to work with
   3.106 +the past history. The basic concept is that changesets can be
   3.107 +converted into patches, which depend on each other and form a stack.
   3.108 +Like any good stack, you can push and pop elements from it. In this
   3.109 +case you push and pop patches.
   3.110 +
   3.111 +To get started you will want to import the normal changesets into MQ.
   3.112 +Let us suppose you found an error in revision 430 (use ``hg view`` or
   3.113 +``hg log`` to find the revision numbers). You then want to import
   3.114 +revision 430 and the following changesets into MQ with this command::
   3.115 +
   3.116 +   hg qimport -r 430:tip
   3.117 +
   3.118 +Nothing much happened — your working directory is left unchanged. To
   3.119 +see that the command did something you can check the current patch
   3.120 +series with ``hg qseries``. When importing changesets revision N is
   3.121 +called ``N.diff`` in the patch series.
   3.122 +
   3.123 +What we want is to pop off the other patches so that ``430.diff`` is
   3.124 +the topmost patch. This is done with::
   3.125 +
   3.126 +   hg qgoto 430.diff
   3.127 +
   3.128 +This updates your working directory to look exactly like it did when
   3.129 +you originally committed revision 430! You can now edit the files to
   3.130 +correct the error you found, and when you are done you run::
   3.131 +
   3.132 +   hg qrefresh
   3.133 +
   3.134 +to refresh the patch in ``430.diff``. You can use ``hg qrefresh -e``
   3.135 +to edit the commit message too. Now comes the fun part — you must now
   3.136 +push the the other patches back on the stack with::
   3.137 +
   3.138 +   hg qpush -a
   3.139 +
   3.140 +If this goes well with no complaints, then you can delete the patches
   3.141 +again with::
   3.142 +
   3.143 +   hg qdelete -r qbase:qtip
   3.144 +
   3.145 +The end result is a completely normal repository with no sign of this
   3.146 +surgery. You can repeat this as many times as needed to slowly develop
   3.147 +your patches until you are satisfied with the results.
   3.148 +
   3.149 +
   3.150 +If the changes you made to the patch are conflicting with other
   3.151 +patches in your stack, then the pushing will stop where the error was
   3.152 +encountered, and the conflicting patch hunk is stored in a ``.rej``
   3.153 +file. There is no need to panic if this happens — all you need to do
   3.154 +is to determine how the hunk in the ``.rej`` file(s) should be applied
   3.155 +(if at all) and then run ``hg qrefresh`` to indicate that the current
   3.156 +patch is okay. Now continue applying patches with ``hg qpush -a`` and
   3.157 +fix any remaining conflicts.
   3.158 +
   3.159 +
   3.160 +.. _Mercurial Queues extension: http://www.selenic.com/mercurial/
   3.161 +                                       wiki/index.cgi/MqExtension
   3.162 +
   3.163 +.. LocalWords:  changeset changesets
     4.1 --- a/doc/implementation.txt	Mon May 26 21:44:29 2008 +0200
     4.2 +++ b/doc/implementation.txt	Mon May 26 22:16:45 2008 +0200
     4.3 @@ -16,3 +16,6 @@
     4.4     prss
     4.5     config
     4.6     program-counters
     4.7 +   coding-style
     4.8 +   development
     4.9 +   unit-testing
     5.1 --- a/doc/index.txt	Mon May 26 21:44:29 2008 +0200
     5.2 +++ b/doc/index.txt	Mon May 26 22:16:45 2008 +0200
     5.3 @@ -13,7 +13,9 @@
     5.4  
     5.5     overview
     5.6     install
     5.7 +   presentations
     5.8     implementation
     5.9 +   bibliography
    5.10     glossary
    5.11  
    5.12  
     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/doc/presentations.txt	Mon May 26 22:16:45 2008 +0200
     6.3 @@ -0,0 +1,33 @@
     6.4 +
     6.5 +Presentations
     6.6 +=============
     6.7 +
     6.8 +The following VIFF-related presentations are available:
     6.9 +
    6.10 +February 21st, 2008:
    6.11 +  Slides used at a PhD Qualification Exam by Martin Geisler. Like the
    6.12 +  report they accompany, the second part of the slides are about VIFF
    6.13 +  and includes benchmark results.
    6.14 +
    6.15 +  Available as PDF__.
    6.16 +
    6.17 +  .. __: http://viff.dk/files/mg-progress-report-talk.pdf
    6.18 +
    6.19 +January 15th, 2008:
    6.20 +  PhD Progress Report by Martin Geisler. The second part of the report
    6.21 +  describes the design of VIFF and proves it secure in the Universally
    6.22 +  Composability security framework by Canetti.
    6.23 +
    6.24 +  Available as PDF__.
    6.25 +
    6.26 +  .. __: http://viff.dk/files/mg-progress-report.pdf
    6.27 +
    6.28 +September 20th, 2007:
    6.29 +  VIFF Design Talk given by Martin Geisler at a SIMAP_ meeting. The
    6.30 +  talk describes some of the goals of the VIFF design. It is current
    6.31 +  to version 0.2 of VIFF.
    6.32 +
    6.33 +  Available as PDF__.
    6.34 +
    6.35 +  .. _SIMAP: http://simap.dk/
    6.36 +  .. __: http://viff.dk/files/design-talk.pdf
     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/doc/unit-testing.txt	Mon May 26 22:16:45 2008 +0200
     7.3 @@ -0,0 +1,289 @@
     7.4 +.. -*- coding: utf-8 -*-
     7.5 +
     7.6 +==============
     7.7 + Unit Testing
     7.8 +==============
     7.9 +
    7.10 +VIFF employs a set of unit tests to help developers catch regressions
    7.11 +and to ensure the correctness of the implementation. The code is
    7.12 +continuously tested using a BuildBot_ and the results are available
    7.13 +online_. If you see warnings or errors from the unit tests on the
    7.14 +`BuildBot waterfall page`_, then please take it as an invitation to
    7.15 +fix them!
    7.16 +
    7.17 +.. _BuildBot: http://buildbot.net/
    7.18 +.. _online: http://buildbot.viff.dk/
    7.19 +.. _BuildBot waterfall page: http://buildbot.viff.dk/waterfall
    7.20 +
    7.21 +When using Twisted it is natural to use its unit testing framework
    7.22 +called Trial_. Trial has the big advantage over normal testing
    7.23 +frameworks that it understands Twisted's Deferreds_ — if a unit test
    7.24 +returns a Deferred, Trial waits for it to trigger before it declares
    7.25 +the test a success or failure. Please refer to this tutorial_ for more
    7.26 +information.
    7.27 +
    7.28 +.. _Trial: http://twistedmatrix.com/trac/wiki/TwistedTrial
    7.29 +.. _Deferreds: http://twistedmatrix.com/projects/core/
    7.30 +               documentation/howto/defer.html
    7.31 +.. _tutorial: http://twistedmatrix.com/trac/browser/branches/
    7.32 +              trial-tutorial-2443/doc/core/howto/trial.xhtml?format=raw
    7.33 +
    7.34 +Running the Unit Tests
    7.35 +----------------------
    7.36 +
    7.37 +To run the VIFF unit tests you must make sure that ``import viff``
    7.38 +works correctly in Python. In other words, you must make sure that
    7.39 +VIFF is installed or that the root of your source tree is in
    7.40 +``PYTHONPATH``. You can test this by changing to some unrelated
    7.41 +directory, starting an interactive Python session and run:
    7.42 +
    7.43 +.. sourcecode:: pycon
    7.44 +
    7.45 +  >>> import viff
    7.46 +  >>> print viff.__version__
    7.47 +  0.3
    7.48 +
    7.49 +If it fails with an ImportError, then please double-check that your
    7.50 +``PYTHONPATH`` is setup correctly.
    7.51 +
    7.52 +Now simply execute ``trial viff`` to run the unit tests. You should
    7.53 +get output similar to this::
    7.54 +
    7.55 +  % trial viff
    7.56 +  Seeding random generator with random seed 4658
    7.57 +  Running 65 tests.
    7.58 +  viff.test.test_active_runtime
    7.59 +    ActiveRuntimeTest
    7.60 +      test_broadcast ...                                           [OK]
    7.61 +  viff.test.test_basic_runtime
    7.62 +    ProgramCounterTest
    7.63 +      test_callback ...                                            [OK]
    7.64 +      test_complex_operation ...                                   [OK]
    7.65 +      test_initial_value ...                                       [OK]
    7.66 +      test_multiple_callbacks ...                             [SKIPPED]
    7.67 +      test_nested_calls ...                                        [OK]
    7.68 +      test_simple_operation ...                                    [OK]
    7.69 +  viff.test.test_field
    7.70 +    GF256TestCase
    7.71 +      test_add ...                                                 [OK]
    7.72 +      test_construct ...                                           [OK]
    7.73 +      test_div ...                                                 [OK]
    7.74 +      test_field ...                                               [OK]
    7.75 +      test_invert ...                                              [OK]
    7.76 +      test_mul ...                                                 [OK]
    7.77 +      test_neg ...                                                 [OK]
    7.78 +      test_pow ...                                                 [OK]
    7.79 +      test_str ...                                                 [OK]
    7.80 +      test_sub ...                                                 [OK]
    7.81 +      test_xor ...                                                 [OK]
    7.82 +    GFpElementTestCase
    7.83 +      test_add ...                                                 [OK]
    7.84 +      test_bit ...                                                 [OK]
    7.85 +      test_div ...                                                 [OK]
    7.86 +      test_field ...                                               [OK]
    7.87 +      test_invert ...                                              [OK]
    7.88 +      test_mul ...                                                 [OK]
    7.89 +      test_neg ...                                                 [OK]
    7.90 +      test_sqrt ...                                                [OK]
    7.91 +      test_str ...                                                 [OK]
    7.92 +      test_sub ...                                                 [OK]
    7.93 +  doctest
    7.94 +    DocTestCase
    7.95 +      field ...                                                    [OK]
    7.96 +      GF ...                                                       [OK]
    7.97 +      __eq__ ...                                                   [OK]
    7.98 +      __init__ ...                                                 [OK]
    7.99 +      __nonzero__ ...                                              [OK]
   7.100 +      __radd__ ...                                                 [OK]
   7.101 +      __rmul__ ...                                                 [OK]
   7.102 +  viff.test.test_prss
   7.103 +    PRSSTestCase
   7.104 +      test_generate_subsets ...                                    [OK]
   7.105 +  doctest
   7.106 +    DocTestCase
   7.107 +      PRF ...                                                      [OK]
   7.108 +      __call__ ...                                                 [OK]
   7.109 +      __init__ ...                                                 [OK]
   7.110 +      generate_subsets ...                                         [OK]
   7.111 +      prss ...                                                     [OK]
   7.112 +  viff.test.test_runtime
   7.113 +    RuntimeTest
   7.114 +      test_add ...                                                 [OK]
   7.115 +      test_add_coerce ...                                          [OK]
   7.116 +      test_convert_bit_share ...                                   [OK]
   7.117 +      test_greater_than ...                                        [OK]
   7.118 +      test_greater_than_equal ...                                  [OK]
   7.119 +      test_greater_than_equalII ...                                [OK]
   7.120 +      test_less_than ...                                           [OK]
   7.121 +      test_less_than_equal ...                                     [OK]
   7.122 +      test_mul ...                                                 [OK]
   7.123 +      test_open ...                                                [OK]
   7.124 +      test_open_no_mutate ...                                      [OK]
   7.125 +      test_prss_share_bit ...                                      [OK]
   7.126 +      test_prss_share_int ...                                      [OK]
   7.127 +      test_prss_share_random_bit ...                               [OK]
   7.128 +      test_prss_share_random_int ...                               [OK]
   7.129 +      test_shamir_share ...                                        [OK]
   7.130 +      test_shamir_share_asymmetric ...                             [OK]
   7.131 +      test_sub ...                                                 [OK]
   7.132 +      test_sub_coerce ...                                          [OK]
   7.133 +      test_xor ...                                                 [OK]
   7.134 +  doctest
   7.135 +    DocTestCase
   7.136 +      share ...                                                    [OK]
   7.137 +      clone_deferred ...                                           [OK]
   7.138 +      dlift ...                                                    [OK]
   7.139 +      find_prime ...                                               [OK]
   7.140 +
   7.141 +  =====================================================================
   7.142 +  [SKIPPED]: viff.test.test_basic_runtime.ProgramCounterTest.
   7.143 +  test_multiple_callbacks
   7.144 +
   7.145 +  TODO: Scheduling callbacks fails to increment program counter!
   7.146 +  ---------------------------------------------------------------------
   7.147 +  Ran 65 tests in 18.305s
   7.148 +
   7.149 +  PASSED (skips=1, successes=64)
   7.150 +
   7.151 +Lots of success! But one of the tests was skipped — we do this when we
   7.152 +have a test which represents a known problem. Otherwise every test run
   7.153 +would be cluttered with long of traceback messages, making it
   7.154 +difficult to notice new *unexpected* failures.
   7.155 +
   7.156 +
   7.157 +Writing Unit Tests
   7.158 +------------------
   7.159 +
   7.160 +The unit tests live in the ``viff.test`` package. There you will find
   7.161 +a number of modules, which in turn contain classes inheriting from
   7.162 +``twisted.trial.unittest.TestCase``. Trial recognizes these classes
   7.163 +and will execute methods starting with ``test``.
   7.164 +
   7.165 +Simple Tests
   7.166 +~~~~~~~~~~~~
   7.167 +
   7.168 +Adding a new unit test can be as simple as defining a new method in a
   7.169 +suitable class. The method will want to assert certain things during
   7.170 +the test, and for that Trial offers a large number of convenient
   7.171 +methods such as ``assertEqual``, ``assertTrue``, and so on. The full
   7.172 +reference is available `online`__. Notice that they describe the
   7.173 +methods under names like ``failUnlessSomething`` which is aliased to
   7.174 +``assertSomething``. So far all the VIFF unit tests use the
   7.175 +``assertSomething`` style, but you are welcome to use the other if you
   7.176 +prefer.
   7.177 +
   7.178 +.. __: http://twistedmatrix.com/documents/current/api/
   7.179 +       twisted.trial.unittest._Assertions.html
   7.180 +
   7.181 +A simple example of a unit test is ``viff.test.test_field`` which
   7.182 +looks like this (heavily abbreviated):
   7.183 +
   7.184 +.. sourcecode:: python
   7.185 +
   7.186 +  """Tests for viff.field."""
   7.187 +
   7.188 +  from viff.field import GF, GF256
   7.189 +  from twisted.trial.unittest import TestCase
   7.190 +
   7.191 +  #: Declare doctests for Trial.
   7.192 +  __doctests__ = ['viff.field']
   7.193 +
   7.194 +  class GFpElementTestCase(TestCase):
   7.195 +      """Tests for elements from a Zp field."""
   7.196 +
   7.197 +      def setUp(self):
   7.198 +          """Initialize Zp to Z31."""
   7.199 +          self.field = GF(31)
   7.200 +
   7.201 +      def test_invert(self):
   7.202 +          """Test inverse operation, including inverting zero."""
   7.203 +          self.assertRaises(ZeroDivisionError, lambda: ~self.field(0))
   7.204 +          self.assertEquals(~self.field(1), self.field(1))
   7.205 +
   7.206 +      def test_sqrt(self):
   7.207 +          """Test extraction of square roots."""
   7.208 +          square = self.field(4)**2
   7.209 +          root = square.sqrt()
   7.210 +          self.assertEquals(root**2, square)
   7.211 +
   7.212 +This demonstrates the most important features in a simple unit test:
   7.213 +
   7.214 +* First the needed definitions are imported as normal.
   7.215 +
   7.216 +* Setting the ``__doctest__`` field makes Trial run the doctests_ in
   7.217 +  the named module.
   7.218 +
   7.219 +* A class is defined which inherit from ``TestCase``.
   7.220 +
   7.221 +* A ``setUp`` method is used to collect preperations that are needed
   7.222 +  for every test.
   7.223 +
   7.224 +* Several test methods are defined. They make use of the assertions
   7.225 +  offered by Trial.
   7.226 +
   7.227 +.. _doctests: http://docs.python.org/lib/module-doctest.html
   7.228 +
   7.229 +
   7.230 +Tests Involving a VIFF Runtime
   7.231 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   7.232 +
   7.233 +Trial really shines when it comes to testing that involves networking.
   7.234 +First, it allows us to forget about the networking — the network
   7.235 +connections are replaced by direct method calls on the receiver's
   7.236 +transport. This makes the test repeatable unlike if real network
   7.237 +connections were used since they may fail if they cannot bind to the
   7.238 +wanted port number.
   7.239 +
   7.240 +In VIFF the ``util.py`` file contains the logic needed to connect a
   7.241 +number of Runtime instances in this way. All you need to do is to
   7.242 +create a subclass of RuntimeTestCase and decorate the test methods
   7.243 +with ``protocol`` like this example (abbreviated from
   7.244 +``viff.test.test_active_runtime``):
   7.245 +
   7.246 +.. sourcecode:: python
   7.247 +
   7.248 +  from viff.test.util import RuntimeTestCase, protocol
   7.249 +
   7.250 +  class ActiveRuntimeTest(RuntimeTestCase):
   7.251 +      """Test for active security."""
   7.252 +
   7.253 +      #: Number of players.
   7.254 +      num_players = 4
   7.255 +
   7.256 +      @protocol
   7.257 +      def test_broadcast(self, runtime):
   7.258 +          """Test Bracha broadcast."""
   7.259 +          if runtime.id == 1:
   7.260 +              x = runtime.broadcast([1], "Hello world!")
   7.261 +          else:
   7.262 +              x = runtime.broadcast([1])
   7.263 +          x.addCallback(self.assertEquals, "Hello world!")
   7.264 +          return x
   7.265 +
   7.266 +By decorating ``test_broadcast`` with ``protocol`` we ensure that the
   7.267 +method will be called with a Runtime instance. Furthermore, the method
   7.268 +will be called ``num_player`` times, each time with another Runtime
   7.269 +instance. The net result is that the test behaves just like if four
   7.270 +players had started four programs containing the method body.
   7.271 +
   7.272 +In the method you can branch on ``runtime.id``. This is needed in the
   7.273 +typical case where you want only one of the parties to input something
   7.274 +to a calculation.
   7.275 +
   7.276 +In this example all four parties get an ``x`` which will eventually
   7.277 +contain the string "Hello World". Using Trial we can return ``x`` and
   7.278 +Trial will then wait for ``x`` to trigger before declaring the test a
   7.279 +success or failure. We have attached ``self.assertEquals`` as a
   7.280 +callback on ``x`` with an extra argument of "Hello World". This means
   7.281 +that when ``x`` eventually triggers, the assertion is run and the test
   7.282 +finishes.
   7.283 +
   7.284 +This is the real power of Trial. You can do some calculations and
   7.285 +finish by returning a Deferred (and remember that Shares are Deferreds
   7.286 +in VIFF). The value of this Deferred is not important, it is only
   7.287 +important that it triggers when the test is done. You will often need
   7.288 +to use ``twisted.internet.defer.gatherResults`` to combine several
   7.289 +Deferreds into one that you can return to Trial. Just make sure that
   7.290 +your final Deferred depends on all other Deferreds so that you do not
   7.291 +leave lingering Deferreds behind. Trial will complain loudly if you
   7.292 +do, so it should be easy to spot.