openstack/tempest
Code Issues Proposed changes

trivial: Fix typos in the documentation page

Browse Source 
This patchset fixes typos (capitalization mistakes,
grammar mistakes) found in the documentation pages.

Change-Id: If500aeab1af7dd8b56d63cbc481ee501216df161
This commit is contained in:
deepak_mourya 2018-07-16 12:38:17 +05:30 committed by Deepak Mourya
parent de5f0da10e
commit e495cd257d
5 changed files with 57 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
doc/source/configuration.rst
View File

@ -172,7 +172,7 @@ used in tests where two different-sized servers are required (for example, a
resize test). resize test).
Using a smaller flavor is generally recommended. When larger flavors are used, Using a smaller flavor is generally recommended. When larger flavors are used,
the extra time required to bring up servers will likely affect total run time the extra time required to bring up servers will likely affect the total run time
and probably require tweaking timeout values to ensure tests have ample time to and probably require tweaking timeout values to ensure tests have ample time to
finish. finish.
@ -207,7 +207,7 @@ uploaded.
The behavior of these options is a bit convoluted (which will likely be fixed in The behavior of these options is a bit convoluted (which will likely be fixed in
future versions). You first need to specify ``img_dir``, which is the directory future versions). You first need to specify ``img_dir``, which is the directory
in which Tempest will look for the image files. First it will check if the in which Tempest will look for the image files. First, it will check if the
filename set for ``img_file`` could be found in ``img_dir``. If it is found then filename set for ``img_file`` could be found in ``img_dir``. If it is found then
the ``img_container_format`` and ``img_disk_format`` options are used to upload the ``img_container_format`` and ``img_disk_format`` options are used to upload
that image to glance. However, if it is not found, Tempest will look for the that image to glance. However, if it is not found, Tempest will look for the
@ -239,7 +239,7 @@ Network Creation/Usage for Servers
"""""""""""""""""""""""""""""""""" """"""""""""""""""""""""""""""""""
When Tempest creates servers for testing, some tests require being able to When Tempest creates servers for testing, some tests require being able to
connect those servers. Depending on the configuration of the cloud, the methods connect those servers. Depending on the configuration of the cloud, the methods
for doing this can be different. In certain configurations it is required to for doing this can be different. In certain configurations, it is required to
specify a single network with server create calls. Accordingly, Tempest provides specify a single network with server create calls. Accordingly, Tempest provides
a few different methods for providing this information in configuration to try a few different methods for providing this information in configuration to try
and ensure that regardless of the cloud's configuration it'll still be able to and ensure that regardless of the cloud's configuration it'll still be able to
@ -297,10 +297,10 @@ With Dynamic Credentials
'''''''''''''''''''''''' ''''''''''''''''''''''''
With dynamic credentials enabled and using nova-network, your only option for With dynamic credentials enabled and using nova-network, your only option for
configuration is to either set a fixed network name or not. However, in most configuration is to either set a fixed network name or not. However, in most
cases it shouldn't matter because nova-network should have no problem booting a cases, it shouldn't matter because nova-network should have no problem booting a
server with multiple networks. If this is not the case for your cloud then using server with multiple networks. If this is not the case for your cloud then using
an accounts file is recommended because it provides the necessary flexibility to an accounts file is recommended because it provides the necessary flexibility to
describe your configuration. Dynamic credentials is not able to dynamically describe your configuration. Dynamic credentials are not able to dynamically
allocate things as necessary if Neutron is not enabled. allocate things as necessary if Neutron is not enabled.
With Neutron and dynamic credentials enabled there should not be any additional With Neutron and dynamic credentials enabled there should not be any additional
@ -352,7 +352,7 @@ Configuring Available Services
OpenStack is really a constellation of several different projects which OpenStack is really a constellation of several different projects which
are running together to create a cloud. However which projects you're running are running together to create a cloud. However which projects you're running
is not set in stone, and which services are running is up to the deployer. is not set in stone, and which services are running is up to the deployer.
Tempest however needs to know which services are available so it can figure Tempest, however, needs to know which services are available so it can figure
out which tests it is able to run and certain setup steps which differ based out which tests it is able to run and certain setup steps which differ based
on the available services. on the available services.
@ -390,8 +390,8 @@ changed.
.. note:: .. note::
Tempest does not serve all kinds of fancy URLs in the service catalog. The Tempest does not serve all kinds of fancy URLs in the service catalog.
service catalog should be in a standard format (which is going to be The service catalog should be in a standard format (which is going to be
standardized at the Keystone level). standardized at the Keystone level).
Tempest expects URLs in the Service catalog in the following format: Tempest expects URLs in the Service catalog in the following format:
@ -413,10 +413,10 @@ message queues, etc. However, the downside to this configurability is that
certain operations and features aren't supported depending on the configuration. certain operations and features aren't supported depending on the configuration.
These features may or may not be discoverable from the API so the burden is These features may or may not be discoverable from the API so the burden is
often on the user to figure out what is supported by the cloud they're talking often on the user to figure out what is supported by the cloud they're talking
to. Besides the obvious interoperability issues with this it also leaves to. Besides the obvious interoperability issues with this, it also leaves
Tempest in an interesting situation trying to figure out which tests are Tempest in an interesting situation trying to figure out which tests are
expected to work. However, Tempest tests do not rely on dynamic API discovery expected to work. However, Tempest tests do not rely on dynamic API discovery
for a feature (assuming one exists). Instead Tempest has to be explicitly for a feature (assuming one exists). Instead, Tempest has to be explicitly
configured as to which optional features are enabled. This is in order to configured as to which optional features are enabled. This is in order to
prevent bugs in the discovery mechanisms from masking failures. prevent bugs in the discovery mechanisms from masking failures.
@ -432,8 +432,8 @@ API Extensions
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
The service feature-enabled sections often contain an ``api-extensions`` option The service feature-enabled sections often contain an ``api-extensions`` option
(or in the case of Swift a ``discoverable_apis`` option). This is used to tell (or in the case of Swift a ``discoverable_apis`` option). This is used to tell
Tempest which api extensions (or configurable middleware) is used in your Tempest which API extensions (or configurable middleware) is used in your
deployment. It has two valid config states: either it contains a single value deployment. It has two valid config states: either it contains a single value
``all`` (which is the default) which means that every api extension is assumed ``all`` (which is the default) which means that every API extension is assumed
to be enabled, or it is set to a list of each individual extension that is to be enabled, or it is set to a list of each individual extension that is
enabled for that service. enabled for that service.

