Developing with OpenStackClient

Communication

Meetings

The OpenStackClient team meets regularly on every Thursday. For details please refer to the wiki.

Testing

Using tox

Before running tests, you should have tox installed and available in your environment:

$ pip install tox

To execute the full suite of tests maintained within OpenStackClient, run:

$ tox

Note

The first time you run tox, it will take additional time to build virtualenvs. You can later use the -r option with tox to rebuild your virtualenv in a similar manner.

To run tests for one or more specific test environments (for example, the most common configuration of Python 2.7 and PEP-8), list the environments with the -e option, separated by spaces:

$ tox -e py27,pep8

See tox.ini for the full list of available test environments.

Running functional tests

OpenStackClient also maintains a set of functional tests that are optimally designed to be run against OpenStack’s gate. Optionally, a developer may choose to run these tests against any OpenStack deployment, however depending on the services available, results will vary.

To run the entire suite of functional tests:

$ tox -e functional

To run a specific functional test:

$ tox -e functional -- --regex functional.tests.compute.v2.test_server

Running with PDB

Using PDB breakpoints with tox and testr normally doesn’t work since the tests fail with a BdbQuit exception rather than stopping at the breakpoint.

To run with PDB breakpoints during testing, use the debug tox environment rather than py27. Here’s an example, passing the name of a test since you’ll normally only want to run the test that hits your breakpoint:

$ tox -e debug opentackclient.tests.identity.v3.test_group

For reference, the debug tox environment implements the instructions here: https://wiki.openstack.org/wiki/Testr#Debugging_.28pdb.29_Tests

Building the Documentation

The documentation is generated with Sphinx using the tox command. To create HTML docs, run the following:

$ tox -e docs

The resultant HTML will be the doc/build/html directory.

Testing new code

If a developer wants to test new code (feature, command or option) that they have written, OpenStackClient may be installed from source by running the following commands in the base directory of the project:

$ python setup.py develop

or

$ pip install -e .