Object Matchers¶

Matchers that inspect objects.

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

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

Parameters: equals (Any) –
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.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.

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

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

Parameters: len_matcher (hamcrest.core.matcher.Matcher[int]) –
Return type: None

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

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

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

Parameters: str_matcher (hamcrest.core.matcher.Matcher[str]) –
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.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')

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

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

Parameters

property_name (str) –
value_matcher (hamcrest.core.matcher.Matcher[hamcrest.library.object.hasproperty.V]) –

Return type

None

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

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

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

Parameters: expected_type (Type) –
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.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)

class hamcrest.core.core.isnone.IsNone¶

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]]

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

Bases: hamcrest.core.base_matcher.BaseMatcher[hamcrest.core.core.issame.T]

Parameters: obj (hamcrest.core.core.issame.T) –
Return type: None

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

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

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

Parameters

expected (Type[Exception]) –
pattern (Optional[str]) –
matching (Optional[hamcrest.core.matcher.Matcher]) –

Return type

None

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

Object Matchers¶

PyHamcrest

Navigation

Related Topics