Add per_module_scenarios

4 files changed, 87 insertions, 2 deletions

diff --git a/NEWS b/NEWS
index db185e2..bdcf729 100644
--- a/NEWS
+++ b/NEWS
@@ -9,6 +9,12 @@ IN DEVELOPMENT
 0.2
 ~~~
 
+NEW FEATURES:
+
+* New function ``per_module_scenarios`` for tests that should be applied across 
+  multiple modules providing the same interface, some of which may not be 
+  available at run time.  (Martin Pool)
+
 CHANGES:
 
 * Adjust the cloned tests ``shortDescription`` if one is present. (Ben Finney)
diff --git a/README b/README
index 887a6ad..90b418e 100644
--- a/README
+++ b/README
@@ -258,6 +258,35 @@ allowing it to be used to layer scenarios without affecting existing scenario
 selection.
 
 
+Generating Scenarios
+====================
+
+Some functions (currently one :-) are available to ease generation of scenario
+lists for common situations.
+
+Testing Per Implementation Module
++++++++++++++++++++++++++++++++++
+
+It is reasonably common to have multiple Python modules that provide the same
+capabilities and interface, and to want apply the same tests to all of them.
+
+In some cases, not all of the statically defined implementations will be able
+to be used in a particular testing environment.  For example, there may be both
+a C and a pure-Python implementation of a module.  You want to test the C
+module if it can be loaded, but also to have the tests pass if the C module has
+not been compiled.
+
+The ``per_module_scenarios`` function generates a scenario for each named
+module, omitting those that raise an ``ImportError``.  For each test object,
+the implementation to be tested is installed into a given attribute.
+
+Note that for the test to be valid, all access to the module under test must go
+through the relevant attribute of the test object.  If one of the
+implementations is also directly imported by the test module or any other,
+testscenarios will not magically stop it being used.
+
+
+
 Advice on Writing Scenarios
 ===========================
 
diff --git a/lib/testscenarios/scenarios.py b/lib/testscenarios/scenarios.py
index 80847d6..e052c22 100644
--- a/lib/testscenarios/scenarios.py
+++ b/lib/testscenarios/scenarios.py
@@ -2,7 +2,7 @@
 #  dependency injection ('scenarios') by tests.
 #
 # Copyright (c) 2009, Robert Collins <robertc@robertcollins.net>
-# Copyright (c) 2010 Martin Pool <mbp@sourcefrog.net>
+# Copyright (c) 2010, 2011 Martin Pool <mbp@sourcefrog.net>
 # 
 # Licensed under either the Apache License, Version 2.0 or the BSD 3-clause
 # license at the users choice. A copy of both licenses are available in the
@@ -129,3 +129,37 @@ def multiply_scenarios(*scenarios):
             scenario_parameters.update(parameter)
         result.append((scenario_name, scenario_parameters))
     return result
+
+
+def per_module_scenarios(attribute_name, modules):
+    """Generate scenarios for available implementation modules.
+
+    This is typically used when there is a subsystem implemented, for
+    example, in both Python and C, and we want to apply the same tests to
+    both, but the C module may sometimes not be available.
+
+    Note: if the module can't be loaded, it's silently omitted from
+    testing.
+
+    :param attribute_name: A name to be set in the scenario parameter
+        dictionary (and thence onto the test instance) pointing to the 
+        implementation module for this scenario.
+
+    :param modules: An iterable of (short_name, module_name), where 
+        the short name is something like 'python' to put in the
+        scenario name, and the long name is a fully-qualified Python module
+        name.
+    """
+    scenarios = []
+    for short_name, module_name in modules:
+        try:
+            mod = __import__(module_name, {}, {}, [''])
+        except ImportError:
+            # TODO: optionally pass this back through a callback, so it can be
+            # logged etc?
+            pass
+        else:
+            scenarios.append((
+                short_name, 
+                {attribute_name: mod}))
+    return scenarios
diff --git a/lib/testscenarios/tests/test_scenarios.py b/lib/testscenarios/tests/test_scenarios.py
index 063df51..1fe12ed 100644
--- a/lib/testscenarios/tests/test_scenarios.py
+++ b/lib/testscenarios/tests/test_scenarios.py
@@ -2,7 +2,7 @@
 #  dependency injection ('scenarios') by tests.
 #
 # Copyright (c) 2009, Robert Collins <robertc@robertcollins.net>
-# Copyright (c) 2010 Martin Pool <mbp@sourcefrog.net>
+# Copyright (c) 2010, 2011 Martin Pool <mbp@sourcefrog.net>
 # 
 # Licensed under either the Apache License, Version 2.0 or the BSD 3-clause
 # license at the users choice. A copy of both licenses are available in the
@@ -239,3 +239,19 @@ class TestMultiplyScenarios(testtools.TestCase):
         self.assertEqual(
             'a,a,a,a',
             scenarios[0][0])
+
+
+class TestPerModuleScenarios(testtools.TestCase):
+
+    def test_per_module_scenarios(self):
+        """Generate scenarios for available modules"""
+        s = testscenarios.scenarios.per_module_scenarios(
+            'the_module', [
+                ('Python', 'testscenarios'),
+                ('unittest', 'unittest'),
+                ('nonexistent', 'nonexistent'),
+                ])
+        self.assertEqual(s, [
+            ('Python', {'the_module': testscenarios}),
+            ('unittest', {'the_module': unittest}),
+            ])