Object Matchers

Matchers that inspect objects.

equal_to

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

Bases: hamcrest.core.base_matcher.BaseMatcher[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 (hamcrest.core.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

hamcrest.core.matcher.Matcher[Any]

This matcher compares the evaluated object to obj for equality.

has_length

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

Bases: hamcrest.core.base_matcher.BaseMatcher[collections.abc.Sized]

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
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 (hamcrest.core.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, hamcrest.core.matcher.Matcher[int]]) – The matcher to satisfy, or an expected value for equal_to matching.

Return type

hamcrest.core.matcher.Matcher[collections.abc.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)

has_string

class hamcrest.library.object.hasstring.HasString(str_matcher)

Bases: hamcrest.core.base_matcher.BaseMatcher[object]

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 (hamcrest.core.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

hamcrest.core.matcher.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')

has_properties/has_property

class hamcrest.library.object.hasproperty.IsObjectWithProperty(property_name, value_matcher)

Bases: hamcrest.core.base_matcher.BaseMatcher[object]

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

Return type

None

hamcrest.library.object.hasproperty.has_properties(**keys_valuematchers: Union[hamcrest.core.matcher.Matcher[hamcrest.library.object.hasproperty.V], hamcrest.library.object.hasproperty.V]) hamcrest.core.matcher.Matcher[Any]
hamcrest.library.object.hasproperty.has_properties(keys_valuematchers: Mapping[str, Union[hamcrest.core.matcher.Matcher[hamcrest.library.object.hasproperty.V], hamcrest.library.object.hasproperty.V]]) hamcrest.core.matcher.Matcher[Any]
hamcrest.library.object.hasproperty.has_properties(*keys_valuematchers: Any) hamcrest.core.matcher.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, hamcrest.core.matcher.Matcher[hamcrest.library.object.hasproperty.V], hamcrest.library.object.hasproperty.V]) – Optional matcher to satisfy.

Return type

hamcrest.core.matcher.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')

instance_of

class hamcrest.core.core.isinstanceof.IsInstanceOf(expected_type)

Bases: hamcrest.core.base_matcher.BaseMatcher[object]

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 (hamcrest.core.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

hamcrest.core.matcher.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)

none, not_none

class hamcrest.core.core.isnone.IsNone(*args, **kwds)

Bases: hamcrest.core.base_matcher.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 (hamcrest.core.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

hamcrest.core.matcher.Matcher[Optional[Any]]

hamcrest.core.core.isnone.not_none()

Matches if object is not None.

Return type

hamcrest.core.matcher.Matcher[Optional[Any]]

same_instance

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

Bases: hamcrest.core.base_matcher.BaseMatcher[hamcrest.core.core.issame.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
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 (hamcrest.core.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 (hamcrest.core.core.issame.T) – The object to compare against as the expected value.

Return type

hamcrest.core.matcher.Matcher[hamcrest.core.core.issame.T]

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

calling, raises

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

Bases: hamcrest.core.base_matcher.BaseMatcher[Callable[[…], Any]]

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
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
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 (hamcrest.core.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

hamcrest.core.core.raises.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

hamcrest.core.matcher.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)
)