# Expect

{.starlark-object}
## Expect.new

{.starlark-signature}
Expect.new([env](#expect_new_env),
[meta](#expect_new_meta))

Creates a new Expect object.

Internal; only other `Expect` methods should be calling this.


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

{.params-box}
:[env[¶](#expect_new_env){.headerlink}]{.span}: []{#expect_new_env}
  unittest env struct or some approximation.
:[meta[¶](#expect_new_meta){.headerlink}]{.span}: []{#expect_new_meta}
  ([`ExpectMeta`]) metadata about call chain and state.

{#expect_new_returns}
RETURNS [¶](#expect_new_returns){.headerlink}
: [`Expect`] object


{.starlark-object}
## Expect.new_from_env

{.starlark-signature}
Expect.new_from_env([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.


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

{.params-box}
:[env[¶](#expect_new_from_env_env){.headerlink}]{.span}: []{#expect_new_from_env_env}
  unittest env struct, or some approximation. There are several
  attributes that override regular behavior; see above doc.

{#expect_new_from_env_returns}
RETURNS [¶](#expect_new_from_env_returns){.headerlink}
: [`Expect`] object


{.starlark-object}
## Expect.that_action

{.starlark-signature}
Expect.that_action([action](#expect_that_action_action))

Creates a subject for asserting Actions.

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

:[action[¶](#expect_that_action_action){.headerlink}]{.span}: []{#expect_that_action_action}
  ([`Action`]) the action to check.

{#expect_that_action_returns}
RETURNS [¶](#expect_that_action_returns){.headerlink}
: [`ActionSubject`] object.


{.starlark-object}
## Expect.that_bool

{.starlark-signature}
Expect.that_bool([value](#expect_that_bool_value),
[expr](#expect_that_bool_expr)="boolean")

Creates a subject for asserting a boolean.

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

:[value[¶](#expect_that_bool_value){.headerlink}]{.span}: []{#expect_that_bool_value}
  ([`bool`]) the bool to check.
:[expr[¶](#expect_that_bool_expr){.headerlink}]{.span}: []{#expect_that_bool_expr}
(_default `"boolean"`_)   ([`str`]) the starting "value of" expression to report in errors.

{#expect_that_bool_returns}
RETURNS [¶](#expect_that_bool_returns){.headerlink}
: [`BoolSubject`] object.


{.starlark-object}
## Expect.that_collection

{.starlark-signature}
Expect.that_collection([collection](#expect_that_collection_collection),
[expr](#expect_that_collection_expr)="collection",
[kwargs](#expect_that_collection_kwargs))

Creates a subject for asserting collections.

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

:[collection[¶](#expect_that_collection_collection){.headerlink}]{.span}: []{#expect_that_collection_collection}
  The collection (list or depset) to assert.
:[expr[¶](#expect_that_collection_expr){.headerlink}]{.span}: []{#expect_that_collection_expr}
(_default `"collection"`_)   ([`str`]) the starting "value of" expression to report in errors.
:[kwargs[¶](#expect_that_collection_kwargs){.headerlink}]{.span}: []{#expect_that_collection_kwargs}
  Additional kwargs to pass onto CollectionSubject.new

{#expect_that_collection_returns}
RETURNS [¶](#expect_that_collection_returns){.headerlink}
: [`CollectionSubject`] object.


{.starlark-object}
## Expect.that_depset_of_files

{.starlark-signature}
Expect.that_depset_of_files([depset_files](#expect_that_depset_of_files_depset_files))

Creates a subject for asserting a depset of files.

Method: Expect.that_depset_of_files


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

:[depset_files[¶](#expect_that_depset_of_files_depset_files){.headerlink}]{.span}: []{#expect_that_depset_of_files_depset_files}
  ([`depset`] of [`File`]) the values to assert on.

{#expect_that_depset_of_files_returns}
RETURNS [¶](#expect_that_depset_of_files_returns){.headerlink}
: [`DepsetFileSubject`] object.


{.starlark-object}
## Expect.that_dict

{.starlark-signature}
Expect.that_dict([mapping](#expect_that_dict_mapping),
[meta](#expect_that_dict_meta)=None)

Creates a subject for asserting a dict.

Method: Expect.that_dict


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

:[mapping[¶](#expect_that_dict_mapping){.headerlink}]{.span}: []{#expect_that_dict_mapping}
  ([`dict`]) the values to assert on
:[meta[¶](#expect_that_dict_meta){.headerlink}]{.span}: []{#expect_that_dict_meta}
(_default `None`_)   ([`ExpectMeta`]) optional custom call chain information to use instead

{#expect_that_dict_returns}
RETURNS [¶](#expect_that_dict_returns){.headerlink}
: [`DictSubject`] object.


{.starlark-object}
## Expect.that_file

{.starlark-signature}
Expect.that_file([file](#expect_that_file_file),
[meta](#expect_that_file_meta)=None)

Creates a subject for asserting a file.

Method: Expect.that_file


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

:[file[¶](#expect_that_file_file){.headerlink}]{.span}: []{#expect_that_file_file}
  ([`File`]) the value to assert.
:[meta[¶](#expect_that_file_meta){.headerlink}]{.span}: []{#expect_that_file_meta}
(_default `None`_)   ([`ExpectMeta`]) optional custom call chain information to use instead

{#expect_that_file_returns}
RETURNS [¶](#expect_that_file_returns){.headerlink}
: [`FileSubject`] object.


{.starlark-object}
## Expect.that_int

{.starlark-signature}
Expect.that_int([value](#expect_that_int_value),
[expr](#expect_that_int_expr)="integer")

Creates a subject for asserting an `int`.

Method: Expect.that_int


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

:[value[¶](#expect_that_int_value){.headerlink}]{.span}: []{#expect_that_int_value}
  ([`int`]) the value to check against.
:[expr[¶](#expect_that_int_expr){.headerlink}]{.span}: []{#expect_that_int_expr}
(_default `"integer"`_)   ([`str`]) the starting "value of" expression to report in errors.

{#expect_that_int_returns}
RETURNS [¶](#expect_that_int_returns){.headerlink}
: [`IntSubject`] object.


{.starlark-object}
## Expect.that_str

{.starlark-signature}
Expect.that_str([value](#expect_that_str_value))

Creates a subject for asserting a `str`.

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

:[value[¶](#expect_that_str_value){.headerlink}]{.span}: []{#expect_that_str_value}
  ([`str`]) the value to check against.

{#expect_that_str_returns}
RETURNS [¶](#expect_that_str_returns){.headerlink}
: [`StrSubject`] object.


{.starlark-object}
## Expect.that_struct

{.starlark-signature}
Expect.that_struct([value](#expect_that_struct_value),
[attrs](#expect_that_struct_attrs),
[expr](#expect_that_struct_expr)="struct")

Creates a subject for asserting a `struct`.

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

:[value[¶](#expect_that_struct_value){.headerlink}]{.span}: []{#expect_that_struct_value}
  ([`struct`]) the value to check against.
:[attrs[¶](#expect_that_struct_attrs){.headerlink}]{.span}: []{#expect_that_struct_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[¶](#expect_that_struct_expr){.headerlink}]{.span}: []{#expect_that_struct_expr}
(_default `"struct"`_)   ([`str`]) The starting "value of" expression to report in errors.

{#expect_that_struct_returns}
RETURNS [¶](#expect_that_struct_returns){.headerlink}
: [`StructSubject`] object.


{.starlark-object}
## Expect.that_target

{.starlark-signature}
Expect.that_target([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"


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

:[target[¶](#expect_that_target_target){.headerlink}]{.span}: []{#expect_that_target_target}
  ([`Target`]) subject target to check against.

{#expect_that_target_returns}
RETURNS [¶](#expect_that_target_returns){.headerlink}
: [`TargetSubject`] object.


{.starlark-object}
## Expect.that_value

{.starlark-signature}
Expect.that_value([value](#expect_that_value_value),
[factory](#expect_that_value_factory),
[expr](#expect_that_value_expr)="value")

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

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

:[value[¶](#expect_that_value_value){.headerlink}]{.span}: []{#expect_that_value_value}
  ([`struct`]) the value to check against.
:[factory[¶](#expect_that_value_factory){.headerlink}]{.span}: []{#expect_that_value_factory}
  A subject factory (a function that takes value and meta).
  Eg. subjects.collection
:[expr[¶](#expect_that_value_expr){.headerlink}]{.span}: []{#expect_that_value_expr}
(_default `"value"`_)   ([`str`]) The starting "value of" expression to report in errors.

{#expect_that_value_returns}
RETURNS [¶](#expect_that_value_returns){.headerlink}
: A subject corresponding to the type returned by the factory.


{.starlark-object}
## Expect.where

{.starlark-signature}
Expect.where([details](#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.


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

:[details[¶](#expect_where_details){.headerlink}]{.span}: []{#expect_where_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.

{#expect_where_returns}
RETURNS [¶](#expect_where_returns){.headerlink}
: [`Expect`] object with separate metadata derived from the original self.


[`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