# 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:

```starlark
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.

```starlark
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")
```

{.starlark-object}
## StructSubject.new

{.starlark-signature}
StructSubject.new([actual](#structsubject_new_actual),
[meta](#structsubject_new_meta),
[attrs](#structsubject_new_attrs))

Creates a `StructSubject`, which is a thin wrapper around a [`struct`].

{#structsubject_new_parameters}
**PARAMETERS** [¶](#structsubject_new_parameters){.headerlink}

{.params-box}
:[actual[¶](#structsubject_new_actual){.headerlink}]{.span}: []{#structsubject_new_actual}
  ([`struct`]) the struct to wrap.
:[meta[¶](#structsubject_new_meta){.headerlink}]{.span}: []{#structsubject_new_meta}
  ([`ExpectMeta`]) object of call context information.
:[attrs[¶](#structsubject_new_attrs){.headerlink}]{.span}: []{#structsubject_new_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.

{#structsubject_new_returns}
RETURNS [¶](#structsubject_new_returns){.headerlink}
: [`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.


[`Action`]: https://bazel.build/rules/lib/Action
[`ActionSubject`]: /api/action_subject
[`bool`]: https://bazel.build/rules/lib/bool
[`BoolSubject`]: /api/bool_subject
[`CollectionSubject`]: /api/collection_subject
[`depset`]: https://bazel.build/rules/lib/depset
[`DepsetFileSubject`]: /api/depset_file_subject
[`dict`]: https://bazel.build/rules/lib/dict
[`DictSubject`]: /api/dict_subject
[`Expect`]: /api/expect
[`ExpectMeta`]: /api/expect_meta
[`File`]: https://bazel.build/rules/lib/File
[`FileSubject`]: /api/file_subject
[`format_str`]: /api/expect_meta.html#expectmeta-format-str
[`IntSubject`]: /api/int_subject
[`Label`]: https://bazel.build/rules/lib/Label
[`LabelSubject`]: /api/label_subject
[`list`]: https://bazel.build/rules/lib/list
[`Ordered`]: /api/ordered
[`RunfilesSubject`]: /api/runfiles_subject
[`str`]: https://bazel.build/rules/lib/string
[`struct`]: https://bazel.build/rules/lib/builtins/struct
[`StrSubject`]: /api/str_subject
[`StructSubject`]: /api/struct_subject
[`Target`]: https://bazel.build/rules/lib/Target
[`TargetSubject`]: /api/target_subject
[target-name]: https://bazel.build/concepts/labels#target-names
[attr-label]: https://bazel.build/concepts/labels