- ``repoze.bfg.testing.registerRoutesMapper`` testing facility added.

  This testing function registers a routes "mapper" object in the
  registry, for tests which require its presence.  This function is
  documented in the ``repoze.bfg.testing`` API documentation.

5 files changed, 57 insertions, 0 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 744e5c406..5b1a4cc15 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,6 +1,14 @@
 Next release
 ============
 
+Features
+--------
+
+- ``repoze.bfg.testing.registerRoutesMapper`` testing facility added.
+  This testing function registers a routes "mapper" object in the
+  registry, for tests which require its presence.  This function is
+  documented in the ``repoze.bfg.testing`` API documentation.
+
 Bug Fixes
 ---------
 
diff --git a/docs/api/testing.rst b/docs/api/testing.rst
index c18f24195..e0df091bc 100644
--- a/docs/api/testing.rst
+++ b/docs/api/testing.rst
@@ -25,6 +25,8 @@
 
   .. autofunction:: registerRoute
 
+  .. autofunction:: registerRoutesMapper
+
   .. autofunction:: registerSettings
 
   .. autofunction:: setUp
diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst
index 2d2ccec56..5808d05fd 100644
--- a/docs/whatsnew-1.1.rst
+++ b/docs/whatsnew-1.1.rst
@@ -614,6 +614,12 @@ Minor Miscellaneous Feature Additions
   Like any framework event, a subscriber function should expect one
   parameter: ``event``.
 
+- A ``repoze.bfg.testing.registerRoutesMapper`` testing facility has
+  been added.  This testing function registers a routes "mapper"
+  object in the registry, for tests which require its presence.  This
+  function is documented in the ``repoze.bfg.testing`` API
+  documentation.
+
 Backwards Incompatibilities
 ---------------------------
 
diff --git a/repoze/bfg/testing.py b/repoze/bfg/testing.py
index 7765a17cc..8e6c8af82 100644
--- a/repoze/bfg/testing.py
+++ b/repoze/bfg/testing.py
@@ -238,6 +238,33 @@ def registerRoute(path, name, factory=None):
         sm.registerUtility(mapper, IRoutesMapper)
     mapper.connect(path, name, factory)
 
+def registerRoutesMapper(root_factory=None):
+    """ Register a new routes mapper using the provided
+    ``root_factory`` as the root factory it wraps.  If
+    ``root_factory`` is ``None``, use a default root factory
+    implementation.
+
+    Use of this function is beneficial when you want to register an
+    empty routes mapper with a custom ``root_factory``.
+
+    Note that ``repoze.bfg.testing.registerRoute`` also registers a
+    route mapper if one is not already registered, thus it is not
+    necessary to call this function before calling
+    ``repoze.bfg.testing.registerRoute``.  However, if
+    ``repoze.bfg.registerRoutesMapper`` *is* called before
+    ``repoze.bfg.testing.registerRoute``, the routes mapper registered
+    by ``repoze.bfg.testing.registerRoutesMapper`` will be used as the
+    mapper in which the route is registered during
+    ``repoze.bfg.testing.registerRoute``."""
+    from repoze.bfg.interfaces import IRoutesMapper
+    from repoze.bfg.urldispatch import RoutesRootFactory
+    if root_factory is None:
+        root_factory = DummyRootFactory
+    mapper = RoutesRootFactory(root_factory)
+    sm = getSiteManager()
+    sm.registerUtility(mapper, IRoutesMapper)
+    return mapper
+
 def registerSettings(dictarg=None, **kw):
     """ Register one or more 'setting' key/value pairs.  A setting is
     a single key/value pair in the dictionary-ish object returned from
diff --git a/repoze/bfg/tests/test_testing.py b/repoze/bfg/tests/test_testing.py
index 130dc9105..4981b6d68 100644
--- a/repoze/bfg/tests/test_testing.py
+++ b/repoze/bfg/tests/test_testing.py
@@ -277,6 +277,20 @@ class TestTestingFunctions(unittest.TestCase):
         self.assertEqual(route_url('home', request, pagename='abc'),
                          'http://example.com/abc')
 
+    def test_registerRoutesMapper(self):
+        from repoze.bfg.interfaces import IRoutesMapper
+        from repoze.bfg.testing import registerRoutesMapper
+        from zope.component import getSiteManager
+        class Factory:
+            def __init__(self, environ):
+                """ """
+        class DummyRequest:
+            application_url = 'http://example.com'
+        result = registerRoutesMapper()
+        sm = getSiteManager()
+        mapper = sm.getUtility(IRoutesMapper)
+        self.assertEqual(result, mapper)
+
     def test_registerSettings(self):
         from repoze.bfg.interfaces import ISettings
         from repoze.bfg.testing import registerSettings