Object Matchers

Matchers that inspect objects.

class hamcrest.core.core.isequal.IsEqual(equals)

Bases: BaseMatcher[Any]

Parameters:

equals (Any) –

describe_to(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 (Description) – The description to be built or appended to.

Return type:

None

hamcrest.core.core.isequal.equal_to(obj)

Matches if object is equal to a given object.

Parameters:

obj (Any) – The object to compare against as the expected value.

Return type:

Matcher[Any]

This matcher compares the evaluated object to obj for equality.

class hamcrest.library.object.haslength.HasLength(len_matcher)

Bases: BaseMatcher[Sized]

Parameters:

len_matcher (Matcher[int]) –

describe_mismatch(item, mismatch_description)

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 (Sized) – The item that the Matcher has rejected.

  • mismatch_description (Description) – The description to be built or appended to.

Return type:

None

describe_to(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 (Description) – The description to be built or appended to.

Return type:

None

hamcrest.library.object.haslength.has_length(match)

Matches if len(item) satisfies a given matcher.

Parameters:

match (Union[int, Matcher[int]]) – The matcher to satisfy, or an expected value for equal_to matching.

Return type:

Matcher[Sized]

This matcher invokes the len function on the evaluated object to get its length, passing the result to a given matcher for evaluation.

If the match argument is not a matcher, it is implicitly wrapped in an equal_to matcher to check for :equality.

Examples:

has_length(greater_than(6))
has_length(5)
class hamcrest.library.object.hasstring.HasString(str_matcher)

Bases: BaseMatcher[object]

Parameters:

str_matcher (Matcher[str]) –

describe_to(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 (Description) – The description to be built or appended to.

Return type:

None

hamcrest.library.object.hasstring.has_string(match)

Matches if str(item) satisfies a given matcher.

Parameters:

match – The matcher to satisfy, or an expected value for equal_to matching.

Return type:

Matcher[object]

This matcher invokes the str function on the evaluated object to get its length, passing the result to a given matcher for evaluation. If the match argument is not a matcher, it is implicitly wrapped in an equal_to matcher to check for equality.

Examples:

has_string(starts_with('foo'))
has_string('bar')
class hamcrest.library.object.hasproperty.IsObjectWithProperty(property_name, value_matcher)

Bases: BaseMatcher[object]

Parameters:

  • property_name (str) –

  • value_matcher (Matcher[V]) –

describe_mismatch(item, mismatch_description)

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 (object) – The item that the Matcher has rejected.

  • mismatch_description (Description) – The description to be built or appended to.

Return type:

None

describe_to(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 (Description) – The description to be built or appended to.

Return type:

None

hamcrest.library.object.hasproperty.has_properties(**keys_valuematchers: Union[Matcher[V], V]) → Matcher[Any]
hamcrest.library.object.hasproperty.has_properties(keys_valuematchers: Mapping[str, Union[Matcher[V], V]]) → Matcher[Any]
hamcrest.library.object.hasproperty.has_properties(*keys_valuematchers: Any) → Matcher[Any]

Matches if an object has properties satisfying all of a dictionary of string property names and corresponding value matchers.

Parameters:

matcher_dict – A dictionary mapping keys to associated value matchers, or to expected values for equal_to matching.

Note that the keys must be actual keys, not matchers. Any value argument that is not a matcher is implicitly wrapped in an equal_to matcher to check for equality.

Examples:

has_properties({'foo':equal_to(1), 'bar':equal_to(2)})
has_properties({'foo':1, 'bar':2})

has_properties also accepts a list of keyword arguments:

hamcrest.library.object.hasproperty.has_properties(keyword1=value_matcher1[, keyword2=value_matcher2[, ...]])
Parameters:

  • keyword1 – A keyword to look up.

  • valueMatcher1 – The matcher to satisfy for the value, or an expected value for equal_to matching.

Examples:

has_properties(foo=equal_to(1), bar=equal_to(2))
has_properties(foo=1, bar=2)

Finally, has_properties also accepts a list of alternating keys and their value matchers:

hamcrest.library.object.hasproperty.has_properties(key1, value_matcher1[, ...])
Parameters:

  • key1 – A key (not a matcher) to look up.

  • valueMatcher1 – The matcher to satisfy for the value, or an expected value for equal_to matching.

Examples:

has_properties('foo', equal_to(1), 'bar', equal_to(2))
has_properties('foo', 1, 'bar', 2)
hamcrest.library.object.hasproperty.has_property(name, match=None)

Matches if object has a property with a given name whose value satisfies a given matcher.

Parameters:

  • name (str) – The name of the property.

  • match (Union[None, Matcher[V], V]) – Optional matcher to satisfy.

Return type:

Matcher[object]

This matcher determines if the evaluated object has a property with a given name. If no such property is found, has_property is not satisfied.

If the property is found, its value is passed to a given matcher for evaluation. If the match argument is not a matcher, it is implicitly wrapped in an equal_to matcher to check for equality.

If the match argument is not provided, the anything matcher is used so that has_property is satisfied if a matching property is found.

Examples:

has_property('name', starts_with('J'))
has_property('name', 'Jon')
has_property('name')
class hamcrest.core.core.isinstanceof.IsInstanceOf(expected_type)

Bases: BaseMatcher[object]

Parameters:

expected_type (Type) –

describe_to(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 (Description) – The description to be built or appended to.

Return type:

None

hamcrest.core.core.isinstanceof.instance_of(atype)

Matches if object is an instance of, or inherits from, a given type.

Parameters:

atype (Type) – The type to compare against as the expected type.

Return type:

Matcher[object]

This matcher checks whether the evaluated object is an instance of atype or an instance of any class that inherits from atype.

Example:

instance_of(str)
class hamcrest.core.core.isnone.IsNone

Bases: BaseMatcher[Optional[Any]]

describe_to(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 (Description) – The description to be built or appended to.

Return type:

None

hamcrest.core.core.isnone.none()

Matches if object is None.

Return type:

Matcher[Optional[Any]]

hamcrest.core.core.isnone.not_none()

Matches if object is not None.

Return type:

Matcher[Optional[Any]]

class hamcrest.core.core.issame.IsSame(obj)

Bases: BaseMatcher[T]

Parameters:

obj (T) –

describe_mismatch(item, mismatch_description)

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 (T) – The item that the Matcher has rejected.

  • mismatch_description (Description) – The description to be built or appended to.

Return type:

None

describe_to(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 (Description) – The description to be built or appended to.

Return type:

None

hamcrest.core.core.issame.same_instance(obj)

Matches if evaluated object is the same instance as a given object.

Parameters:

obj (T) – The object to compare against as the expected value.

Return type:

Matcher[T]

This matcher invokes the is identity operator to determine if the evaluated object is the the same object as obj.

class hamcrest.core.core.raises.Raises(expected, pattern=None, matching=None)

Bases: BaseMatcher[Callable[[…], Any]]

Parameters:
describe_match(item, match_description)

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

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

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

Parameters:

  • item – The item that the Matcher has accepted.

  • match_description (Description) – The description to be built or appended to.

Return type:

None

describe_mismatch(item, description)

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.

  • description (Description) –

Return type:

None

describe_to(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 (Description) – The description to be built or appended to.

Return type:

None

hamcrest.core.core.raises.calling(func)

Wrapper for function call that delays the actual execution so that raises matcher can catch any thrown exception.

Parameters:

func (Callable[[...], Any]) – The function or method to be called

Return type:

DeferredCallable

The arguments can be provided with a call to the with_args function on the returned object:

calling(my_method).with_args(arguments, and_='keywords')
hamcrest.core.core.raises.raises(exception, pattern=None, matching=None)

Matches if the called function raised the expected exception.

Parameters:

  • exception (Type[Exception]) – The class of the expected exception

  • pattern – Optional regular expression to match exception message.

  • matching – Optional Hamcrest matchers to apply to the exception.

Return type:

Matcher[Callable[[…], Any]]

Expects the actual to be wrapped by using calling, or a callable taking no arguments. Optional argument pattern should be a string containing a regular expression. If provided, the string representation of the actual exception - e.g. str(actual) - must match pattern.

Examples:

assert_that(calling(int).with_args('q'), raises(TypeError))
assert_that(calling(parse, broken_input), raises(ValueError))
assert_that(
    calling(valid_user, bad_json),
    raises(HTTPError, matching=has_properties(status_code=500)
)