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.all¶

matching.all(matchers)

Match that all of multiple matchers match.

PARAMETERS ¶

matchers¶:: list of [Matcher]. If all match, then it is considered a match.

RETURNS ¶: [Matcher] (see _match_custom)

matching.any¶

matching.any(matchers)

Match that any of multiple matchers match.

See also: is_in for checking if a value is one amongst multiple values.

PARAMETERS ¶

matchers¶:: list of [Matcher]. If any match, then it is considered a match.

RETURNS ¶: [Matcher] (see _match_custom)

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¶

matching.custom(desc, func)

Wrap an arbitrary function up as a Matcher.

Method: Matcher.new

Matcher struct attributes:

desc: (str) a human-friendly description
match: (callable) accepts 1 positional arg (the value to match) and returns bool (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 is value.

matching.file_basename_contains¶

matching.file_basename_contains(substr)

Match that a a File.basename string contains a substring.

PARAMETERS ¶

substr¶:: (str) the substring to match.

RETURNS ¶: [Matcher] (see _match_custom()).

matching.file_basename_equals¶

matching.file_basename_equals(value)

Match that a File.basename string equals value.

PARAMETERS ¶

value¶:: (str) the basename to match.

RETURNS ¶: [Matcher] instance

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 ¶

values¶:: (list of str) the extensions to match.

RETURNS ¶: [Matcher] instance

matching.file_path_matches¶

matching.file_path_matches(pattern)

Match that a File.path string matches a glob-style pattern.

PARAMETERS ¶

pattern¶:: (str) the pattern to match. “*” can be used to denote “match anything”.

RETURNS ¶: [Matcher] (see _match_custom).

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.

See also: matching.any for matching amongst arbitrary other matchers.

PARAMETERS ¶

values¶:: The collection that the value must be within.

RETURNS ¶: [Matcher] (see _match_custom()).

matching.is_matcher¶

matching.is_matcher(obj)

PARAMETERS ¶

obj¶:: undocumented

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 ¶

desc¶:: (str) human-friendly string.

RETURNS ¶: [Matcher] (see _match_custom).

matching.str_endswith¶

matching.str_endswith(suffix)

Match that a string contains another string.

PARAMETERS ¶

suffix¶:: (str) the suffix that must be present

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 ¶

prefix¶:: (str) the prefix that must be present

RETURNS ¶: [Matcher] (see _match_custom).

subjects.bool¶

subjects.bool(value, meta)

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”, format=False)

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.
format¶:: (default False) (bool) True if asserted values should be formatted.

RETURNS ¶: CollectionSubject.

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¶:: (depset of File) the values to assert on.
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¶

subjects.file(file, meta)

Creates a FileSubject asserting against the given file.

Method: FileSubject.new

PARAMETERS ¶

file¶:: (File) the file to assert against.
meta¶:: (ExpectMeta)

RETURNS ¶: FileSubject object.

subjects.int¶

subjects.int(value, meta)

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 ¶: IntSubject.

subjects.label¶

subjects.label(label, meta)

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 ¶: LabelSubject.

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) (optional str) what type of runfiles they are, usually “data” or “default”. If not known or not applicable, use None.

RETURNS ¶: RunfilesSubject object.

subjects.str¶

subjects.str(actual, meta)

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

subjects.target¶

subjects.target(target, meta)

Creates a subject for asserting Targets.

Method: TargetSubject.new

Public attributes:

actual: The wrapped Target 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 regular Expect.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 (a Target and a [provider]) and returns bool (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.

RETURNS ¶: Expect object