oslotest

https://docs.openstack.org/oslotest/latest/
Admin
oslotest is an OpenStack testing framework and utilities library that provides base test cases, mock...
Tokens:6,956
Snippets:65
Trust Score:10
Update:3 hours ago
Show doc for...
Tokens:
Raw
### Install oslotest with pip

Source: https://docs.openstack.org/oslotest/latest/install/index.html

Run this command in your terminal to install the oslotest package. It is the standard installation method for Python packages.

```bash
$ pip install oslotest
```

--------------------------------

### Example class Foo

Source: https://docs.openstack.org/oslotest/latest/user/mock-autospec.html

A simple class with a method bar that takes parameters a, b, c, and optional d. Used as an example for autospec testing.

```python
class Foo(object):
    def bar(self, a, b, c, d=None):
        pass
```

--------------------------------

### Use MockAutospecFixture in setUp

Source: https://docs.openstack.org/oslotest/latest/user/mock-autospec.html

In the test setUp method, use self.useFixture(mock_fixture.MockAutospecFixture()) to replace mock.Mock and mock.MagicMock with subclasses that accept the autospec argument.

```python
nova/test.py
...
from oslotest import mock_fixture

class TestCase(testtools.TestCase):
    def setUp(self):
        super(TestCase, self).setUp()
        self.useFixture(mock_fixture.MockAutospecFixture())
```

--------------------------------

### Interactive pdb prompt output

Source: https://docs.openstack.org/oslotest/latest/user/features.html

Example output showing the interactive pdb prompt that appears when debugging with tox.

```text
> /opt/stack/ceilometer/ceilometer/tests/identity/test_notifications.py(106)notification_for_role_change()
-> action_name = '%s.%s' % (action, ROLE_ASSIGNMENT)
(Pdb)
```

--------------------------------

### BaseTestCase.addCleanup

Source: https://docs.openstack.org/oslotest/latest/reference/api/oslotest.base.html

Adds a cleanup function to be called after tearDown. Cleanup functions are called in reverse order of addition and are always executed before a test finishes, even if setUp raises an exception.

```APIDOC
## addCleanup(cleanup, *args, **kwargs)

### Description
Add a cleanup function to be called after tearDown. Functions added with addCleanup will be called in reverse order of adding after tearDown, or after setUp if setUp raises an exception. If a function added with addCleanup raises an exception, the error will be recorded as a test error, and the next cleanup will then be run. Cleanup functions are always called before a test finishes running, even if setUp is aborted by an exception.

### Method
addCleanup

### Parameters
- **cleanup** (Callable) - Required - The cleanup function to be called.
- **args** (object) - Optional - Positional arguments to pass to the cleanup function.
- **kwargs** (object) - Optional - Keyword arguments to pass to the cleanup function.

### Returns
None
```

--------------------------------

### Unit tests with autospec

Source: https://docs.openstack.org/oslotest/latest/user/mock-autospec.html

Using the setup described above, these unit tests will pass correctly. The first test uses mock.Mock(autospec=Foo) and expects TypeError when calling bar with invalid argument. The second uses @mock.patch.object(Foo, 'bar', autospec=True) and similarly expects TypeError.

```python
class FooTestCase(TestCase):
    def test_mock_bar(self):
        mock_foo = mock.Mock(autospec=Foo)
        self.assertRaises(TypeError, mock_foo.bar, invalid='argument')

    @mock.patch.object(Foo, 'bar', autospec=True)
    def test_patch_bar(self, mock_bar):
        foo = Foo()
        self.assertRaises(TypeError, foo.bar, invalid='argument')
```

--------------------------------

### class oslotest.timeout.Timeout

Source: https://docs.openstack.org/oslotest/latest/reference/api/oslotest.timeout.html

The Timeout class is a fixture that sets the maximum length of time for a test to run. It uses the OS_TEST_TIMEOUT environment variable to get the timeout value.

```APIDOC
## class oslotest.timeout.Timeout

### Description
Set the maximum length of time for the test to run. Uses OS_TEST_TIMEOUT to get the timeout.

### Constructor
`Timeout(default_timeout: int | float = 0, scaling_factor: int | float = 1)`

### Parameters
- **default_timeout** (int | float) - Optional - The default timeout value.
- **scaling_factor** (int | float) - Optional - The scaling factor for the timeout.

### Methods
- **setUp()** - Prepare the Fixture for use. This should not be overridden. Concrete fixtures should implement _setUp. Overriding of setUp is still supported, just not recommended. After setUp has completed, the fixture will have one or more attributes which can be used (these depend totally on the concrete subclass). Raises MultipleExceptions if _setUp fails. The last exception captured within the MultipleExceptions will be a SetupError exception. Returns None.
```

