StructSubject¶
A subject for arbitrary structs. This is most useful when wrapping an ad-hoc struct (e.g. a struct specific to a particular function). Such ad-hoc structs are usually just plain data objects, so they don’t need special functionality that writing a full custom subject allows. If a struct would benefit from custom accessors or asserts, write a custom subject instead.
This subject is usually used as a helper to a more formally defined subject that
knows the shape of the struct it needs to wrap. For example, a FooInfoSubject
implementation might use it to handle FooInfo.struct_with_a_couple_fields
.
Note the resulting subject object is not a direct replacement for the struct
being wrapped:
* Structs wrapped by this subject have the attributes exposed as functions,
not as plain attributes. This matches the other subject classes and defers
converting an attribute to a subject unless necessary.
* The attribute name actual
is reserved.
Example usages¶
To use it as part of a custom subject returning a sub-value, construct it using
subjects.struct()
like so:
load("@rules_testing//lib:truth.bzl", "subjects")
def _my_subject_foo(self):
return subjects.struct(
self.actual.foo,
meta = self.meta.derive("foo()"),
attrs = dict(a=subjects.int, b=subjects.str),
)
If you’re checking a struct directly in a test, then you can use
Expect.that_struct
. You’ll still have to pass the attrs
arg so it knows how
to map the attributes to the matching subject factories.
def _foo_test(env):
actual = env.expect.that_struct(
struct(a=1, b="x"),
attrs = dict(a=subjects.int, b=subjects.str)
)
actual.a().equals(1)
actual.b().equals("x")
StructSubject.new¶
StructSubject.new(actual, meta, attrs)
Creates a StructSubject
, which is a thin wrapper around a struct
.
PARAMETERS ¶
- actual¶:
(
struct
) the struct to wrap.- meta¶:
(
ExpectMeta
) object of call context information.- attrs¶:
(
dict
ofstr
to [callable
]) the functions to convert attributes to subjects. The keys are attribute names that must exist onactual
. The values are functions with the signaturedef factory(value, *, meta)
, wherevalue
is the actual attribute value of the struct, andmeta
is anExpectMeta
object.
- RETURNS ¶
StructSubject
object, which is a struct with the following shape: *actual
attribute, the underlying struct that was wrapped. * A callable attribute for eachattrs
entry; it takes no args and returns what the corresponding factory fromattrs
returns.