Tempest Test Writing Guide¶

Allocating Credentials¶

Since Tempest tests are all about testing a running cloud, every test will need credentials to be able to make API requests against the cloud. Since this is critical to operation and, when running in parallel, easy to make a mistake, the base TestCase class will automatically allocate a regular user for each TestCase during the setup_credentials() phase. During this process it will also initialize a client manager object using those credentials, which will be your entry point into interacting with the cloud. For more details on how credentials are allocated the Test Credentials section of the Tempest Configuration Guide provides more details on the operation of this.

There are some cases when you need more than a single set of credentials, or credentials with a more specialized set of roles. To accomplish this you have to set a class variable credentials on the TestCase directly. For example:

from tempest import test

class TestExampleAdmin(test.BaseTestCase):

    credentials = ['primary', 'admin']

@classmethod
def skip_checks(cls):
...

In this example the TestExampleAdmin TestCase will allocate 2 sets of credentials, one regular user and one admin user. The corresponding manager objects will be set as class variables cls.os_primary and cls.os_admin respectively. You can also allocate a second user by putting 'alt' in the list too. A set of alt credentials are the same as primary but can be used for tests cases that need a second user/project.

You can also specify credentials with specific roles assigned. This is useful for cases where there are specific RBAC requirements hard coded into an API. The canonical example of this are swift tests which often want to test swift's concepts of operator and reseller_admin. An actual example from tempest on how to do this is:

class PublicObjectTest(base.BaseObjectTest):

    credentials = [['operator', CONF.object_storage.operator_role],
                   ['operator_alt', CONF.object_storage.operator_role]]

    @classmethod
    def setup_credentials(cls):
        super(PublicObjectTest, cls).setup_credentials()
        ...

In this case the manager objects will be set to cls.os_roles_operator and cls.os_roles_operator_alt respectively.

There is no limit to how many credentials you can allocate in this manner, however in almost every case you should not need more than 3 sets of credentials per test case.

To figure out the mapping of manager objects set on the TestCase and the requested credentials you can reference:

By default cls.os_primary is available since it is allocated in the base tempest test class (located in tempest/test.py). If your TestCase inherits from a different direct parent class (it'll still inherit from the BaseTestCase, just not directly) be sure to check if that class overrides allocated credentials.

Dealing with Network Allocation¶

When neutron is enabled and a testing requires networking this isn't normally automatically setup when a tenant is created. Since tempest needs isolated tenants to function properly it also needs to handle network allocation. By default the base test class will allocate a network, subnet, and router automatically (this depends on the configured credential provider, for more details see: Network Creation/Usage for Servers). However, there are situations where you do no need all of these resources allocated (or your TestCase inherits from a class that overrides the default in tempest/test.py). There is a class level mechanism to override this allocation and specify which resources you need. To do this you need to call cls.set_network_resources() in the setup_credentials() method before the super(). For example:

from tempest import test


class TestExampleCase(test.BaseTestCase):

@classmethod
def setup_credentials(cls):
    cls.set_network_resources(network=True, subnet=True, router=False)
    super(TestExampleCase, cls).setup_credentials()

There are 2 quirks with the usage here. First for the set_network_resources function to work properly it must be called before super(). This is so that children classes' settings are always used instead of a parent classes'. The other quirk here is that if you do not want to allocate any network resources for your test class simply call set_network_resources() without any arguments. For example:

from tempest import test


class TestExampleCase(test.BaseTestCase):

@classmethod
def setup_credentials(cls):
    cls.set_network_resources()
    super(TestExampleCase, cls).setup_credentials()

This will not allocate any networking resources. This is because by default all the arguments default to False.

It's also worth pointing out that it is common for base test classes for different services (and scenario tests) to override this setting. When inheriting from classes other than the base TestCase in tempest/test.py it is worth checking the immediate parent for what is set to determine if your class needs to override that setting.