{"id":1864,"library":"pyhamcrest","title":"PyHamcrest","description":"PyHamcrest is a framework for writing matcher objects for Python. It provides a declarative way to define 'match' rules, most commonly used in unit testing to create flexible and precise assertions. It is currently at version 2.1.0 and has a consistent release cadence with several minor and major updates over the years, most recently adding features for async futures.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/hamcrest/PyHamcrest/","tags":["testing","assertions","matchers","unit testing","test framework"],"install":[{"cmd":"pip install pyhamcrest","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.6 or newer.","package":"Python","optional":false}],"imports":[{"symbol":"assert_that","correct":"from hamcrest import assert_that, equal_to"},{"symbol":"anything","correct":"from hamcrest import anything"},{"symbol":"contains_string","correct":"from hamcrest import contains_string"},{"note":"Wildcard import is common in tests for brevity but can lead to name collisions.","symbol":"*","correct":"from hamcrest import *"}],"quickstart":{"code":"from hamcrest import assert_that, equal_to, greater_than\n\nclass MyObject:\n    def __init__(self, value):\n        self.value = value\n\n    def __eq__(self, other):\n        if not isinstance(other, MyObject):\n            return NotImplemented\n        return self.value == other.value\n\ndef test_object_equality():\n    obj1 = MyObject('test')\n    obj2 = MyObject('test')\n    assert_that(obj1, equal_to(obj2))\n    print('Test object_equality passed.')\n\ndef test_number_comparison():\n    number = 10\n    assert_that(number, greater_than(5))\n    print('Test number_comparison passed.')\n\nif __name__ == '__main__':\n    test_object_equality()\n    test_number_comparison()","lang":"python","description":"This quickstart demonstrates basic usage of `assert_that` with `equal_to` for object comparison and `greater_than` for numeric comparison. PyHamcrest matchers provide a more readable and flexible way to express assertions in tests."},"warnings":[{"fix":"Upgrade to Python 3.6+ or pin PyHamcrest to version <1.9.0 for older Python environments.","message":"PyHamcrest dropped formal support for Python 2.x (all versions) and Python 3.x versions older than 3.4 starting with V1.9.0. Attempting to install or run V1.9.0 or later on unsupported Python versions will result in errors.","severity":"breaking","affected_versions":">=1.9.0"},{"fix":"Explicitly use `equal_to()` for value comparisons (e.g., `assert_that(actual, equal_to(expected))` instead of `assert_that(actual, expected)`) to ensure consistent behavior across versions.","message":"In V2.0.0, the `assert_that` function's behavior changed. If a non-boolean value was passed as the matcher argument, it now implicitly wraps it with `equal_to()`. Previously, this might have behaved differently or raised an error depending on the exact context.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Avoid using the `numpy alias`. If your code depends on specific NumPy-related matchers, ensure you are using the correct, explicit imports and patterns as per current documentation.","message":"The `numpy alias` was deprecated in PyHamcrest V2.1.0. While it might still function, its use is discouraged and will be removed in future versions.","severity":"deprecated","affected_versions":"2.1.0"},{"fix":"Use `assert_that(calling(your_function), raises(YourException))`.","message":"When using the `raises()` matcher (e.g., for asserting exceptions) with `pytest`, you must wrap the callable in `calling()` for it to work correctly. Directly passing the callable to `assert_that(callable, raises(Exception))` will fail.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Design custom matchers to be immutable and stateless, or create new instances for each assertion if state management is unavoidable.","message":"Custom matchers should generally be stateless. If you create a custom matcher and intend to reuse a single instance across multiple assertions, ensure that its internal state does not change during the matching process, as this can lead to unexpected test results.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}