Truth¶
Truth-style asserts for Bazel’s Starlark.
These asserts follow the Truth-style way of performing assertions. This basically means the actual value is wrapped in a type-specific object that provides type-specific assertion methods. This style provides several benefits: * A fluent API that more directly expresses the assertion * More egonomic assert functions * Error messages with more informative context * Promotes code reuses at the type-level.
For more detailed documentation, see the docs on GitHub.
Basic usage¶
NOTE: This example assumes usage of [rules_testing
]’s [analysis_test
]
framework, but that framework is not required.
def foo_test(env, target):
subject = env.expect.that_target(target)
subject.runfiles().contains_at_least(["foo.txt"])
subject.executable().equals("bar.exe")
subject = env.expect.that_action(...)
subject.contains_at_least_args(...)
matching.contains¶
matching.contains(contained)
Match that contained
is within the to-be-matched value.
This is equivalent to: contained in to_be_matched
. See _match_is_in
for the reversed operation.
PARAMETERS ¶
- contained¶:
the value that to-be-matched value must contain.
- RETURNS ¶
[
Matcher
] (see_match_custom
).
matching.custom¶
Wrap an arbitrary function up as a Matcher.
Method: Matcher.new
Matcher
struct attributes:
desc
: (str
) a human-friendly descriptionmatch
: (callable) accepts 1 positional arg (the value to match) and returnsbool
(True
if it matched,False
if not).
PARAMETERS ¶
- desc¶:
(
str
) a human-friendly string describing what is matched.- func¶:
(callable) accepts 1 positional arg (the value to match) and returns
bool
(True
if it matched,False
if not).
- RETURNS ¶
[
Matcher
] (see above).
matching.equals_wrapper¶
matching.equals_wrapper(value)
Match that a value equals value
, but use value
as the desc
.
This is a helper so that simple equality comparisons can re-use predicate based APIs.
PARAMETERS ¶
- value¶:
object, the value that must be equal to.
- RETURNS ¶
[
Matcher
] (see_match_custom()
), whose description isvalue
.
matching.file_basename_contains¶
matching.file_basename_contains(substr)
Match that a a File.basename
string contains a substring.
PARAMETERS ¶
- RETURNS ¶
[
Matcher
] (see_match_custom()
).
matching.file_basename_equals¶
matching.file_basename_equals(value)
Match that a File.basename
string equals value
.
PARAMETERS ¶
- RETURNS ¶
[
Matcher
] instance
matching.file_path_matches¶
matching.file_path_matches(pattern)
Match that a File.path
string matches a glob-style pattern.
PARAMETERS ¶
- RETURNS ¶
[
Matcher
] (see_match_custom
).
matching.file_extension_in¶
matching.file_extension_in(values)
Match that a File.extension
string is any of values
.
See also: file_path_matches
for matching extensions that
have multiple parts, e.g. *.tar.gz
or *.so.*
.
PARAMETERS ¶
- RETURNS ¶
[
Matcher
] instance
matching.is_in¶
matching.is_in(values)
Match that the to-be-matched value is in a collection of other values.
This is equivalent to: to_be_matched in values
. See _match_contains
for the reversed operation.
PARAMETERS ¶
- values¶:
The collection that the value must be within.
- RETURNS ¶
[
Matcher
] (see_match_custom()
).
matching.never¶
matching.never(desc)
A matcher that never matches.
This is mostly useful for testing, as it allows preventing any match while providing a custom description.
PARAMETERS ¶
- RETURNS ¶
[
Matcher
] (see_match_custom
).
matching.str_endswith¶
matching.str_endswith(suffix)
Match that a string contains another string.
PARAMETERS ¶
- RETURNS ¶
[
Matcher
] (see_match_custom
).
matching.str_matches¶
matching.str_matches(pattern)
Match that a string matches a glob-style pattern.
PARAMETERS ¶
- pattern¶:
(
str
) the pattern to match.*
can be used to denote “match anything”. There is an implicit*
at the start and end of the pattern.
- RETURNS ¶
[
Matcher
] object.
matching.str_startswith¶
matching.str_startswith(prefix)
Match that a string contains another string.
PARAMETERS ¶
- RETURNS ¶
[
Matcher
] (see_match_custom
).
matching.is_matcher¶
matching.is_matcher(obj)
PARAMETERS ¶
- obj¶:
undocumented
subjects.bool¶
Creates a “BoolSubject” struct.
Method: BoolSubject.new
PARAMETERS ¶
- value¶:
(
bool
) the value to assert against.- meta¶:
(
ExpectMeta
) the metadata about the call chain.
- RETURNS ¶
A
BoolSubject
.
subjects.collection¶
subjects.collection(values, meta, container_name=”values”, sortable=True, element_plural_name=”elements”)
Creates a “CollectionSubject” struct.
Method: CollectionSubject.new
Public Attributes:
actual
: The wrapped collection.
PARAMETERS ¶
- values¶:
([
collection
]) the values to assert against.- meta¶:
(
ExpectMeta
) the metadata about the call chain.- container_name¶:
(default
"values"
) (str
) conceptual name of the container.- sortable¶:
(default
True
) (bool
) True if output should be sorted for display, False if not.- element_plural_name¶:
(default
"elements"
) (str
) the plural word for the values in the container.
- RETURNS ¶
subjects.default_info¶
subjects.default_info(info, meta)
Creates a DefaultInfoSubject
PARAMETERS ¶
- info¶:
([
DefaultInfo
]) the DefaultInfo object to wrap.- meta¶:
(
ExpectMeta
) call chain information.
- RETURNS ¶
[
DefaultInfoSubject
] object.
subjects.depset_file¶
subjects.depset_file(files, meta, container_name=”depset”, element_plural_name=”files”)
Creates a DepsetFileSubject asserting on files
.
Method: DepsetFileSubject.new
PARAMETERS ¶
- files¶:
- meta¶:
(
ExpectMeta
) of call chain information.- container_name¶:
(default
"depset"
) (str
) conceptual name of the container.- element_plural_name¶:
(default
"files"
) (str
) the plural word for the values in the container.
- RETURNS ¶
DepsetFileSubject
object.
subjects.dict¶
subjects.dict(actual, meta, container_name=”dict”, key_plural_name=”keys”)
Creates a new DictSubject
.
Method: DictSubject.new
PARAMETERS ¶
- actual¶:
(
dict
) the dict to assert against.- meta¶:
(
ExpectMeta
) of call chain information.- container_name¶:
(default
"dict"
) (str
) conceptual name of the dict.- key_plural_name¶:
(default
"keys"
) (str
) the plural word for the keys of the dict.
- RETURNS ¶
New
DictSubject
struct.
subjects.file¶
Creates a FileSubject asserting against the given file.
Method: FileSubject.new
PARAMETERS ¶
- RETURNS ¶
FileSubject
object.
subjects.int¶
Create an “IntSubject” struct.
Method: IntSubject.new
PARAMETERS ¶
- value¶:
(optional [
int
]) the value to perform asserts against may be None.- meta¶:
(
ExpectMeta
) the meta data about the call chain.
- RETURNS ¶
subjects.label¶
Creates a new LabelSubject
for asserting Label
objects.
Method: LabelSubject.new
PARAMETERS ¶
- label¶:
(
Label
) the label to check against.- meta¶:
(
ExpectMeta
) the metadata about the call chain.
- RETURNS ¶
subjects.runfiles¶
subjects.runfiles(runfiles, meta, kind=None)
Creates a “RunfilesSubject” struct.
Method: RunfilesSubject.new
PARAMETERS ¶
- runfiles¶:
([
runfiles
]) the runfiles to check against.- meta¶:
(
ExpectMeta
) the metadata about the call chain.- kind¶:
(default
None
) (optionalstr
) what type of runfiles they are, usually “data” or “default”. If not known or not applicable, use None.
- RETURNS ¶
RunfilesSubject
object.
subjects.str¶
Creates a subject for asserting strings.
Method: StrSubject.new
PARAMETERS ¶
- actual¶:
(
str
) the string to check against.- meta¶:
(
ExpectMeta
) of call chain information.
- RETURNS ¶
StrSubject
object.
subjects.struct¶
subjects.struct(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.
subjects.target¶
Creates a subject for asserting Targets.
Method: TargetSubject.new
Public attributes:
actual
: The wrappedTarget
object.
PARAMETERS ¶
- target¶:
(
Target
) the target to check against.- meta¶:
(
ExpectMeta
) metadata about the call chain.
- RETURNS ¶
TargetSubject
object
truth.expect¶
truth.expect(env)
Wrapper around env
.
This is the entry point to the Truth-style assertions. Example usage: expect = expect(env) expect.that_action(action).contains_at_least_args(…)
The passed in env
object allows optional attributes to be set to
customize behavior. Usually this is helpful for testing. See _fake_env()
in truth_tests.bzl for examples.
fail
: callable that takes a failure message. If present, it will be called instead of the regularExpect.add_failure
logic.get_provider
: callable that takes 2 positional args (target and provider) and returns the found provider or fails.has_provider
: callable that takes 2 positional args (aTarget
and a [provider
]) and returnsbool
(True
if present,False
otherwise) or fails.
PARAMETERS ¶
- env¶:
unittest env struct, or some approximation. There are several attributes that override regular behavior; see above doc.