--------------------------------

### MockAutospecFixture.setUp()

Source: https://docs.openstack.org/oslotest/latest/reference/api/oslotest.mock_fixture.html

Prepares the fixture for use. This method should not be overridden; concrete fixtures should implement _setUp instead. It returns None and may raise MultipleExceptions if _setUp fails.

```APIDOC
## MockAutospecFixture.setUp()

### Description
Prepares the fixture for use. This method should not be overridden; concrete fixtures should implement _setUp instead. It returns None and may raise MultipleExceptions if _setUp fails.

### Method
setUp

### Signature
setUp() → None

### Parameters
None

### Returns
None

### Raises
- **MultipleExceptions** - If _setUp fails. The last exception captured within the MultipleExceptions will be a SetupError exception.

### Notes
- Changed in version 1.3: The recommendation to override setUp has been reversed - before 1.3, setUp() should be overridden, now it should not be.
- Changed in version 1.3.1: BaseException is now caught, and only subclasses of Exception are wrapped in MultipleExceptions.
```

--------------------------------

### BaseTestCase.setUp

Source: https://docs.openstack.org/oslotest/latest/reference/api/oslotest.base.html

Hook method for setting up the test fixture before exercising it. This is part of the unittest framework and is called before each test method.

```APIDOC
## setUp()

### Description
Hook method for setting up the test fixture before exercising it. This method is called before each test method to prepare the test environment.

### Method
setUp

### Parameters
None

### Returns
None
```

--------------------------------

### oslotest.createfile.CreateFileWithContent

Source: https://docs.openstack.org/oslotest/latest/genindex.html

Fixture to create a file with specified content.

```APIDOC
## CreateFileWithContent

### Description
Fixture to create a file with specified content.

### Module
oslotest.createfile

### Class
CreateFileWithContent
```

--------------------------------

### CreateFileWithContent

Source: https://docs.openstack.org/oslotest/latest/reference/api/oslotest.createfile.html

Creates a temporary file with the given content, using a predictable name for tests that need to interact with the real filesystem. The caller is responsible for ensuring the file is removed.

```APIDOC
## CreateFileWithContent

### Description
Creates a temporary file with the given content, using a predictable name for tests that need to interact with the real filesystem. The caller is responsible for ensuring the file is removed.

### Constructor
`CreateFileWithContent(filename: str, contents: str | bytes, ext: str = '.conf', encoding: str = 'utf-8')`

### Parameters
- **filename** (str) - Required - Base file name or full literal path to the file to be created.
- **contents** (str | bytes) - Required - The data to write to the file. Unicode data will be encoded before being written.
- **ext** (str) - Optional - An extension to add to filename. Default is '.conf'.
- **encoding** (str) - Optional - An encoding to use for unicode data (ignored for byte strings). Default is 'utf-8'.

### Attributes
- **path** (str) - The canonical name of the file created.

### Methods
#### setUp() -> None
Prepares the Fixture for use. This should not be overridden; concrete fixtures should implement _setUp. After setUp has completed, the fixture will have one or more attributes which can be used. Raises MultipleExceptions if _setUp fails. Returns None.

### Notes
- It is the responsibility of the caller to ensure that the file is removed.
- Users may also want to use `fixtures.NestedTempfile` to set the temporary directory somewhere safe and ensure files are cleaned up.

```

--------------------------------

### Run tests with oslo_debug_helper

Source: https://docs.openstack.org/oslotest/latest/user/debugging.html

Run the tests using oslo_debug_helper, either directly or through tox. Replace [tests to run] with the specific tests you want to debug.

```bash
$ oslo_debug_helper [tests to run]
```

```bash
$ tox -e venv -- oslo_debug_helper [tests to run]
```

--------------------------------

### get_config_parser()

Source: https://docs.openstack.org/oslotest/latest/reference/api/oslotest.tools.config.html

Returns a ConfigOpts instance for parsing configuration.

```APIDOC
## get_config_parser()

### Description
Returns a ConfigOpts instance for parsing configuration.

### Method
Function

### Signature
`get_config_parser() -> ConfigOpts`

### Returns
- **ConfigOpts** - A configuration options parser instance.
```

--------------------------------

