Eva Balycheva b53ff5d12c Refactoring of docs during Mitaka cycle

This patch improves Zaqar documentation and fixes currently existing
bugs.

Bugs this patch currently addresses and solutions:

Short names for documentation locations used in this commit message:
GitRepo - https://github.com/openstack/zaqar/
Contributor Docs - http://docs.openstack.org/developer/zaqar/
Wiki - https://wiki.openstack.org/wiki/Zaqar/

1. DRY violation and spreaded information for contributors bug.
The information for Zaqar contributors is spreaded/duplicated across
GitRepo, Contributor Docs and Wiki.
Examples of DRY violation are these three articles:
https://wiki.openstack.org/wiki/Zaqar/Give_Zaqar_a_try,
https://github.com/openstack/zaqar/blob/master/README.rst,
http://docs.openstack.org/developer/zaqar/development-environment.html

Example of spreaded information is: "zaqar/tests/functional/README.rst"
Normally the contributor want to see the information from this file in
"doc/source/running_tests.rst".

Solution: move useful missing information for contributors from Wiki and
GitRepo to Contributor Docs, then replace all contributor information in
Wiki and GitRepo with links to Contributor Docs.

2. Outdated information, missing new information and broken links bug.
Example is "test_suite.rst":
a. It still states that Zaqar test suite lives in two directories -
"tests" and "zaqar/tests", but now it's not true.
b. Doesn't contain information about how test invocation is organized,
what really happens when "tox -e py27" command executes.

Solution: replace outdated information with new, fix broken links if
possible, add useful missing information.

3. Style and formatting bugs.
The reference is http://docs.openstack.org/contributor-guide/.

Many documents in Contributor Docs have wrong line wrapping - some lines
are wrapped too short and some are wrapped too long.
Lines must wrap at 79 characters, exceptions are code and links.
Example is "first_review.rst" which lines are not wrapped at all.

Enumerated lists must be written using "#. " syntax.
Example with wrong enumerated list is "development.environment.rst".

Some inline elements must be styled according to:
http://docs.openstack.org/contributor-guide/rst-conv/inline-markups.html
Example with wrong styling of inline elements is
"development.environment.rst" where many paths and file names are not
marked with `` (double backticks).

By default code inserts are implicitly styled with python syntax.
There are many places in Contributor Docs where console (bash) code is
wrongly styled with python syntax.

Also there are some failed attempts to apply a formatting in Contributor
Docs. For example there is a broken list in "first_review.rst" at line
52.

Solution: fix broken formatting, apply proper style where it is needed.

Some of these bugs fixes closes few bug reports from:
https://etherpad.openstack.org/p/zaqar-mitaka-docs

Change-Id: Id668684248bdee03eb43b537dc2c6bb2a68ed23d

2016-01-07 17:05:09 +03:00

4.6 KiB

Raw Blame History

Running tests

Zaqar contains a suite of tests (both unit and functional) in the zaqar/tests directory.

See test_suite for details.

Any proposed code change is automatically rejected by the OpenStack Jenkins server¹ if the change causes test failures.

It is recommended for developers to run the test suite before submitting patch for review. This allows to catch errors as early as possible.

Preferred way to run the tests

The preferred way to run the unit tests is using tox. It executes tests in isolated environment, by creating separate virtualenv and installing dependencies from the requirements.txt and test-requirements.txt files, so the only package you install is tox itself:

$ pip install tox

See the unit testing section of the Testing wiki page for more information. Following are some simple examples.

To run the Python 2.7 tests:

$ tox -e py27

To run the style tests:

$ tox -e pep8

To run multiple tests separate items by commas:

$ tox -e py27,py34,pep8

Running a subset of tests

Instead of running all tests, you can specify an individual directory, file, class or method that contains test code, i.e. filter full names of tests by a string.

To run the tests located only in the zaqar/tests/unit/queues/storage directory use:

$ tox -e py27 zaqar.tests.unit.queues.storage

To run the tests specific to the MongoDB driver in the zaqar/tests/unit/queues/storage/test_impl_mongodb.py file:

$ tox -e py27 test_impl_mongodb

To run the tests in the MongodbMessageTests class in the tests/unit/queues/storage/test_impl_mongodb.py file:

$ tox -e py27 test_impl_mongodb.MongodbMessageTests

To run the MongodbMessageTests.test_message_lifecycle test method in the tests/unit/queues/storage/test_impl_mongodb.py file:

$ tox -e py27 test_impl_mongodb.MongodbMessageTests.test_message_lifecycle

Running functional tests

Zaqar's functional tests treat Zaqar as a black box. In other words, the API calls attempt to simulate an actual user. Unlike unit tests, the functional tests do not use mockendpoints.

Functional test modes

Functional tests can run in integration mode and non-integration mode.

Integration mode

In integration mode functional tests are performed on Zaqar server instances running as separate processes. This is real functional testing.

To run functional tests in integration mode, execute:

$ tox -e integration

Non-integration mode

In non-integration mode functional tests are performed on Zaqar server instances running as python objects. This mode doesn't guarantee enough black boxness for Zaqar, but tests run 10 times faster than in integration mode.

To run functional tests in non-integration mode, execute:

$ tox -e py27 zaqar.tests.functional

Using a custom MongoDB instance

If you need to run functional tests against a non-default MongoDB installation, you can set the ZAQAR_TEST_MONGODB_URL environment variable. For example:

$ export ZAQAR_TEST_MONGODB_URL=mongodb://remote-server:27017

Using custom parameters

You can edit default functional test configuration file zaqar/tests/etc/functional-tests.conf according to your needs.

For example, you want to run functional tests with keystone authentication enabled, input a valid set of credentials to [auth] section in configuration file and set auth_on parameter to True.

Footnotes

See http://docs.openstack.org/infra/system-config/jenkins.html ↩︎

4.6 KiB Raw Blame History