82c307a034
This change adds the publish-to-pypi job template for the whitebox-tempest-plugin. This change also correct the syntax error in the README.rst preventign the twine check command form passing. this will enable releases to be done via commits to the release repo via pypi https://pypi.org/project/whitebox-tempest-plugin/ a side effect of this process is the creation of git tags and release tarballs for each tagged release. Change-Id: I5cf0e3072c0502320866de1ce9771d61f1e0ec1b
84 lines
3.2 KiB
ReStructuredText
84 lines
3.2 KiB
ReStructuredText
Whitebox Tempest plugin
|
|
=======================
|
|
|
|
This is a Tempest plugin for whitebox testing. While Tempest's scope is limited
|
|
to only the REST APIs, whitebox allows tests to peak behind the curtain,
|
|
similar to how a cloud admin might. Examining things on the compute host(s)
|
|
and/or the controller(s) is not only allowed, it's required for a test to be in
|
|
whitebox's scope. Whitebox tests must still be REST API-driven, however their
|
|
assertions can involve things like the instance XML (if the Nova libvirt driver
|
|
is in use) or the database.
|
|
|
|
* Bugs: https://storyboard.openstack.org/#!/project/1162
|
|
* IRC: #openstack-qa on OFTC
|
|
|
|
Requirements
|
|
------------
|
|
|
|
While Tempest is cloud-agnostic because all clouds expose the same OpenStack
|
|
APIs (with some caveats around extensions), whitebox peaks behind the curtain,
|
|
and thus is coupled to the way the cloud was deployed. Currently, devstack and
|
|
TripleO (with undercloud and overcloud) are supported, with only devstack being
|
|
tested in CI.
|
|
|
|
Some tests have specific hardware requirements. These should be documented as
|
|
config options, and tests are expected to skip if their hardware requirements
|
|
are not declared in the configuration.
|
|
|
|
Install, configure and run
|
|
--------------------------
|
|
|
|
0. Tempest needs to be installed and configured.
|
|
|
|
1. Install the plugin.
|
|
|
|
This should be done from source. ::
|
|
|
|
.. code-block:: shell
|
|
|
|
WORKSPACE=/some/directory
|
|
cd $WORKSPACE
|
|
git clone https://opendev.org/openstack/whitebox-tempest-plugin
|
|
sudo pip install whitebox-tempest-plugin
|
|
|
|
2. Configure Tempest.
|
|
|
|
The exact configuration will depend on the deployment. There is no
|
|
configuration reference yet, have a look at
|
|
``whitebox_tempest_plugin/config.py`` instead. As an example, here is a
|
|
configuration for a multinode TripleO deployment::
|
|
|
|
.. code-block:: ini
|
|
|
|
[whitebox]
|
|
ctlplane_addresses = compute-0.localdomain:192.168.24.6,compute-1.localdomain:192.168.24.12
|
|
ctlplane_ssh_username = heat-admin
|
|
ctlplane_ssh_private_key_path = /home/stack/.ssh/id_rsa
|
|
containers = true
|
|
max_compute_nodes = 2 # Some tests depend on there being a single (available) compute node
|
|
|
|
3. Execute the tests. ::
|
|
|
|
tempest run --serial --regex whitebox_tempest_plugin.
|
|
|
|
.. important::
|
|
|
|
Whitebox expects its tests to run one at a time. Make sure to pass
|
|
``--serial`` or ``--concurrency 1`` to ``tempest run``.
|
|
|
|
|
|
How to add a new test
|
|
---------------------
|
|
|
|
Tests should fit whitebox's scope. If a test intereacts with REST APIs and
|
|
nothing else, it is better suited for Tempest itself. New tests should be added
|
|
in their respective subdirectories. For example, tests that use the compute API
|
|
live in ``whitebox_tempest_plugin/api/compute``. Test code does not need unit
|
|
tests, but helpers or utilities do. Unit tests live in
|
|
``whitebox_tempest_plugin/tests``. Whitebox does not adhere to the `Tempest
|
|
plugin interface <https://docs.openstack.org/tempest/latest/plugin.html>`. As
|
|
mentioned, whitebox tests run one at a time, so it's safe for a test to modify
|
|
the environment and/or be destructive, as long as it cleans up after itself.
|
|
For example, changing Nova configuration values and/or restarting services is
|
|
acceptable, as long as the original values and service state are restored.
|