### CreateFileWithContent.path

Source: https://docs.openstack.org/oslotest/latest/genindex.html

Attribute of the CreateFileWithContent class in oslotest.createfile. Represents the file path.

```APIDOC
## CreateFileWithContent.path

### Description
Attribute of the CreateFileWithContent class in oslotest.createfile. Represents the file path.

### Module
oslotest.createfile

### Type
attribute

```

--------------------------------

### oslotest.log.ConfigureLogging

Source: https://docs.openstack.org/oslotest/latest/genindex.html

Fixture to configure logging for tests.

```APIDOC
## ConfigureLogging

### Description
Fixture to configure logging for tests.

### Module
oslotest.log

### Class
ConfigureLogging
```

--------------------------------

### Configure debug environment with -t for package-level tests

Source: https://docs.openstack.org/oslotest/latest/user/features.html

Most oslo projects have tests at the package level, so use this configuration to point to the tests directory.

```ini
[testenv:debug]
commands = oslo_debug_helper -t tests {posargs}
```

--------------------------------

### Run oslotest tests with tox

Source: https://docs.openstack.org/oslotest/latest/user/testing.html

Use this command to run the test suite for oslotest in a Python 3 environment. It is the standard way to test any OpenStack project.

```bash
tox -e py3
```

--------------------------------

### Run tox with debug environment

Source: https://docs.openstack.org/oslotest/latest/user/features.html

Commands to run tox with the debug environment, optionally specifying a test or test case to debug.

```bash
$ tox -e debug
$ tox -e debug test_notifications
$ tox -e debug test_notifications.NotificationsTestCase
$ tox -e debug test_notifications.NotificationsTestCase.test_send_notification
```

--------------------------------

### parse_arguments(conf)

Source: https://docs.openstack.org/oslotest/latest/reference/api/oslotest.tools.config.html

Parses command-line arguments using the provided configuration object.

```APIDOC
## parse_arguments(conf)

### Description
Parses command-line arguments using the provided configuration object.

### Method
Function

### Signature
`parse_arguments(conf: type[_ConfigOptT]) -> _ConfigOptT`

### Parameters
- **conf** (type[_ConfigOptT]) - Required - The configuration object to parse arguments into.

### Returns
- **_ConfigOptT** - The configuration object with parsed arguments.
```

--------------------------------

### Configure debug environment in tox.ini

Source: https://docs.openstack.org/oslotest/latest/user/features.html

Add this to your project's tox.ini to define a debug environment that runs oslo_debug_helper with positional arguments.

```ini
[testenv:debug]
commands = oslo_debug_helper {posargs}
```

--------------------------------

### parse_arguments()

Source: https://docs.openstack.org/oslotest/latest/genindex.html

Function in module oslotest.tools.config. Parses command-line arguments for configuration.

```APIDOC
## parse_arguments()

### Description
Parses command-line arguments for configuration.

### Module
oslotest.tools.config

### Signature
parse_arguments()

```

--------------------------------

### Configure debug environment with -t for custom tests directory

Source: https://docs.openstack.org/oslotest/latest/user/features.html

Use this when the project name and the module preceding the tests directory do not match. The -t argument specifies the directory where tests are located.

```ini
[testenv:debug]
commands = oslo_debug_helper -t keystoneclient/tests {posargs}
```

--------------------------------

### oslotest.mock_fixture.Base

Source: https://docs.openstack.org/oslotest/latest/genindex.html

Base class for mock fixtures in oslotest.mock_fixture module.

```APIDOC
## Base

### Description
Base class for mock fixtures in oslotest.mock_fixture module.

### Module
oslotest.mock_fixture

### Class
Base
```

--------------------------------

### oslotest.base.BaseTestCase.create_tempfiles

Source: https://docs.openstack.org/oslotest/latest/genindex.html

Creates temporary files for use in tests. This method is part of the BaseTestCase class in the oslotest.base module.

```APIDOC
## create_tempfiles()

### Description
Creates temporary files for use in tests.

### Method
create_tempfiles

### Module
oslotest.base

### Class
BaseTestCase

### Parameters
- **files** (list) - Required - A list of tuples (name, content) or (name, content, encoding).
- **map** (dict) - Optional - A mapping of file names to content.

### Returns
List of paths to the created temporary files.
```

--------------------------------

### CaptureOutput

Source: https://docs.openstack.org/oslotest/latest/reference/api/oslotest.output.html

