Merge lp:~andrea-crotti-0/mailman/test_doc into lp:mailman

[Andrea Crotti]

Added some doc from the Testing instructions in the e-mail.

This is far from perfect but I don't know much about it yet, so please give me some feedback about how it should be structured and what I should add..

[Barry Warsaw (barry)]

Thanks for taking a shot at this! Here are some comments:

Notice that there is a template.py file in the top level directory. This is a great way to start any new .py file (except __init__.py files which are typically empty). So if you're adding a new test_foo.py file, start with the template.

You might describe how to run a single test, e.g.

    $ bin/test -t test_simple_wrap

will run just that one test, while

    $ bin/test -t test_headers

will run all the tests in the test_headers.py file.

    $ bin/test -t users.rst

will run that doctest. This isn't really Mailman specific; it's all zope.testing.

Also perhaps describe the -vv option, which I use all the time.

From there, I'd say you could describe some some about how the project is managed, e.g.

 - Branches and merge proposals are preferred over patches (though patches may be accepted)
 - I prefer a branch/merge-proposal to be attached to a bug since then we can milestone it and include a note in the NEWS.rst file.
 - Please include a test in every branch. Documentation is nice too, as is a NEWS.rst file entry (but the latter is optional, especially if there is a bug report).

Please make sure to run the full test suite to make sure your branch doesn't regress.

That's probably it for now. This is a great start and could eventually be expanded to explain other aspects for contributors. But we can wait on that. :)

review: Needs Fixing

[Barry Warsaw (barry)]

This branch is pretty far out of date with trunk. Thanks for the contribution, but I'm going to close this merge proposal.

Unmerged revisions

7126. By Andrea Crotti on 2012-03-19

- refactor the testing information
- add CONTRIBUTING to the TOC

7125. By Andrea Crotti on 2012-03-19

add first sample of documentation for testing

=== modified file 'README.rst'
--- README.rst	2012-03-14 20:49:09 +0000
+++ README.rst	2012-03-19 22:12:19 +0000
@@ -38,6 +38,7 @@
     src/mailman/docs/DATABASE
     src/mailman/docs/MTA
     src/mailman/docs/8-miles-high
+    src/mailman/docs/CONTRIBUTING
     src/mailman/bin/docs/*
     src/mailman/commands/docs/*
     src/mailman/database/docs/*

=== added file 'src/mailman/docs/CONTRIBUTING.rst'
--- src/mailman/docs/CONTRIBUTING.rst	1970-01-01 00:00:00 +0000
+++ src/mailman/docs/CONTRIBUTING.rst	2012-03-19 22:12:19 +0000
@@ -0,0 +1,81 @@
+============
+Contributing
+============
+
+Tests
+=====
+
+Setup
+-----
+
+First make sure you set up your buildout correctly with:
+
+::
+
+    python bootstrap.py && bin/buildout
+
+This will generate the *bin/test* script, which is the main script to run the project tests.
+
+
+Layout
+------
+
+Essentially all unittests live in a test_foo.py module inside a tests/
+directory (which has an __init__.py so it's a package).
+
+unittest.TestCase subclasses are named TestFoo and individual tests
+inside there as test_foo() methods.
+
+.. It's only a little extra work if you have to create a new tests/
+.. subdirectory or test_foo.py module, but again, it should be pretty
+.. straightforward.
+
+::
+
+    class TestListLifecycleEvents(unittest.TestCase):
+        layer = ConfigLayer
+    
+        def setUp(self):
+            self._ant = create_list('[e-mail]')
+            self._bee = create_list('[e-mail]')
+            self._usermanager = getUtility(IUserManager)
+    
+
+Tests are automatically discovered by the zope.testing framework, and
+we use *layers* to set up expensive resources among a suite of tests.
+
+E.g. if you need the rest server to be started, you'd use the
+RESTLayer (see mailman.testing.layers for what's currently defined).
+
+To enable a layer, you just need to set the `layer` attribute of the
+TestFoo class.
+
+Almost all the tests will require at least the ConfigLayer since that
+brings up the Zope component architecture, connfiguration system.
+
+Note that doctests are all set up in test_documentation.py so they're
+not really all that special.
+
+
+Possible issues
+---------------
+
+zope.testing is a bit weird here because the normal rules of subclasses don't
+actually apply.  E.g. the LMTPLayer derives from ConfigLayer which derives
+from MockAndMonkeyLayer.  
+
+All the appropriate setUp()s get called by zope.testing so you don't
+need to up-call explicitly in the layer class.
+
+.. too much magic and would be good to switch to something else
+
+
+Test coverage
+=============
+
+You can see the tests coverage using
+
+
+::
+
+   bin/test coverage=coveragepy