pti: Misc fixes
Add some links, fix some formatting, and generally tidy things up here. Change-Id: I6d4326f6c8e38fa7f57b479cba8c455759da24dd Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
This commit is contained in:
Stephen Finucane
@@ -6,7 +6,7 @@ Project Testing Interface: Python
|
||||
|
||||
Each project containing Python components must be able to do:
|
||||
|
||||
- Unit tests for python (see below for version details)
|
||||
- Unit tests for Python (see below for version details)
|
||||
- Codestyle checks
|
||||
- Testing Coverage Report
|
||||
- Source Tarball Generation
|
||||
@@ -47,8 +47,8 @@ Projects that are translated should also support generating and updating their
|
||||
|
||||
Some basic prerequisites for test running (system packages, database
|
||||
configuration, custom filesystem types) are acceptable as long as they are
|
||||
documented in a visible location such as a CONTRIBUTING, TESTING, or README
|
||||
file in the root of the repository.
|
||||
documented in a visible location such as a ``CONTRIBUTING.rst``,
|
||||
``TESTING.rst``, or ``README.rst`` file in the root of the repository.
|
||||
|
||||
Requirements Listing
|
||||
--------------------
|
||||
@@ -73,52 +73,66 @@ ease the diagnosis of breakage caused by projects upstream to OpenStack and
|
||||
to provide a set of packages known to work together.
|
||||
|
||||
Projects may opt into using the constraints in one or more of their
|
||||
standard targets via their tox.ini configuration.
|
||||
standard targets via their ``tox.ini`` configuration.
|
||||
|
||||
Virtual Environment Management
|
||||
------------------------------
|
||||
|
||||
To support sensible testing across multiple python versions, we use tox
|
||||
To support sensible testing across multiple Python versions, we use tox
|
||||
config files in the projects.
|
||||
|
||||
Python test running
|
||||
-------------------
|
||||
|
||||
OpenStack uses stestr as its test runner. stestr should be used for running
|
||||
all python tests, this includes unit tests, functional tests, and integration
|
||||
tests. stestr is used because of its real time subunit output and its support
|
||||
for parallel execution of tests. In addition, stestr only runs tests conforming
|
||||
to the python stdlib unittest model (and extensions on it like testtools). This
|
||||
enables people to use any test runner they prefer locally. Other popular test
|
||||
runners often include a testing ecosystem which is tied directly to the runner.
|
||||
Using these precludes the use of alternative runners for other users.
|
||||
OpenStack uses `stestr`__ as its test runner. *stestr* should be used for
|
||||
running all Python tests, including unit, functional, and integration tests.
|
||||
*stestr* is used because of its real time subunit output and its support for
|
||||
parallel execution of tests. In addition, *stestr* only runs tests conforming
|
||||
to the Python stdlib unittest model (and extensions on it like `testtools`__).
|
||||
This enables people to use any test runner they prefer locally. Other popular
|
||||
test runners often include a testing ecosystem which is tied directly to the
|
||||
runner. Using these precludes the use of alternative runners for other users.
|
||||
|
||||
To have a consistent interface via tox between projects' unit test
|
||||
jobs the command for running stestr in tox should be set to::
|
||||
jobs the command for running *stestr* in tox should be set like so:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[testenv]
|
||||
commands =
|
||||
stestr run {posargs}
|
||||
|
||||
.. note::
|
||||
|
||||
While the use of wrapper scripts can sometimes be useful as a short term
|
||||
crutch to work around a specific temporary issues, it should be avoided
|
||||
because it creates a divergent experience between projects, and can mask
|
||||
real issues.
|
||||
|
||||
If there are additional mandatory args needed for running a test suite they
|
||||
can be added before the posargs. (this way the end user experience is the same)
|
||||
For example::
|
||||
If there are additional mandatory arguments needed for running a test suite
|
||||
they can be added before the positional arguments, ensuring the end user
|
||||
experience remains the same. For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
[testenv]
|
||||
commands =
|
||||
stestr --test-path ./tests/unit run {posargs}
|
||||
|
||||
However, these arguments should try to be minimized because it just adds to the
|
||||
complexity that people will need to understand when running tests on a project.
|
||||
|
||||
.. __: https://stestr.readthedocs.io/
|
||||
.. __: https://testtools.readthedocs.io/
|
||||
|
||||
Coverage Jobs
|
||||
-------------
|
||||
|
||||
For coverage jobs you need to invoke the test runner in the same way as for the
|
||||
normal unit test jobs, but to switch the python executable to be
|
||||
``coverage run``. To do this you need to setup the tox ``cover`` job like::
|
||||
normal unit test jobs, but to switch the Python executable to be
|
||||
``coverage run``. To do this you need to setup the tox ``cover`` job like:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[testenv:cover]
|
||||
setenv =
|
||||
@@ -137,7 +151,7 @@ Project Configuration
|
||||
|
||||
All OpenStack projects use `pbr`__ for consistent operation of setuptools.
|
||||
To accomplish this, all ``setup.py`` files only contain a simple setup function
|
||||
that enabled pbr. Actual project configuration is then handled in
|
||||
that enabled *pbr*. Actual project configuration is then handled in
|
||||
``pyproject.toml`` or ``setup.cfg``.
|
||||
|
||||
.. __: https://docs.openstack.org/pbr/latest/
|
||||
@@ -145,20 +159,20 @@ that enabled pbr. Actual project configuration is then handled in
|
||||
Generated Files
|
||||
---------------
|
||||
|
||||
ChangeLog and AUTHORS files are generated at setup.py sdist time. This is
|
||||
handled by pbr.
|
||||
``ChangeLog`` and ``AUTHORS`` files are generated at setup.py sdist time. This
|
||||
is handled by pbr.
|
||||
|
||||
.mailmap files should exist where a developer has more than one email address
|
||||
or identity, and should map to the developer's canonical identity.
|
||||
``.mailmap`` files should exist where a developer has more than one email
|
||||
address or identity, and should map to the developer's canonical identity.
|
||||
|
||||
Translations
|
||||
------------
|
||||
|
||||
To support translations processing, projects should have a valid babel config.
|
||||
There should be a locale package inside of the top project module, and in that
|
||||
dir should be the $project.pot file. For instance, for nova, there should be
|
||||
nova/locale/nova.pot. Babel commands should be configured out output their .mo
|
||||
files in to $project/locale as well.
|
||||
There should be a ``locale`` package inside of the top project module, and in that
|
||||
directory should be the ``$project.pot`` file. For instance, the ``.pot`` file
|
||||
for nova should be found at ``nova/locale/nova.pot``. Babel commands should be
|
||||
configured out output their ``.mo`` files in to ``$project/locale`` as well.
|
||||
|
||||
Release Notes
|
||||
-------------
|
||||
@@ -174,4 +188,4 @@ a ``releasenotes`` environment for tox that will run
|
||||
The project infrastructure will not use ``tox -e releasenotes`` to build the
|
||||
documentation. Therefore it is **STRONGLY** discouraged for people to put
|
||||
additional logic into the command section of that tox environment. Additional
|
||||
logic needed around releasenotes generation should go into reno.
|
||||
logic needed around release notes generation should go into *reno*.
|
||||
|
||||
Reference in New Issue
Block a user