diff options
Diffstat (limited to 'nova/tests/unit/README.rst')
-rw-r--r-- | nova/tests/unit/README.rst | 95 |
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 |