Decorator Matchers¶

Matchers that decorate other matchers for better expression.

described_as¶

class hamcrest.core.core.described_as.DescribedAs(description_template: str, matcher: hamcrest.core.matcher.Matcher[typing.Any][Any], *values)¶

Bases: hamcrest.core.base_matcher.BaseMatcher

describe_mismatch(item: Any, mismatch_description: hamcrest.core.description.Description) → None¶

Generates a description of why the matcher has not accepted the item.

The description will be part of a larger description of why a matching failed, so it should be concise.

This method assumes that matches(item) is False, but will not check this.

Parameters:	item – The item that the `Matcher` has rejected. mismatch_description – The description to be built or appended to.

describe_to(description: hamcrest.core.description.Description) → None¶

Generates a description of the object.

The description may be part of a description of a larger object of which this is just a component, so it should be worded appropriately.

Parameters:	description – The description to be built or appended to.

matches(item: Any, mismatch_description: Optional[hamcrest.core.description.Description] = None) → bool¶

Evaluates the matcher for argument item.

If a mismatch is detected and argument mismatch_description is provided, it will generate a description of why the matcher has not accepted the item.

Parameters:	item – The object against which the matcher is evaluated. mismatch_description –
Returns:	`True` if `item` matches, otherwise `False`.

hamcrest.core.core.described_as.described_as(description, matcher[, value1[, ...]])¶

Adds custom failure description to a given matcher.

Parameters:	description – Overrides the matcher’s description. matcher – The matcher to satisfy. value1,.. – Optional comma-separated list of substitution values.

The description may contain substitution placeholders %0, %1, etc. These will be replaced by any values that follow the matcher.

is_¶

class hamcrest.core.core.is_.Is(matcher: hamcrest.core.matcher.Matcher[~T][T])¶

Bases: hamcrest.core.base_matcher.BaseMatcher

describe_mismatch(item: T, mismatch_description: hamcrest.core.description.Description) → None¶

Generates a description of why the matcher has not accepted the item.

The description will be part of a larger description of why a matching failed, so it should be concise.

This method assumes that matches(item) is False, but will not check this.

Parameters:	item – The item that the `Matcher` has rejected. mismatch_description – The description to be built or appended to.

describe_to(description: hamcrest.core.description.Description)¶

Generates a description of the object.

The description may be part of a description of a larger object of which this is just a component, so it should be worded appropriately.

Parameters:	description – The description to be built or appended to.

matches(item: T, mismatch_description: Optional[hamcrest.core.description.Description] = None) → bool¶

Evaluates the matcher for argument item.

If a mismatch is detected and argument mismatch_description is provided, it will generate a description of why the matcher has not accepted the item.

Parameters:	item – The object against which the matcher is evaluated. mismatch_description –
Returns:	`True` if `item` matches, otherwise `False`.

hamcrest.core.core.is_.is_(x)¶

Decorates another matcher, or provides shortcuts to the frequently used is(equal_to(x)) and is(instance_of(x)).

Parameters:	x – The matcher to satisfy, or a type for `instance_of` matching, or an expected value for `equal_to` matching.

This matcher compares the evaluated object to the given matcher.

Note

PyHamcrest’s is_ matcher is unrelated to Python’s is operator. The matcher for object identity is same_instance.

If the x argument is a matcher, its behavior is retained, but the test may be more expressive. For example:

assert_that(value, less_than(5))
assert_that(value, is_(less_than(5)))

If the x argument is a type, it is wrapped in an instance_of matcher. This makes the following statements equivalent:

assert_that(cheese, instance_of(Cheddar))
assert_that(cheese, is_(instance_of(Cheddar)))
assert_that(cheese, is_(Cheddar))

Otherwise, if the x argument is not a matcher, it is wrapped in an equal_to matcher. This makes the following statements equivalent:

assert_that(cheese, equal_to(smelly))
assert_that(cheese, is_(equal_to(smelly)))
assert_that(cheese, is_(smelly))

Choose the style that makes your expression most readable. This will vary depending on context.