# CollectionSubject

{.starlark-object}
## CollectionSubject.contains

{.starlark-signature}
CollectionSubject.contains([expected](#collectionsubject_contains_expected))

Asserts that `expected` is within the collection.

Method: CollectionSubject.contains


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

:[expected[¶](#collectionsubject_contains_expected){.headerlink}]{.span}: []{#collectionsubject_contains_expected}
  ([`str`]) the value that must be present.


{.starlark-object}
## CollectionSubject.contains_at_least

{.starlark-signature}
CollectionSubject.contains_at_least([expected](#collectionsubject_contains_at_least_expected))

Assert that the collection is a subset of the given predicates.

Method: CollectionSubject.contains_at_least

The collection must contain all the values. It can contain extra elements.
The multiplicity of values is respected. Checking that the relative order
of matches is the same as the passed-in expected values order can done by
calling `in_order()`.


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

:[expected[¶](#collectionsubject_contains_at_least_expected){.headerlink}]{.span}: []{#collectionsubject_contains_at_least_expected}
  ([`list`]) values that must be in the collection.

{#collectionsubject_contains_at_least_returns}
RETURNS [¶](#collectionsubject_contains_at_least_returns){.headerlink}
: [`Ordered`] (see `_ordered_incorrectly_new`).


{.starlark-object}
## CollectionSubject.contains_at_least_predicates

{.starlark-signature}
CollectionSubject.contains_at_least_predicates([matchers](#collectionsubject_contains_at_least_predicates_matchers))

Assert that the collection is a subset of the given predicates.

Method: CollectionSubject.contains_at_least_predicates

The collection must match all the predicates. It can contain extra elements.
The multiplicity of matchers is respected. Checking that the relative order
of matches is the same as the passed-in matchers order can done by calling
`in_order()`.


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

:[matchers[¶](#collectionsubject_contains_at_least_predicates_matchers){.headerlink}]{.span}: []{#collectionsubject_contains_at_least_predicates_matchers}
  ([`list`] of [`Matcher`]) (see `matchers` struct).

{#collectionsubject_contains_at_least_predicates_returns}
RETURNS [¶](#collectionsubject_contains_at_least_predicates_returns){.headerlink}
: [`Ordered`] (see `_ordered_incorrectly_new`).


{.starlark-object}
## CollectionSubject.contains_exactly

{.starlark-signature}
CollectionSubject.contains_exactly([expected](#collectionsubject_contains_exactly_expected))

Check that a collection contains exactly the given elements.

Method: CollectionSubject.contains_exactly

* Multiplicity is respected.
* The collection must contain all the values, no more or less.
* Checking that the order of matches is the same as the passed-in matchers
  order can be done by call `in_order()`.

The collection must contain all the values and no more. Multiplicity of
values is respected. Checking that the order of matches is the same as the
passed-in matchers order can done by calling `in_order()`.


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

:[expected[¶](#collectionsubject_contains_exactly_expected){.headerlink}]{.span}: []{#collectionsubject_contains_exactly_expected}
  ([`list`]) values that must exist.

{#collectionsubject_contains_exactly_returns}
RETURNS [¶](#collectionsubject_contains_exactly_returns){.headerlink}
: [`Ordered`] (see `_ordered_incorrectly_new`).


{.starlark-object}
## CollectionSubject.contains_exactly_predicates

{.starlark-signature}
CollectionSubject.contains_exactly_predicates([expected](#collectionsubject_contains_exactly_predicates_expected))

Check that the values correspond 1:1 to the predicates.

Method: CollectionSubject.contains_exactly_predicates

* There must be a 1:1 correspondence between the container values and the
  predicates.
* Multiplicity is respected (i.e., if the same predicate occurs twice, then
  two distinct elements must match).
* Matching occurs in first-seen order. That is, a predicate will "consume"
  the first value in `actual_container` it matches.
* The collection must match all the predicates, no more or less.
* Checking that the order of matches is the same as the passed-in matchers
  order can be done by call `in_order()`.

Note that confusing results may occur if predicates with overlapping
match conditions are used. For example, given:
  actual=["a", "ab", "abc"],
  predicates=[<contains a>, <contains b>, <equals a>]

Then the result will be they aren't equal: the first two predicates
consume "a" and "ab", leaving only "abc" for the <equals a> predicate
to match against, which fails.


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

:[expected[¶](#collectionsubject_contains_exactly_predicates_expected){.headerlink}]{.span}: []{#collectionsubject_contains_exactly_predicates_expected}
  ([`list`] of [`Matcher`]) that must match.

{#collectionsubject_contains_exactly_predicates_returns}
RETURNS [¶](#collectionsubject_contains_exactly_predicates_returns){.headerlink}
: [`Ordered`] (see `_ordered_incorrectly_new`).


{.starlark-object}
## CollectionSubject.contains_no_duplicates

{.starlark-signature}
CollectionSubject.contains_no_duplicates()

Asserts that the collection contains no duplicates.

Method: CollectionSubject.contains_no_duplicates




{.starlark-object}
## CollectionSubject.contains_none_of

{.starlark-signature}
CollectionSubject.contains_none_of([values](#collectionsubject_contains_none_of_values))

Asserts the collection contains none of `values`.

Method: CollectionSubject.contains_none_of


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

:[values[¶](#collectionsubject_contains_none_of_values){.headerlink}]{.span}: []{#collectionsubject_contains_none_of_values}
  ([`collection`]) values of which none of are allowed to exist.


{.starlark-object}
## CollectionSubject.contains_predicate

{.starlark-signature}
CollectionSubject.contains_predicate([matcher](#collectionsubject_contains_predicate_matcher))

Asserts that `matcher` matches at least one value.

Method: CollectionSubject.contains_predicate


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

:[matcher[¶](#collectionsubject_contains_predicate_matcher){.headerlink}]{.span}: []{#collectionsubject_contains_predicate_matcher}
  ([`Matcher`]) (see `matchers` struct).


{.starlark-object}
## CollectionSubject.has_size

{.starlark-signature}
CollectionSubject.has_size([expected](#collectionsubject_has_size_expected))

Asserts that `expected` is the size of the collection.

Method: CollectionSubject.has_size


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

:[expected[¶](#collectionsubject_has_size_expected){.headerlink}]{.span}: []{#collectionsubject_has_size_expected}
  ([`int`]) the expected size of the collection.


{.starlark-object}
## CollectionSubject.new

{.starlark-signature}
CollectionSubject.new([values](#collectionsubject_new_values),
[meta](#collectionsubject_new_meta),
[container_name](#collectionsubject_new_container_name)="values",
[sortable](#collectionsubject_new_sortable)=True,
[element_plural_name](#collectionsubject_new_element_plural_name)="elements",
[format](#collectionsubject_new_format)=False)

Creates a "CollectionSubject" struct.

Method: CollectionSubject.new

Public Attributes:
* `actual`: The wrapped collection.


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

{.params-box}
:[values[¶](#collectionsubject_new_values){.headerlink}]{.span}: []{#collectionsubject_new_values}
  ([`collection`]) the values to assert against.
:[meta[¶](#collectionsubject_new_meta){.headerlink}]{.span}: []{#collectionsubject_new_meta}
  ([`ExpectMeta`]) the metadata about the call chain.
:[container_name[¶](#collectionsubject_new_container_name){.headerlink}]{.span}: []{#collectionsubject_new_container_name}
(_default `"values"`_)   ([`str`]) conceptual name of the container.
:[sortable[¶](#collectionsubject_new_sortable){.headerlink}]{.span}: []{#collectionsubject_new_sortable}
(_default `True`_)   ([`bool`]) True if output should be sorted for display, False if not.
:[element_plural_name[¶](#collectionsubject_new_element_plural_name){.headerlink}]{.span}: []{#collectionsubject_new_element_plural_name}
(_default `"elements"`_)   ([`str`]) the plural word for the values in the container.
:[format[¶](#collectionsubject_new_format){.headerlink}]{.span}: []{#collectionsubject_new_format}
(_default `False`_)   ([`bool`]) True if asserted values should be formatted.

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


{.starlark-object}
## CollectionSubject.not_contains_predicate

{.starlark-signature}
CollectionSubject.not_contains_predicate([matcher](#collectionsubject_not_contains_predicate_matcher))

Asserts that `matcher` matches no values in the collection.

Method: CollectionSubject.not_contains_predicate


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

:[matcher[¶](#collectionsubject_not_contains_predicate_matcher){.headerlink}]{.span}: []{#collectionsubject_not_contains_predicate_matcher}
  [`Matcher`] object (see `matchers` struct).


{.starlark-object}
## CollectionSubject.offset

{.starlark-signature}
CollectionSubject.offset([offset](#collectionsubject_offset_offset),
[factory](#collectionsubject_offset_factory))

Fetches an element from the collection as a subject.

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

:[offset[¶](#collectionsubject_offset_offset){.headerlink}]{.span}: []{#collectionsubject_offset_offset}
  ([`int`]) the offset to fetch
:[factory[¶](#collectionsubject_offset_factory){.headerlink}]{.span}: []{#collectionsubject_offset_factory}
  ([`callable`]). The factory function to use to create
  the subject for the offset's value. It must have the following
  signature: `def factory(value, *, meta)`.

{#collectionsubject_offset_returns}
RETURNS [¶](#collectionsubject_offset_returns){.headerlink}
: Object created by `factory`.


{.starlark-object}
## CollectionSubject.transform

{.starlark-signature}
CollectionSubject.transform([desc](#collectionsubject_transform_desc)=None,
[map_each](#collectionsubject_transform_map_each)=None,
[loop](#collectionsubject_transform_loop)=None,
[filter](#collectionsubject_transform_filter)=None,
[format](#collectionsubject_transform_format)=None)

Transforms a collections's value and returns another CollectionSubject.

This is equivalent to applying a list comprehension over the collection values,
but takes care of propagating context information and wrapping the value
in a `CollectionSubject`.

`transform(map_each=M, loop=L, filter=F)` is equivalent to
`[M(v) for v in L(collection) if F(v)]`.


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

:[desc[¶](#collectionsubject_transform_desc){.headerlink}]{.span}: []{#collectionsubject_transform_desc}
(_default `None`_)   (optional [`str`]) a human-friendly description of the transform
  for use in error messages. Required when a description can't be
  inferred from the other args. The description can be inferred if the
  filter arg is a named function (non-lambda) or Matcher object.
:[map_each[¶](#collectionsubject_transform_map_each){.headerlink}]{.span}: []{#collectionsubject_transform_map_each}
(_default `None`_)   (optional [`callable`]) function to transform an element in
  the collection. It takes one positional arg, the loop's
  current iteration value, and its return value will be the element's
  new value. If not specified, the values from the loop iteration are
  returned unchanged.
:[loop[¶](#collectionsubject_transform_loop){.headerlink}]{.span}: []{#collectionsubject_transform_loop}
(_default `None`_)   (optional [`callable`]) function to produce values from the
  original collection and whose values are iterated over. It takes one
  positional arg, which is the original collection. If not specified,
  the original collection values are iterated over.
:[filter[¶](#collectionsubject_transform_filter){.headerlink}]{.span}: []{#collectionsubject_transform_filter}
(_default `None`_)   (optional [`callable`]) function that decides what values are
  passed onto `map_each` for inclusion in the final result. It takes
  one positional arg, the value to match (which is the current
  iteration value before `map_each` is applied), and returns a bool
  (True if the value should be included in the result, False if it
  should be skipped).
:[format[¶](#collectionsubject_transform_format){.headerlink}]{.span}: []{#collectionsubject_transform_format}
(_default `None`_)   (optional [`bool`]) If asserted values should be formatted. If
  unset, will default to the value of `format` passed while creating
  the original collection subject.

{#collectionsubject_transform_returns}
RETURNS [¶](#collectionsubject_transform_returns){.headerlink}
: [`CollectionSubject`] of the transformed values.


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