A fixture that optionally captures the output streams (stdout and stderr). Behavior is controlled via constructor arguments or environment variables OS_STDOUT_CAPTURE and OS_STDERR_CAPTURE.

```APIDOC
## CaptureOutput

### Description
A fixture that optionally captures the output streams (stdout and stderr). Behavior is controlled via constructor arguments or environment variables OS_STDOUT_CAPTURE and OS_STDERR_CAPTURE.

### Constructor
`CaptureOutput(do_stdout: bool | None = None, do_stderr: bool | None = None)`

### Parameters
- **do_stdout** (bool) - Optional - Whether to capture stdout.
- **do_stderr** (bool) - Optional - Whether to capture stderr.

### Attributes
- **stdout** - The `stream` attribute from a `StringStream` instance replacing stdout.
- **stderr** - The `stream` attribute from a `StringStream` instance replacing stderr.

### Methods
#### setUp() -> None

##### Description
Prepare the Fixture for use. This should not be overridden. Concrete fixtures should implement _setUp. Overriding of setUp is still supported, just not recommended.

##### Returns
None.

##### Raises
MultipleExceptions if _setUp fails. The last exception captured within the MultipleExceptions will be a SetupError exception.

##### Notes
Changed in 1.3: The recommendation to override setUp has been reversed - before 1.3, setUp() should be overridden, now it should not be.
Changed in 1.3.1: BaseException is now caught, and only subclasses of Exception are wrapped in MultipleExceptions.
```

--------------------------------

### oslotest.output.CaptureOutput

Source: https://docs.openstack.org/oslotest/latest/genindex.html

Fixture to capture stdout and stderr output during tests.

```APIDOC
## CaptureOutput

### Description
Fixture to capture stdout and stderr output during tests.

### Module
oslotest.output

### Class
CaptureOutput
```

--------------------------------

### Add pdb breakpoint in test code

Source: https://docs.openstack.org/oslotest/latest/user/debugging.html

Insert this line in the test code to set a breakpoint for debugging. This is the first step before running tests with oslo_debug_helper.

```python
import pdb; pdb.set_trace()
```

--------------------------------

### oslotest.base.BaseTestCase

Source: https://docs.openstack.org/oslotest/latest/genindex.html

Base test case class for oslotest. Provides common functionality for test cases.

```APIDOC
## BaseTestCase

### Description
Base test case class for oslotest. Provides common functionality for test cases.

### Module
oslotest.base

### Class
BaseTestCase
```

--------------------------------

### patch_mock_module()

Source: https://docs.openstack.org/oslotest/latest/genindex.html

Function in module oslotest.mock_fixture. Patches the mock module for testing fixtures.

```APIDOC
## patch_mock_module()

### Description
Patches the mock module for testing fixtures.

### Module
oslotest.mock_fixture

### Signature
patch_mock_module()

```

--------------------------------

### patch_mock_module()

Source: https://docs.openstack.org/oslotest/latest/reference/api/oslotest.mock_fixture.html

Replaces the mock.patch class in the mock module. This function is used to apply the autospec enhancements provided by the fixture.

```APIDOC
## patch_mock_module()

### Description
Replaces the mock.patch class in the mock module. This function is used to apply the autospec enhancements provided by the fixture.

### Method
patch_mock_module

### Signature
patch_mock_module() → None

### Parameters
None

### Returns
None
```

--------------------------------

### oslotest.base.BaseTestCase.addCleanup

Source: https://docs.openstack.org/oslotest/latest/genindex.html

Registers a cleanup function to be called after the test case finishes. This method is part of the BaseTestCase class in the oslotest.base module.

```APIDOC
## addCleanup()

### Description
Registers a cleanup function to be called after the test case finishes.

### Method
addCleanup

### Module
oslotest.base

### Class
BaseTestCase

### Parameters
- **function** (callable) - Required - The cleanup function to call.
- **\*args** - Optional - Arguments to pass to the cleanup function.
- **\*\*kwargs** - Optional - Keyword arguments to pass to the cleanup function.

### Returns
None
```

--------------------------------

### Patch mock module in test module

Source: https://docs.openstack.org/oslotest/latest/user/mock-autospec.html

Call mock_fixture.patch_mock_module() as early as possible in the test module or base test module to fix autospec handling of self/cls arguments. This function also sets autospec to True unless new_callable, create, or spec are passed.

```python
nova/test.py
...
from oslotest import mock_fixture

mock_fixture.patch_mock_module()
```
Tokens:
Raw