diff --git a/TESTING.rst b/TESTING.rst new file mode 100644 index 000000000..aeaf3cef7 --- /dev/null +++ b/TESTING.rst @@ -0,0 +1,187 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + + Convention for heading levels in GBP devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +Testing GBP +=============== + + +Running Tests +------------- + +There are two mechanisms for running tests: run_tests.sh, and tox. +Before submitting a patch for review you should always +ensure all test pass; a tox run is triggered by the jenkins gate +executed on gerrit for each patch pushed for review. + +With these mechanisms you can either run the tests in the standard +environment or create a virtual environment to run them in. + +By default after running all of the tests, any pep8 errors +found in the tree will be reported. + + +With `run_tests.sh` +~~~~~~~~~~~~~~~~~~~ + +You can use the `run_tests.sh` script in the root source directory to execute +tests in a virtualenv:: + + ./run_tests -V + + +With `tox` +~~~~~~~~~~ + +GBP, like other OpenStack projects, uses `tox`_ for managing the virtual +environments for running test cases. It uses `Testr`_ for managing the running +of the test cases. + +Tox handles the creation of a series of `virtualenvs`_ that target specific +versions of Python. + +Testr handles the parallel execution of series of test cases as well as +the tracking of long-running tests and other things. + +For more information on the standard Tox-based test infrastructure used by +OpenStack and how to do some common test/debugging procedures with Testr, +see this wiki page: + + https://wiki.openstack.org/wiki/Testr + +.. _Testr: https://wiki.openstack.org/wiki/Testr +.. _tox: http://tox.readthedocs.org/en/latest/ +.. _virtualenvs: https://pypi.python.org/pypi/virtualenv + +PEP8 and Unit Tests ++++++++++++++++++++ + +Running pep8 and unit tests is as easy as executing this in the root +directory of the GBP source code:: + + tox + +To run only pep8:: + + tox -e pep8 + +To restrict pep8 check to only the files altered by the latest patch changes:: + + tox -e pep8 HEAD~1 + +To run only the unit tests:: + + tox -e py27 + + +Running Individual Tests +~~~~~~~~~~~~~~~~~~~~~~~~ + +For running individual test modules, cases or tests, you just need to pass +the dot-separated path you want as an argument to it. + +For example, the following would run only a single test or test case:: + + $ ./run_tests.sh gbpservice.neutron.tests.unit.test_extension_group_policy + $ ./run_tests.sh gbpservice.neutron.tests.unit.test_extension_group_policy.GroupPolicyExtensionTestCase + $ ./run_tests.sh gbpservice.neutron.tests.unit.test_extension_group_policy.GroupPolicyExtensionTestCase.test_create_policy_target + +or:: + + $ tox -e py27 gbpservice.neutron.tests.unit.test_extension_group_policy + $ tox -e py27 gbpservice.neutron.tests.unit.test_extension_group_policy.GroupPolicyExtensionTestCase + $ tox -e py27 gbpservice.neutron.tests.unit.test_extension_group_policy.GroupPolicyExtensionTestCase.test_create_policy_target + +If you want to pass other arguments to ostestr, you can do the following:: + $ tox -e -epy27 -- --regex gbpservice.neutron.tests.unit.test_extension_group_policy --serial + + +Coverage +-------- + +To get a grasp of the areas where tests are needed, you can check +current unit tests coverage by running:: + + $ ./run_tests.sh -c + +or by running:: + + $ tox -ecover + +Note that this is also useful to run before submitting a new patchset +to ensure that the new code you are introducing has adequate unit test +coverage. + + +Debugging +--------- + +By default, calls to pdb.set_trace() will be ignored when tests +are run. For pdb statements to work, invoke run_tests as follows:: + + $ ./run_tests.sh -d [test module path] + +It's possible to debug tests in a tox environment:: + + $ tox -e venv -- python -m testtools.run [test module path] + +Tox-created virtual environments (venv's) can also be activated +after a tox run and reused for debugging:: + + $ tox -e venv + $ . .tox/venv/bin/activate + $ python -m testtools.run [test module path] + +Tox packages and installs the GBP source tree in a given venv +on every invocation, but if modifications need to be made between +invocation (e.g. adding more pdb statements), it is recommended +that the source tree be installed in the venv in editable mode:: + + # run this only after activating the venv + $ pip install --editable . + +Editable mode ensures that changes made to the source tree are +automatically reflected in the venv, and that such changes are not +overwritten during the next tox run. + +Post-mortem Debugging +~~~~~~~~~~~~~~~~~~~~~ + +Setting OS_POST_MORTEM_DEBUGGER in the shell environment will ensure +that the debugger .post_mortem() method will be invoked on test failure:: + + $ OS_POST_MORTEM_DEBUGGER=pdb ./run_tests.sh -d [test module path] + +Supported debuggers are pdb, and pudb. Pudb is full-screen, console-based +visual debugger for Python which let you inspect variables, the stack, +and breakpoints in a very visual way, keeping a high degree of compatibility +with pdb:: + + $ ./.venv/bin/pip install pudb + + $ OS_POST_MORTEM_DEBUGGER=pudb ./run_tests.sh -d [test module path] + +References +~~~~~~~~~~ + +.. [#pudb] PUDB debugger: + https://pypi.python.org/pypi/pudb diff --git a/doc/source/devref/development.environment.rst b/doc/source/devref/development.environment.rst new file mode 100644 index 000000000..d64fc51e9 --- /dev/null +++ b/doc/source/devref/development.environment.rst @@ -0,0 +1,55 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + + Convention for heading levels in GBP devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +Setting Up a Development Environment +==================================== + +This page describes how to setup a working Python development +environment that can be used in developing GBP on Ubuntu, Fedora or +Mac OS X. These instructions assume you're already familiar with +Git and Gerrit, which is a code repository mirror and code review toolset +, however if you aren't please see `this Git tutorial`_ for an introduction +to using Git and `this guide`_ for a tutorial on using Gerrit and Git for +code contribution to OpenStack projects. + +.. _this Git tutorial: http://git-scm.com/book/en/Getting-Started +.. _this guide: http://docs.openstack.org/infra/manual/developers.html#development-workflow + +Following these instructions will allow you to run the GBP unit +tests. If you want to be able to run GBP in a full OpenStack environment, +you can use the excellent `DevStack`_ project to do so. There is a wiki page +that describes `setting up GBP using DevStack`_. + +.. _DevStack: https://git.openstack.org/cgit/openstack-dev/devstack +.. _setting up GBP using Devstack: https://wiki.openstack.org/wiki/GroupBasedPolicy/InstallDevstack + +Getting the code +---------------- + +Grab the code:: + + git clone git://git.openstack.org/openstack/group-based-policy.git + cd group-based-policy + + +.. include:: ../../../TESTING.rst diff --git a/doc/source/devref/images/README b/doc/source/devref/images/README new file mode 100644 index 000000000..4cc5b53e6 --- /dev/null +++ b/doc/source/devref/images/README @@ -0,0 +1,3 @@ +This is a placeholder file until images get added to this directory. +When the first image is added to this director, this README file +can be deleted. diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst new file mode 100644 index 000000000..e643aefa9 --- /dev/null +++ b/doc/source/devref/index.rst @@ -0,0 +1,60 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +Developer Guide +=============== + +In the Developer Guide, you will find information on the design and +implementation of Group Based Policy's software components. + + +Programming HowTos and Tutorials +-------------------------------- +.. toctree:: + :maxdepth: 3 + + development.environment + + +GBP Design +---------- +.. toctree:: + :maxdepth: 3 + + gbp_resource_model + gbp_plugin_and_driver_architecture + gbp_driver_extensions + implicit_mapping_policy_driver + resource_mapping_policy_driver + gbp_external_connectivity + gbp_service_chaining_model + gbp_node_composition_plugin_and_driver_architecture + gbp_traffic_stitching_plumber + + +Module Reference +---------------- +.. toctree:: + :maxdepth: 3 + +.. todo:: + + Add in all the big modules as automodule indexes. + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search`