diff options
Diffstat (limited to 'lib/private/struct_subject.bzl')
-rw-r--r-- | lib/private/struct_subject.bzl | 108 |
1 files changed, 108 insertions, 0 deletions
diff --git a/lib/private/struct_subject.bzl b/lib/private/struct_subject.bzl new file mode 100644 index 0000000..7822341 --- /dev/null +++ b/lib/private/struct_subject.bzl @@ -0,0 +1,108 @@ +# Copyright 2023 The Bazel Authors. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +"""# 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") +``` +""" + +def _struct_subject_new(actual, *, meta, attrs): + """Creates a `StructSubject`, which is a thin wrapper around a [`struct`]. + + Args: + 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. + """ + attr_accessors = {} + for name, factory in attrs.items(): + if not hasattr(actual, name): + fail("Struct missing attribute: '{}' (from expression {})".format( + name, + meta.current_expr(), + )) + attr_accessors[name] = _make_attr_accessor(actual, name, factory, meta) + + public = struct(actual = actual, **attr_accessors) + return public + +def _make_attr_accessor(actual, name, factory, meta): + # A named function is used instead of a lambda so stack traces are easier to + # grok. + def attr_accessor(): + return factory(getattr(actual, name), meta = meta.derive(name + "()")) + + return attr_accessor + +# buildifier: disable=name-conventions +StructSubject = struct( + # keep sorted start + new = _struct_subject_new, + # keep sorted end +) |