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 of str to [callable]) the functions to convert attributes to subjects. The keys are attribute names that must exist on actual. The values are functions with the signature def factory(value, *, meta), where value is the actual attribute value of the struct, and meta is an ExpectMeta object.

RETURNS

StructSubject object, which is a struct with the following shape: * actual attribute, the underlying struct that was wrapped. * A callable attribute for each attrs entry; it takes no args and returns what the corresponding factory from attrs returns.