From b7714e82fdbede2dfe328eaae0add07f6e2b92c5 Mon Sep 17 00:00:00 2001 From: Monty Taylor Date: Mon, 11 Feb 2013 15:22:24 -0600 Subject: Update docs about testing. Add an entry to the HACKING file about testr. While in there, noticed a reference to the now-defunct nova/testing dir. Fixed that, moved the testing README into nova/tests and remove the nova/testing dir. Change-Id: Ibf6fb82658ba73eee9123fa53b340d0b72afb292 --- HACKING.rst | 22 ++++++++++++- nova/testing/README.rst | 86 ------------------------------------------------ nova/testing/__init__.py | 0 nova/tests/README.rst | 78 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 99 insertions(+), 87 deletions(-) delete mode 100644 nova/testing/README.rst delete mode 100644 nova/testing/__init__.py create mode 100644 nova/tests/README.rst diff --git a/HACKING.rst b/HACKING.rst index 213495832..fade33ee4 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -218,7 +218,27 @@ submitted bug fix does have a unit test, be sure to add a new one that fails without the patch and passes with the patch. For more information on creating unit tests and utilizing the testing -infrastructure in OpenStack Nova, please read nova/testing/README.rst. +infrastructure in OpenStack Nova, please read nova/tests/README.rst. + + +Running Tests +------------- +The testing system is based on a combination of tox and testr. The canonical +approach to running tests is to simply run the command `tox`. This will +create virtual environments, populate them with depenedencies and run all of +the tests that OpenStack CI systems run. Behind the scenes, tox is running +`testr run --parallel`, but is set up such that you can supply any additional +testr arguments that are needed to tox. For example, you can run: +`tox -- --analyze-isolation` to cause tox to tell testr to add +--analyze-isolation to its argument list. + +It is also possible to run the tests inside of a virtual environment +you have created, or it is possible that you have all of the dependencies +installed locally already. In this case, you can interact with the testr +command directly. Running `testr run` will run the entire test suite. `testr +run --parallel` will run it in parallel (this is the default incantation tox +uses.) More information about testr can be found at: +http://wiki.openstack.org/testr openstack-common diff --git a/nova/testing/README.rst b/nova/testing/README.rst deleted file mode 100644 index 4c341b7ed..000000000 --- a/nova/testing/README.rst +++ /dev/null @@ -1,86 +0,0 @@ -===================================== -OpenStack Nova Testing Infrastructure -===================================== - -A note of clarification is in order, to help those who are new to testing in -OpenStack nova: - -- actual unit tests are created in the "tests" directory; -- the "testing" directory is used to house the infrastructure needed to support - testing in OpenStack Nova. - -This README file attempts to provide current and prospective contributors with -everything they need to know in order to start creating unit tests and -utilizing the convenience code provided in nova.testing. - -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 overriden. - -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) diff --git a/nova/testing/__init__.py b/nova/testing/__init__.py deleted file mode 100644 index e69de29bb..000000000 diff --git a/nova/tests/README.rst b/nova/tests/README.rst new file mode 100644 index 000000000..76b92258a --- /dev/null +++ b/nova/tests/README.rst @@ -0,0 +1,78 @@ +===================================== +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 overriden. + +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) -- cgit