Finished off testing docs, put in nosewrapper script because it's a pain to get plugins in the path any other way.

doc/testing.rst

@@ -3,6 +3,18 @@ Testing Eventlet
 
 Eventlet is tested using `Nose <http://somethingaboutorange.com/mrl/projects/nose/>`_.  To run tests, simply install nose, and then, in the eventlet tree, do:
 
+.. code-block:: sh
+
+  $ python setup.py test
+  
+If you want access to all the nose plugins via command line, you can run:
+
+.. code-block:: sh
+
+  $ python setup.py nosetests
+
+Lastly, you can just use nose directly if you want:
+
 .. code-block:: sh
 
   $ nosetests
@@ -24,4 +36,24 @@ Run the standard library tests with nose; simply do:
   $ cd tests/
   $ nosetests stdlib
   
-That should get you started.  Note that most of the test failures are caused by `Nose issue 162 <http://code.google.com/p/python-nose/issues/detail?id=162>`_, which incorrectly identifies helper methods as test cases.  Therefore, ignore any failure for the reason ``TypeError: foo() takes exactly N arguments (2 given)``, and sit tight until a version of Nose is released that fixes the issue.
+That should get you started.  At this time this generates a bunch of spurious failures, due to `Nose issue 162 <http://code.google.com/p/python-nose/issues/detail?id=162>`_, which incorrectly identifies helper methods as test cases.  Therefore, ignore any failure for the reason ``TypeError: foo() takes exactly N arguments (2 given)``, and sit tight until a version of Nose is released that fixes the issue.
+
+Testing Eventlet Hubs
+---------------------
+
+When you run the tests, Eventlet will use the most appropriate hub for the current platform to do its dispatch.  It's sometimes useful when making changes to Eventlet to test those changes on hubs other than the default.  You can do this with the eventlethub nose plugin.  The plugin is not installed in your system, so in order to get Nose to see it, we have to call a wrapper script instead of Nose:
+
+.. code-block:: sh
+
+ $ python tests/nosewrapper.py --with-eventlethub --hub=selects
+ 
+``nosewrapper.py`` takes exactly the same arguments as nosetests, and behaves exactly the same way.  Here's what the two arguments mean:
+
+* ``--with-eventlethub`` enables the eventlethub plugin.
+* ``--hub=HUB`` specifies which Eventlet hub to use during the tests.
+
+If you wish to run tests against a particular Twisted reactor, use `--reactor=REACTOR` instead of ``--hub``.  The full list of eventlet hubs is currently:
+
+* poll
+* selects
+* libevent  (requires pyevent)

setup.py

@@ -28,6 +28,7 @@ setup(
     retaining high programmer usability by using coroutines to make
     the non-blocking io operations appear blocking at the source code
     level.""",
+    test_suite = 'nose.collector',
     classifiers=[
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python",

tests/eventlethub.py

@@ -23,26 +23,26 @@ import logging
 from nose.plugins.base import Plugin
 from eventlet import api
 
-log = logging.getLogger('nose.plugins.eventlet_hub')
+log = logging.getLogger('nose.plugins.eventlethub')
 
 class EventletHub(Plugin):
     name = 'eventlethub'
 
     def options(self, parser, env):
         super(EventletHub, self).options(parser, env)
-        parser.add_option('--eventlet-hub',
+        parser.add_option('--hub',
                           dest="eventlet_hub",
                           metavar="HUB",
                           default=env.get('NOSE_EVENTLET_HUB'),
                           help="Use the specified eventlet hub for the tests."\
                            " [NOSE_EVENTLET_HUB]")
-        parser.add_option('--eventlet-reactor',
+        parser.add_option('--reactor',
                           dest="eventlet_reactor",
                           metavar="REACTOR",
                           default=env.get('NOSE_EVENTLET_REACTOR'),
                           help="Use the specified Twisted reactor for the "\
                           "tests.  Use of this flag forces the twisted hub, "\
-                          "as if --eventlet-hub=twistedr was also supplied. "\
+                          "as if --hub=twistedr was also supplied. "\
                           "[NOSE_EVENTLET_REACTOR]")
 
                            
@@ -59,7 +59,7 @@ class EventletHub(Plugin):
             self.twisted_already_used = False
             if self.reactor is None:
                 raise ValueError("Can't have twisted hub without specifying a "\
-                "reactor.  Use --eventlet-reactor instead.")
+                "reactor.  Use --reactor instead.")
 
             m = __import__('twisted.internet.' + self.reactor)
             getattr(m.internet, self.reactor).install()
@@ -74,7 +74,9 @@ class EventletHub(Plugin):
         """Select the desired hub.
         """        
         if self.hub_name is None:
-            log.warn('using *default* eventlet hub: %s', api.get_hub())
+            log.warn('Using default eventlet hub: %s, did you mean '\
+                     'to supply --hub command line argument?', 
+                     api.get_hub().__module__)
         else:
             if self.hub_name == 'twistedr':
                 if self.twisted_already_used:

tests/nosewrapper.py

@@ -0,0 +1,32 @@
+# Copyright (c) 2007, Linden Research, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+""" This script simply gets the paths correct for testing eventlet with the 
+hub extension for Nose."""
+import nose
+from os.path import dirname, realpath, abspath
+import sys
+
+parent_dir = dirname(dirname(realpath(abspath(__file__))))
+if parent_dir not in sys.path:
+    sys.path.insert(0, parent_dir)
+
+from tests import eventlethub
+nose.main(addplugins=[eventlethub.EventletHub()])