1 files changed, 95 insertions, 0 deletions
diff --git a/nova/tests/unit/README.rst b/nova/tests/unit/README.rst
new file mode 100644
index 0000000000..8ac999c740
--- /dev/null
+++ b/nova/tests/unit/README.rst
@@ -0,0 +1,95 @@
+=====================================
+OpenStack Nova Testing Infrastructure
+=====================================
+
+This README file attempts to provide current and prospective contributors with
+everything they need to know in order to start creating unit tests for nova.
+
+Note: the content for the rest of this file will be added as the work items in
+the following blueprint are completed:
+  https://blueprints.launchpad.net/nova/+spec/consolidate-testing-infrastructure
+
+
+Test Types: Unit vs. Functional vs. Integration
+-----------------------------------------------
+
+TBD
+
+Writing Unit Tests
+------------------
+
+TBD
+
+Using Fakes
+~~~~~~~~~~~
+
+TBD
+
+test.TestCase
+-------------
+The TestCase class from nova.test (generally imported as test) will
+automatically manage self.stubs using the stubout module and self.mox
+using the mox module during the setUp step. They will automatically
+verify and clean up during the tearDown step.
+
+If using test.TestCase, calling the super class setUp is required and
+calling the super class tearDown is required to be last if tearDown
+is overridden.
+
+Writing Functional Tests
+------------------------
+
+TBD
+
+Writing Integration Tests
+-------------------------
+
+TBD
+
+Tests and Exceptions
+--------------------
+A properly written test asserts that particular behavior occurs. This can
+be a success condition or a failure condition, including an exception.
+When asserting that a particular exception is raised, the most specific
+exception possible should be used.
+
+In particular, testing for Exception being raised is almost always a
+mistake since it will match (almost) every exception, even those
+unrelated to the exception intended to be tested.
+
+This applies to catching exceptions manually with a try/except block,
+or using assertRaises().
+
+Example::
+
+    self.assertRaises(exception.InstanceNotFound, db.instance_get_by_uuid,
+                      elevated, instance_uuid)
+
+If a stubbed function/method needs a generic exception for testing
+purposes, test.TestingException is available.
+
+Example::
+
+    def stubbed_method(self):
+        raise test.TestingException()
+    self.stubs.Set(cls, 'inner_method', stubbed_method)
+
+    obj = cls()
+    self.assertRaises(test.TestingException, obj.outer_method)
+
+
+Stubbing and Mocking
+--------------------
+
+Whenever possible, tests SHOULD NOT stub and mock out the same function.
+
+If it's unavoidable, tests SHOULD define stubs before mocks since the
+`TestCase` cleanup routine will un-mock before un-stubbing. Doing otherwise
+results in a test that leaks stubbed functions, causing hard-to-debug
+interference between tests [1]_.
+
+If a mock must take place before a stub, any stubs after the mock call MUST be
+manually unset using `self.cleanUp` calls within the test.
+
+
+.. [1] https://bugs.launchpad.net/nova/+bug/1180671