diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index d0d73209bd..2e5f7067b0 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -172,7 +172,7 @@ used in tests where two different-sized servers are required (for example, a resize test). 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 finish. @@ -207,7 +207,7 @@ uploaded. 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 -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 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 @@ -239,7 +239,7 @@ Network Creation/Usage for Servers """""""""""""""""""""""""""""""""" When Tempest creates servers for testing, some tests require being able to 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 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 @@ -297,10 +297,10 @@ With Dynamic Credentials '''''''''''''''''''''''' 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 -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 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. 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 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. -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 on the available services. @@ -390,8 +390,8 @@ changed. .. note:: - Tempest does not serve all kinds of fancy URLs in the service catalog. The - service catalog should be in a standard format (which is going to be + Tempest does not serve all kinds of fancy URLs in the service catalog. + The service catalog should be in a standard format (which is going to be standardized at the Keystone level). 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. 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 -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 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 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 (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 -``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 enabled for that service. diff --git a/doc/source/library.rst b/doc/source/library.rst index 14415ae44a..6a12c4513f 100644 --- a/doc/source/library.rst +++ b/doc/source/library.rst @@ -4,12 +4,12 @@ Tempest Library Documentation ============================= Tempest provides a stable library interface that provides external tools or -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 +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 public interface and it should be safe to external consume that. Every effort goes into maintaining backwards compatibility with any change. 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). Stability @@ -32,7 +32,7 @@ supporting. Making changes '''''''''''''' 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 not after your change, then it is not acceptable. Every effort needs to go into preserving backwards compatibility in changes. @@ -40,8 +40,8 @@ preserving backwards compatibility in changes. Reviewing ''''''''' 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 -existing interfaces we have to be careful to make sure we don't break any +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 external consumers. Some common red flags are: * 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 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. Current Library APIs diff --git a/doc/source/plugin.rst b/doc/source/plugin.rst index 6f6621d023..9958792445 100644 --- a/doc/source/plugin.rst +++ b/doc/source/plugin.rst @@ -5,24 +5,24 @@ Tempest Test Plugin Interface ============================= 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 -leverage being run with the rest of the tempest suite while not requiring the -tests live in the tempest tree. +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 +tests live in the Tempest tree. Creating a plugin ================= 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 -doing this is that the interfaces exposed by tempest are not considered stable -(with the exception of configuration variables which ever effort goes into -ensuring backwards compatibility). You should not need to import anything from -tempest itself except where explicitly noted. +doing this is that the interfaces exposed by Tempest are not considered stable +(with the exception of configuration variables whichever effort goes into +ensuring backward compatibility). You should not need to import anything from +Tempest itself except where explicitly noted. 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: * tempest.lib.* @@ -32,7 +32,7 @@ others are not. A list of stable APIs available to plugins is provided below: * tempest.clients * 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 that situation, file a bug, push a migration patch, etc. to expedite providing 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 -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. 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 ----------------------------------- -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 -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, there are tradeoffs to consider when deciding which approach to take when 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 `Branchless Tempest Spec`_ for more details on this). It also greatly 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 -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. .. _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 ============ -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 -to get information when it needs. To simplify creating this tempest provides an +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 +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 you would do something like the following: @@ -147,7 +147,7 @@ create a directory structure with something like:: services/ 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 * **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 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 -being added in the plugin act and behave like the rest of tempest. +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. Dealing with configuration options ---------------------------------- -Historically Tempest didn't provide external guarantees on its configuration -options. However, with the introduction of the plugin interface this is no +Historically, Tempest didn't provide external guarantees on its configuration +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 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 @@ -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 ``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 -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. Service Clients @@ -325,23 +325,23 @@ Using Plugins 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 -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 -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 -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 between plugins. 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 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 -plugin package on your system and then running tempest inside a venv will not +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 work. Tempest also exposes a tox job, all-plugin, which will setup a tox virtualenv diff --git a/doc/source/test_removal.rst b/doc/source/test_removal.rst index b22503b7ad..786a203aa3 100644 --- a/doc/source/test_removal.rst +++ b/doc/source/test_removal.rst @@ -91,7 +91,7 @@ you would run the following: #. paste the output table with numbers and the mysql command you ran to 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. 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 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 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 @@ -116,7 +116,7 @@ Discussing the 3rd prong """""""""""""""""""""""" 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 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 @@ -133,7 +133,7 @@ nature of ML. 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: #. 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 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: * 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) * 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. 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 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 -change, the test must be removed according to the procedure discussed into +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 in this document. The API change should not be merged until all conditions required for test removal can be met. diff --git a/doc/source/write_tests.rst b/doc/source/write_tests.rst index fff2405ee8..0a29b7b3b8 100644 --- a/doc/source/write_tests.rst +++ b/doc/source/write_tests.rst @@ -4,7 +4,7 @@ Tempest Test Writing Guide ########################## 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 that are unique to Tempest and its role as an integration test suite running against a real cloud.