14
doc/source/library.rst
View File

@ -4,12 +4,12 @@ Tempest Library Documentation
============================= =============================
Tempest provides a stable library interface that provides external tools or Tempest provides a stable library interface that provides external tools or
test suites an interface for reusing pieces of tempest code. Any public test suites an interface for reusing pieces of Tempest code. Any public
interface that lives in tempest/lib in the tempest repo is treated as a stable interface that lives in tempest/lib in the Tempest repo is treated as a stable
public interface and it should be safe to external consume that. Every effort public interface and it should be safe to external consume that. Every effort
goes into maintaining backwards compatibility with any change. goes into maintaining backwards compatibility with any change.
The library is self contained and doesn't have any dependency on The library is self contained and doesn't have any dependency on
other tempest internals outside of lib (including no usage of tempest other Tempest internals outside of lib (including no usage of Tempest
configuration). configuration).
Stability Stability
@ -32,7 +32,7 @@ supporting.
Making changes Making changes
'''''''''''''' ''''''''''''''
When making changes to tempest/lib you have to be conscious of the effect of When making changes to tempest/lib you have to be conscious of the effect of
any changes on external consumers. If your proposed changeset will change the any changes on external consumers. If your proposed change set will change the
default behaviour of any interface, or make something which previously worked default behaviour of any interface, or make something which previously worked
not after your change, then it is not acceptable. Every effort needs to go into not after your change, then it is not acceptable. Every effort needs to go into
preserving backwards compatibility in changes. preserving backwards compatibility in changes.
@ -40,8 +40,8 @@ preserving backwards compatibility in changes.
Reviewing Reviewing
''''''''' '''''''''
When reviewing a proposed change to tempest/lib code we need to be careful to When reviewing a proposed change to tempest/lib code we need to be careful to
ensure that we don't break backwards compatibility. For patches that change ensure that we don't break backward compatibility. For patches that change
existing interfaces we have to be careful to make sure we don't break any existing interfaces, we have to be careful to make sure we don't break any
external consumers. Some common red flags are: external consumers. Some common red flags are:
* a change to an existing API requires a change outside the library directory * a change to an existing API requires a change outside the library directory
@ -52,7 +52,7 @@ Testing
''''''' '''''''
When adding a new interface to the library we need to at a minimum have unit When adding a new interface to the library we need to at a minimum have unit
test coverage. A proposed change to add an interface to tempest/lib that test coverage. A proposed change to add an interface to tempest/lib that
doesn't have unit tests shouldn't be accepted. Ideally these unit tests will doesn't have unit tests shouldn't be accepted. Ideally, these unit tests will
provide sufficient coverage to ensure a stable interface moving forward. provide sufficient coverage to ensure a stable interface moving forward.
Current Library APIs Current Library APIs

