Fixture¶
Fixtures for writing tests for code using oslo.versionedobjects
Note
This module has several extra dependencies not needed at runtime
for production code, and therefore not installed by default. To
ensure those dependencies are present for your tests, add
oslo.versionedobjects[fixtures]
to your list of test dependencies.
- oslo_versionedobjects.fixture.CompatArgSpec¶
alias of
oslo_versionedobjects.fixture.ArgSpec
- class oslo_versionedobjects.fixture.FakeIndirectionAPI(serializer=None)¶
- object_action(context, objinst, objmethod, args, kwargs)¶
Perform an action on a VersionedObject instance.
When indirection_api is set on a VersionedObject (to a class implementing this interface), method calls on remotable methods will cause this to be executed to actually make the desired call. This often involves performing RPC.
- Parameters
context – The context within which to perform the action
objinst – The object instance on which to perform the action
objmethod – The name of the action method to call
args – The positional arguments to the action method
kwargs – The keyword arguments to the action method
- Returns
The result of the action method
- object_backport(context, objinst, target_version)¶
Deprecated since version 0.10.0.
Use
object_backport_versions()
instead.Perform a backport of an object instance to a specified version.
When indirection_api is set on a VersionedObject (to a class implementing this interface), the default behavior of the base VersionedObjectSerializer, upon receiving an object with a version newer than what is in the lcoal registry, is to call this method to request a backport of the object. In an environment where there is an RPC-able service on the bus which can gracefully downgrade newer objects for older services, this method services as a translation mechanism for older code when receiving objects from newer code.
NOTE: This older/original method is soon to be deprecated. When a backport is required, the newer object_backport_versions() will be tried, and if it raises NotImplementedError, then we will fall back to this (less optimal) method.
- Parameters
context – The context within which to perform the backport
objinst – An instance of a VersionedObject to be backported
target_version – The maximum version of the objinst’s class that is understood by the requesting host.
- Returns
The downgraded instance of objinst
- object_class_action(context, objname, objmethod, objver, args, kwargs)¶
Deprecated since version 0.10.0.
Use
object_class_action_versions()
instead.Perform an action on a VersionedObject class.
When indirection_api is set on a VersionedObject (to a class implementing this interface), classmethod calls on remotable_classmethod methods will cause this to be executed to actually make the desired call. This usually involves performing RPC.
- Parameters
context – The context within which to perform the action
objname – The registry name of the object
objmethod – The name of the action method to call
objver – The (remote) version of the object on which the action is being taken
args – The positional arguments to the action method
kwargs – The keyword arguments to the action method
- Returns
The result of the action method, which may (or may not) be an instance of the implementing VersionedObject class.
- object_class_action_versions(context, objname, objmethod, object_versions, args, kwargs)¶
Perform an action on a VersionedObject class.
When indirection_api is set on a VersionedObject (to a class implementing this interface), classmethod calls on remotable_classmethod methods will cause this to be executed to actually make the desired call. This usually involves performing RPC.
This differs from object_class_action() in that it is provided with object_versions, a manifest of client-side object versions for easier nested backports. The manifest is the result of calling obj_tree_get_versions().
NOTE: This was not in the initial spec for this interface, so the base class raises NotImplementedError if you don’t implement it. For backports, this method will be tried first, and if unimplemented, will fall back to object_class_action(). New implementations should provide this method instead of object_class_action()
- Parameters
context – The context within which to perform the action
objname – The registry name of the object
objmethod – The name of the action method to call
object_versions – A dict of {objname: version} mappings
args – The positional arguments to the action method
kwargs – The keyword arguments to the action method
- Returns
The result of the action method, which may (or may not) be an instance of the implementing VersionedObject class.
- class oslo_versionedobjects.fixture.IndirectionFixture(indirection_api=None)¶
- 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.
- 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.
- exception oslo_versionedobjects.fixture.ObjectHashMismatch(expected, actual)¶
- class oslo_versionedobjects.fixture.ObjectVersionChecker(obj_classes={})¶
- get_dependency_tree()¶
- get_hashes(extra_data_func=None)¶
Return a dict of computed object hashes.
- Parameters
extra_data_func – a function that is given the object class which gathers more relevant data about the class that is needed in versioning. Returns a tuple containing the extra data bits.
- test_compatibility_routines(use_manifest=False, init_args=None, init_kwargs=None)¶
Test obj_make_compatible() on all object classes.
- Parameters
use_manifest – a boolean that determines if the version manifest should be passed to obj_make_compatible
init_args – a dictionary of the format {obj_class: [arg1, arg2]} that will be used to pass arguments to init on the given obj_class. If no args are needed, the obj_class does not need to be added to the dict
init_kwargs – a dictionary of the format {obj_class: {‘kwarg1’: val1}} that will be used to pass kwargs to init on the given obj_class. If no kwargs are needed, the obj_class does not need to be added to the dict
- test_hashes(expected_hashes, extra_data_func=None)¶
- test_relationships(expected_tree)¶
- test_relationships_in_order()¶
- class oslo_versionedobjects.fixture.StableObjectJsonFixture¶
Fixture that makes sure we get stable JSON object representations.
Since objects contain things like set(), which can’t be converted to JSON, we have some situations where the representation isn’t fully deterministic. This doesn’t matter at all at runtime, but does to unit tests that try to assert things at a low level.
This fixture mocks the obj_to_primitive() call and makes sure to sort the list of changed fields (which came from a set) before returning it to the caller.
- 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.
- 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.
- class oslo_versionedobjects.fixture.VersionedObjectRegistryFixture¶
Use a VersionedObjectRegistry as a temp registry pattern fixture.
The pattern solution is to backup the object registry, register a class locally, and then restore the original registry. This could be used for test objects that do not need to be registered permanently but will have calls which lookup registration.
- static register(cls_name)¶
- 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.
- 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.
- oslo_versionedobjects.fixture.compare_obj(test, obj, db_obj, subs=None, allow_missing=None, comparators=None)¶
Compare a VersionedObject and a dict-like database object.
This automatically converts TZ-aware datetimes and iterates over the fields of the object.
- Parameters
test – The TestCase doing the comparison
obj – The VersionedObject to examine
db_obj – The dict-like database object to use as reference
subs – A dict of objkey=dbkey field substitutions
allow_missing – A list of fields that may not be in db_obj
comparators – Map of comparator functions to use for certain fields
- oslo_versionedobjects.fixture.get_method_spec(method)¶
Get a stable and compatible method spec.
Newer features in Python3 (kw-only arguments and annotations) are not supported or representable with inspect.getargspec() but many object hashes are already recorded using that method. This attempts to return something compatible with getargspec() when possible (i.e. when those features are not used), and otherwise just returns the newer getfullargspec() representation.
ObjectVersionChecker¶
Fingerprints¶
One function of the ObjectVersionChecker is to generate fingerprints of versioned objects. These fingerprints are a combination of the object’s version and a hash of the RPC-critical attributes of the object: fields and remotable methods.
The test_hashes() method is used to retrieve the expected and actual fingerprints of the objects. When using this method to assert the versions of objects in a local project, the expected fingerprints are the fingerprints of the previous state of the objects. These fingerprints are defined locally in the project and passed to test_hashes(). The actual fingerprints are the dynamically-generated fingerprints of the current state of the objects. If the expected and actual fingerprints do not match on an object, this means the RPC contract that was previously defined in the object is no longer the same. Because of this, the object’s version must be updated. When the version is updated and the tests are run again, a new fingerprint for the object is generated. This fingerprint should be written over the previous version of the fingerprint. This shows the newly generated fingerprint is now the most recent state of the object.