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. ::
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. ::
[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
Here is an example for a two-node DevStack deployment:
.. code-block:: ini
[whitebox]
nodes_yaml = /opt/stack/whitebox-tempest-plugin/nodes.yaml
ctlplane_ssh_username = vagrant
ctlplane_ssh_private_key_path = /home/vagrant/.ssh/id_rsa
with a ``nodes.yaml`` file that looks something like:
.. code-block:: yaml
controller:
services:
libvirt:
start-command: 'systemctl start libvirtd'
stop_command: 'systemctl stop libvirtd'
nova-compute:
config_path: '/etc/nova/nova-cpu.conf'
start_command: 'systemctl start devstack@n-cpu'
stop_command: 'systemctl stop devstack@n-cpu'
compute1:
services:
libvirt:
start-command: 'systemctl start libvirtd'
stop_command: 'systemctl stop libvirtd'
nova-compute:
config_path: '/etc/nova/nova-cpu.conf'
start_command: 'systemctl start devstack@n-cpu'
stop_command: 'systemctl stop devstack@n-cpu'
where ``controller`` is the hostname of the controller node and
``compute1`` is the hostname of the second node running nova-compute.
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.
Raw data
{
"_id": null,
"home_page": "https://opendev.org/openstack/whitebox-tempest-plugin",
"name": "whitebox-tempest-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "OpenStack",
"author_email": "openstack-discuss@lists.openstack.org",
"download_url": "https://files.pythonhosted.org/packages/93/fb/db10387bc2aaaf91fb69a26c2e6f440477358338d1bcea0b8ba74cdd8230/whitebox_tempest_plugin-0.1.0.tar.gz",
"platform": null,
"description": "Whitebox Tempest plugin\n=======================\n\nThis is a Tempest plugin for whitebox testing. While Tempest's scope is limited\nto only the REST APIs, whitebox allows tests to peak behind the curtain,\nsimilar to how a cloud admin might. Examining things on the compute host(s)\nand/or the controller(s) is not only allowed, it's required for a test to be in\nwhitebox's scope. Whitebox tests must still be REST API-driven, however their\nassertions can involve things like the instance XML (if the Nova libvirt driver\nis in use) or the database.\n\n* Bugs: https://storyboard.openstack.org/#!/project/1162\n* IRC: #openstack-qa on OFTC\n\nRequirements\n------------\n\nWhile Tempest is cloud-agnostic because all clouds expose the same OpenStack\nAPIs (with some caveats around extensions), whitebox peaks behind the curtain,\nand thus is coupled to the way the cloud was deployed. Currently, devstack and\nTripleO (with undercloud and overcloud) are supported, with only devstack being\ntested in CI.\n\nSome tests have specific hardware requirements. These should be documented as\nconfig options, and tests are expected to skip if their hardware requirements\nare not declared in the configuration.\n\nInstall, configure and run\n--------------------------\n\n0. Tempest needs to be installed and configured.\n\n1. Install the plugin.\n\n This should be done from source. ::\n\n WORKSPACE=/some/directory\n cd $WORKSPACE\n git clone https://opendev.org/openstack/whitebox-tempest-plugin\n\n sudo pip install whitebox-tempest-plugin\n\n2. Configure Tempest.\n\n The exact configuration will depend on the deployment. There is no\n configuration reference yet, have a look at\n ``whitebox_tempest_plugin/config.py`` instead. As an example, here is a\n configuration for a multinode TripleO deployment. ::\n\n [whitebox]\n ctlplane_addresses = compute-0.localdomain:192.168.24.6,compute-1.localdomain:192.168.24.12\n ctlplane_ssh_username = heat-admin\n ctlplane_ssh_private_key_path = /home/stack/.ssh/id_rsa\n containers = true\n max_compute_nodes = 2 # Some tests depend on there being a single (available) compute node\n\n Here is an example for a two-node DevStack deployment:\n\n .. code-block:: ini\n\n [whitebox]\n nodes_yaml = /opt/stack/whitebox-tempest-plugin/nodes.yaml\n ctlplane_ssh_username = vagrant\n ctlplane_ssh_private_key_path = /home/vagrant/.ssh/id_rsa\n\n with a ``nodes.yaml`` file that looks something like:\n\n .. code-block:: yaml\n\n controller:\n services:\n libvirt:\n start-command: 'systemctl start libvirtd'\n stop_command: 'systemctl stop libvirtd'\n nova-compute:\n config_path: '/etc/nova/nova-cpu.conf'\n start_command: 'systemctl start devstack@n-cpu'\n stop_command: 'systemctl stop devstack@n-cpu'\n compute1:\n services:\n libvirt:\n start-command: 'systemctl start libvirtd'\n stop_command: 'systemctl stop libvirtd'\n nova-compute:\n config_path: '/etc/nova/nova-cpu.conf'\n start_command: 'systemctl start devstack@n-cpu'\n stop_command: 'systemctl stop devstack@n-cpu'\n\n where ``controller`` is the hostname of the controller node and\n ``compute1`` is the hostname of the second node running nova-compute.\n\n3. Execute the tests. ::\n\n tempest run --serial --regex whitebox_tempest_plugin.\n\n .. important::\n\n Whitebox expects its tests to run one at a time. Make sure to pass\n ``--serial`` or ``--concurrency 1`` to ``tempest run``.\n\n\nHow to add a new test\n---------------------\n\nTests should fit whitebox's scope. If a test intereacts with REST APIs and\nnothing else, it is better suited for Tempest itself. New tests should be added\nin their respective subdirectories. For example, tests that use the compute API\nlive in ``whitebox_tempest_plugin/api/compute``. Test code does not need unit\ntests, but helpers or utilities do. Unit tests live in\n``whitebox_tempest_plugin/tests``. Whitebox does not adhere to the `Tempest\nplugin interface <https://docs.openstack.org/tempest/latest/plugin.html>`. As\nmentioned, whitebox tests run one at a time, so it's safe for a test to modify\nthe environment and/or be destructive, as long as it cleans up after itself.\nFor example, changing Nova configuration values and/or restarting services is\nacceptable, as long as the original values and service state are restored.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Tempest plugin for whitebox testing. For testing things not exposed through the REST APIs.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://opendev.org/openstack/whitebox-tempest-plugin"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d0c971c65e0caac7638de7fa3b99ccd0e70e9215732aabdfa778a71ea86debc5",
"md5": "ca5ff4b85e67df01697353875da6f0e5",
"sha256": "1f058aad51f89af32515aa406788c1bf5735412df7349e20635644b3751296f3"
},
"downloads": -1,
"filename": "whitebox_tempest_plugin-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca5ff4b85e67df01697353875da6f0e5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 101278,
"upload_time": "2025-07-25T12:28:20",
"upload_time_iso_8601": "2025-07-25T12:28:20.376615Z",
"url": "https://files.pythonhosted.org/packages/d0/c9/71c65e0caac7638de7fa3b99ccd0e70e9215732aabdfa778a71ea86debc5/whitebox_tempest_plugin-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "93fbdb10387bc2aaaf91fb69a26c2e6f440477358338d1bcea0b8ba74cdd8230",
"md5": "3f3c8b6d8821fde36dc3b31d0c9fae49",
"sha256": "26ec528eae79f35877fea57f0d55a0b9b6ef8418a9f518aac7b8fe1e9525f59c"
},
"downloads": -1,
"filename": "whitebox_tempest_plugin-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "3f3c8b6d8821fde36dc3b31d0c9fae49",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 83251,
"upload_time": "2025-07-25T12:28:21",
"upload_time_iso_8601": "2025-07-25T12:28:21.370730Z",
"url": "https://files.pythonhosted.org/packages/93/fb/db10387bc2aaaf91fb69a26c2e6f440477358338d1bcea0b8ba74cdd8230/whitebox_tempest_plugin-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 12:28:21",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "whitebox-tempest-plugin"
}
JSON