58
doc/source/plugin.rst
View File

@ -5,24 +5,24 @@ Tempest Test Plugin Interface
============================= =============================
Tempest has an external test plugin interface which enables anyone to integrate Tempest has an external test plugin interface which enables anyone to integrate
an external test suite as part of a tempest run. This will let any project an external test suite as part of a Tempest run. This will let any project
leverage being run with the rest of the tempest suite while not requiring the leverage being run with the rest of the Tempest suite while not requiring the
tests live in the tempest tree. tests live in the Tempest tree.
Creating a plugin Creating a plugin
================= =================
Creating a plugin is fairly straightforward and doesn't require much additional Creating a plugin is fairly straightforward and doesn't require much additional
effort on top of creating a test suite using tempest.lib. One thing to note with effort on top of creating a test suite using tempest.lib. One thing to note with
doing this is that the interfaces exposed by tempest are not considered stable doing this is that the interfaces exposed by Tempest are not considered stable
(with the exception of configuration variables which ever effort goes into (with the exception of configuration variables whichever effort goes into
ensuring backwards compatibility). You should not need to import anything from ensuring backward compatibility). You should not need to import anything from
tempest itself except where explicitly noted. Tempest itself except where explicitly noted.
Stable Tempest APIs plugins may use Stable Tempest APIs plugins may use
----------------------------------- -----------------------------------
As noted above, several tempest APIs are acceptable to use from plugins, while As noted above, several Tempest APIs are acceptable to use from plugins, while
others are not. A list of stable APIs available to plugins is provided below: others are not. A list of stable APIs available to plugins is provided below:
* tempest.lib.* * tempest.lib.*
@ -32,7 +32,7 @@ others are not. A list of stable APIs available to plugins is provided below:
* tempest.clients * tempest.clients
* tempest.test * tempest.test
If there is an interface from tempest that you need to rely on in your plugin If there is an interface from Tempest that you need to rely on in your plugin
which is not listed above, it likely needs to be migrated to tempest.lib. In which is not listed above, it likely needs to be migrated to tempest.lib. In
that situation, file a bug, push a migration patch, etc. to expedite providing that situation, file a bug, push a migration patch, etc. to expedite providing
the interface in a reliable manner. the interface in a reliable manner.
@ -62,7 +62,7 @@ Entry Point
----------- -----------
Once you've created your plugin class you need to add an entry point to your Once you've created your plugin class you need to add an entry point to your
project to enable tempest to find the plugin. The entry point must be added project to enable Tempest to find the plugin. The entry point must be added
to the "tempest.test_plugins" namespace. to the "tempest.test_plugins" namespace.
If you are using pbr this is fairly straightforward, in the setup.cfg just add If you are using pbr this is fairly straightforward, in the setup.cfg just add
@ -77,9 +77,9 @@ something like the following:
Standalone Plugin vs In-repo Plugin Standalone Plugin vs In-repo Plugin
----------------------------------- -----------------------------------
Since all that's required for a plugin to be detected by tempest is a valid Since all that's required for a plugin to be detected by Tempest is a valid
setuptools entry point in the proper namespace there is no difference from the setuptools entry point in the proper namespace there is no difference from the
tempest perspective on either creating a separate python package to Tempest perspective on either creating a separate python package to
house the plugin or adding the code to an existing python project. However, house the plugin or adding the code to an existing python project. However,
there are tradeoffs to consider when deciding which approach to take when there are tradeoffs to consider when deciding which approach to take when
creating a new plugin. creating a new plugin.
@ -91,9 +91,9 @@ the other project. It lets you version the plugin independently and maintain a
single version of the test code across project release boundaries (see the single version of the test code across project release boundaries (see the
`Branchless Tempest Spec`_ for more details on this). It also greatly `Branchless Tempest Spec`_ for more details on this). It also greatly
simplifies the install time story for external users. Instead of having to simplifies the install time story for external users. Instead of having to
install the right version of a project in the same python namespace as tempest install the right version of a project in the same python namespace as Tempest
they simply need to pip install the plugin in that namespace. It also means they simply need to pip install the plugin in that namespace. It also means
that users don't have to worry about inadvertently installing a tempest plugin that users don't have to worry about inadvertently installing a Tempest plugin
when they install another package. when they install another package.
.. _Branchless Tempest Spec: http://specs.openstack.org/openstack/qa-specs/specs/tempest/implemented/branchless-tempest.html .. _Branchless Tempest Spec: http://specs.openstack.org/openstack/qa-specs/specs/tempest/implemented/branchless-tempest.html
@ -108,9 +108,9 @@ single combined commit.
Plugin Class Plugin Class
============ ============
To provide tempest with all the required information it needs to be able to run To provide Tempest with all the required information it needs to be able to run
your plugin you need to create a plugin class which tempest will load and call your plugin you need to create a plugin class which Tempest will load and call
to get information when it needs. To simplify creating this tempest provides an to get information when it needs. To simplify creating this Tempest provides an
abstract class that should be used as the parent for your plugin. To use this abstract class that should be used as the parent for your plugin. To use this
you would do something like the following: you would do something like the following:
@ -147,7 +147,7 @@ create a directory structure with something like::
services/ services/
client.py client.py
That will mirror what people expect from tempest. The file That will mirror what people expect from Tempest. The file
* **config.py**: contains any plugin specific configuration variables * **config.py**: contains any plugin specific configuration variables
* **plugin.py**: contains the plugin class used for the entry point * **plugin.py**: contains the plugin class used for the entry point
@ -156,14 +156,14 @@ That will mirror what people expect from tempest. The file
* **services**: where the plugin specific service clients are * **services**: where the plugin specific service clients are
Additionally, when you're creating the plugin you likely want to follow all Additionally, when you're creating the plugin you likely want to follow all
of the tempest developer and reviewer documentation to ensure that the tests of the Tempest developer and reviewer documentation to ensure that the tests
being added in the plugin act and behave like the rest of tempest. being added in the plugin act and behave like the rest of Tempest.
Dealing with configuration options Dealing with configuration options
---------------------------------- ----------------------------------
Historically Tempest didn't provide external guarantees on its configuration Historically, Tempest didn't provide external guarantees on its configuration
options. However, with the introduction of the plugin interface this is no options. However, with the introduction of the plugin interface, this is no
longer the case. An external plugin can rely on using any configuration option longer the case. An external plugin can rely on using any configuration option
coming from Tempest, there will be at least a full deprecation cycle for any coming from Tempest, there will be at least a full deprecation cycle for any
option before it's removed. However, just the options provided by Tempest option before it's removed. However, just the options provided by Tempest
@ -171,7 +171,7 @@ may not be sufficient for the plugin. If you need to add any plugin specific
configuration options you should use the ``register_opts`` and configuration options you should use the ``register_opts`` and
``get_opt_lists`` methods to pass them to Tempest when the plugin is loaded. ``get_opt_lists`` methods to pass them to Tempest when the plugin is loaded.
When adding configuration options the ``register_opts`` method gets passed the When adding configuration options the ``register_opts`` method gets passed the
CONF object from tempest. This enables the plugin to add options to both CONF object from Tempest. This enables the plugin to add options to both
existing sections and also create new configuration sections for new options. existing sections and also create new configuration sections for new options.
Service Clients Service Clients
@ -325,23 +325,23 @@ Using Plugins
Tempest will automatically discover any installed plugins when it is run. So by Tempest will automatically discover any installed plugins when it is run. So by
just installing the python packages which contain your plugin you'll be using just installing the python packages which contain your plugin you'll be using
them with tempest, nothing else is really required. them with Tempest, nothing else is really required.
However, you should take care when installing plugins. By their very nature However, you should take care when installing plugins. By their very nature
there are no guarantees when running tempest with plugins enabled about the there are no guarantees when running Tempest with plugins enabled about the
quality of the plugin. Additionally, while there is no limitation on running quality of the plugin. Additionally, while there is no limitation on running
with multiple plugins it's worth noting that poorly written plugins might not with multiple plugins, it's worth noting that poorly written plugins might not
properly isolate their tests which could cause unexpected cross interactions properly isolate their tests which could cause unexpected cross interactions
between plugins. between plugins.
Notes for using plugins with virtualenvs Notes for using plugins with virtualenvs
---------------------------------------- ----------------------------------------
When using a tempest inside a virtualenv (like when running under tox) you have When using a Tempest inside a virtualenv (like when running under tox) you have
to ensure that the package that contains your plugin is either installed in the to ensure that the package that contains your plugin is either installed in the
venv too or that you have system site-packages enabled. The virtualenv will venv too or that you have system site-packages enabled. The virtualenv will
isolate the tempest install from the rest of your system so just installing the isolate the Tempest install from the rest of your system so just installing the
plugin package on your system and then running tempest inside a venv will not plugin package on your system and then running Tempest inside a venv will not
work. work.
Tempest also exposes a tox job, all-plugin, which will setup a tox virtualenv Tempest also exposes a tox job, all-plugin, which will setup a tox virtualenv

