Expect¶

Expect.new¶

Expect.new(env, meta)

Creates a new Expect object.

Internal; only other Expect methods should be calling this.

PARAMETERS ¶

env¶:: unittest env struct or some approximation.
meta¶:: (ExpectMeta) metadata about call chain and state.

RETURNS ¶: Expect object

Expect.new_from_env¶

Expect.new_from_env(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

Expect.that_action¶

Expect.that_action(action)

Creates a subject for asserting Actions.

PARAMETERS ¶

action¶:: (Action) the action to check.

RETURNS ¶: ActionSubject object.

Expect.that_bool¶

Expect.that_bool(value, expr=”boolean”)

Creates a subject for asserting a boolean.

PARAMETERS ¶

value¶:: (bool) the bool to check.
expr¶:: (default "boolean") (str) the starting “value of” expression to report in errors.

RETURNS ¶: BoolSubject object.

Expect.that_collection¶

Expect.that_collection(collection, expr=”collection”, kwargs)

Creates a subject for asserting collections.

PARAMETERS ¶

collection¶:: The collection (list or depset) to assert.
expr¶:: (default "collection") (str) the starting “value of” expression to report in errors.
kwargs¶:: Additional kwargs to pass onto CollectionSubject.new

RETURNS ¶: CollectionSubject object.

Expect.that_depset_of_files¶

Expect.that_depset_of_files(depset_files)

Creates a subject for asserting a depset of files.

Method: Expect.that_depset_of_files

PARAMETERS ¶

depset_files¶:: (depset of File) the values to assert on.

RETURNS ¶: DepsetFileSubject object.

Expect.that_dict¶

Expect.that_dict(mapping, meta=None)

Creates a subject for asserting a dict.

Method: Expect.that_dict

PARAMETERS ¶

mapping¶:: (dict) the values to assert on
meta¶:: (default None) (ExpectMeta) optional custom call chain information to use instead

RETURNS ¶: DictSubject object.

Expect.that_file¶

Expect.that_file(file, meta=None)

Creates a subject for asserting a file.

Method: Expect.that_file

PARAMETERS ¶

file¶:: (File) the value to assert.
meta¶:: (default None) (ExpectMeta) optional custom call chain information to use instead

RETURNS ¶: FileSubject object.

Expect.that_int¶

Expect.that_int(value, expr=”integer”)

Creates a subject for asserting an int.

Method: Expect.that_int

PARAMETERS ¶

value¶:: ([int]) the value to check against.
expr¶:: (default "integer") (str) the starting “value of” expression to report in errors.

RETURNS ¶: IntSubject object.

Expect.that_str¶

Expect.that_str(value)

Creates a subject for asserting a str.

PARAMETERS ¶

value¶:: (str) the value to check against.

RETURNS ¶: StrSubject object.

Expect.that_struct¶

Expect.that_struct(value, attrs, expr=”struct”)

Creates a subject for asserting a struct.

PARAMETERS ¶

value¶:: (struct) the value to check against.
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.
expr¶:: (default "struct") (str) The starting “value of” expression to report in errors.

RETURNS ¶: StructSubject object.

Expect.that_target¶

Expect.that_target(target)

Creates a subject for asserting a Target.

This adds the following parameters to ExpectMeta.format_str: {package}: The target’s package, e.g. “foo/bar” from “//foo/bar:baz” {name}: The target’s base name, e.g., “baz” from “//foo/bar:baz”

PARAMETERS ¶

target¶:: (Target) subject target to check against.

RETURNS ¶: TargetSubject object.

Expect.that_value¶

Expect.that_value(value, factory, expr=”value”)

Creates a subject for asserting an arbitrary value of a custom type.

PARAMETERS ¶

value¶:: (struct) the value to check against.
factory¶:: A subject factory (a function that takes value and meta). Eg. subjects.collection
expr¶:: (default "value") (str) The starting “value of” expression to report in errors.

RETURNS ¶: A subject corresponding to the type returned by the factory.

Expect.where¶

Expect.where(details)

Add additional information about the assertion.

This is useful for attaching information that isn’t part of the call chain or some reason. Example usage:

expect(env).where(platform=ctx.attr.platform).that_str(...)

Would include “platform: {ctx.attr.platform}” in failure messages.

PARAMETERS ¶

details¶:: (dict of str to value) Each named arg is added to the metadata details with the provided string, which is printed as part of displaying any failures.

RETURNS ¶: Expect object with separate metadata derived from the original self.