16
doc/source/test_removal.rst
View File

@ -91,7 +91,7 @@ you would run the following:
#. paste the output table with numbers and the mysql command you ran to #. paste the output table with numbers and the mysql command you ran to
generate it into the etherpad. generate it into the etherpad.
Eventually a CLI interface will be created to make that a bit more friendly. Eventually, a CLI interface will be created to make that a bit more friendly.
Also a dashboard is in the works so we don't need to manually run the command. Also a dashboard is in the works so we don't need to manually run the command.
The intent of the 2nd prong is to verify that moving the test into a project The intent of the 2nd prong is to verify that moving the test into a project
@ -102,7 +102,7 @@ testing isn't really being effective in catching that bug (and therefore
blocking it from landing) and having the testing run in Tempest still has blocking it from landing) and having the testing run in Tempest still has
value. value.
However for the 3rd prong verification is a bit more subjective. The original However, for the 3rd prong verification is a bit more subjective. The original
intent of this prong was mostly for refstack/defcore and also for things that intent of this prong was mostly for refstack/defcore and also for things that
running on the stable branches. We don't want to remove any tests if that running on the stable branches. We don't want to remove any tests if that
would break our API consistency checking between releases, or something that would break our API consistency checking between releases, or something that
@ -116,7 +116,7 @@ Discussing the 3rd prong
"""""""""""""""""""""""" """"""""""""""""""""""""
There are 2 approaches to addressing the 3rd prong. Either it can be raised There are 2 approaches to addressing the 3rd prong. Either it can be raised
during a qa meeting during the Tempest discussion. Please put it on the agenda during a QA meeting during the Tempest discussion. Please put it on the agenda
well ahead of the scheduled meeting. Since the meeting time will be well known well ahead of the scheduled meeting. Since the meeting time will be well known
ahead of time anyone who depends on the tests will have ample time beforehand ahead of time anyone who depends on the tests will have ample time beforehand
to outline any concerns on the before the meeting. To give ample time for to outline any concerns on the before the meeting. To give ample time for
@ -133,7 +133,7 @@ nature of ML.
Exceptions to this procedure Exceptions to this procedure
---------------------------- ----------------------------
For the most part all Tempest test removals have to go through this procedure For the most part, all Tempest test removals have to go through this procedure
there are a couple of exceptions though: there are a couple of exceptions though:
#. The class of testing has been decided to be outside the scope of Tempest. #. The class of testing has been decided to be outside the scope of Tempest.
@ -145,7 +145,7 @@ there are a couple of exceptions though:
Such tests cannot live in Tempest because of the branchless nature of Such tests cannot live in Tempest because of the branchless nature of
Tempest. Such tests must still honor `prong #3`_. Tempest. Such tests must still honor `prong #3`_.
For the first exception type the only types of testing in tree which have been For the first exception type, the only types of testing in the tree which have been
declared out of scope at this point are: declared out of scope at this point are:
* The CLI tests (which should be completely removed at this point) * The CLI tests (which should be completely removed at this point)
@ -154,7 +154,7 @@ declared out of scope at this point are:
* XML API Tests (which should be completely removed at this point) * XML API Tests (which should be completely removed at this point)
* EC2 API/boto tests (which should be completely removed at this point) * EC2 API/boto tests (which should be completely removed at this point)
For tests that fit into this category the only criteria for removal is that For tests that fit into this category, the only criteria for removal is that
there is equivalent testing elsewhere. there is equivalent testing elsewhere.
Tempest Scope Tempest Scope
@ -187,7 +187,7 @@ that API cannot live in Tempest anymore.
This is because tests would not be able to know or control which API response This is because tests would not be able to know or control which API response
to expect, and thus would not be able to enforce a specific behavior. to expect, and thus would not be able to enforce a specific behavior.
If a test exists in Tempest that would meet this criteria as consequence of a If a test exists in Tempest that would meet these criteria as a consequence of a
change, the test must be removed according to the procedure discussed into change, the test must be removed according to the procedure discussed in
this document. The API change should not be merged until all conditions this document. The API change should not be merged until all conditions
required for test removal can be met. required for test removal can be met.

2
doc/source/write_tests.rst
View File

@ -4,7 +4,7 @@ Tempest Test Writing Guide
########################## ##########################
This guide serves as a starting point for developers working on writing new This guide serves as a starting point for developers working on writing new
Tempest tests. At a high level tests in Tempest are just tests that conform to Tempest tests. At a high level, tests in Tempest are just tests that conform to
the standard python `unit test`_ framework. But there are several aspects of the standard python `unit test`_ framework. But there are several aspects of
that are unique to Tempest and its role as an integration test suite running that are unique to Tempest and its role as an integration test suite running
against a real cloud. against a real cloud.