https://github.com/mwilliamson/python-precisely Skip to content Sign up * Why GitHub? Features - + Mobile - + Actions - + Codespaces - + Packages - + Security - + Code review - + Project management - + Integrations - + GitHub Sponsors - + Customer stories - + Security - * Team * Enterprise * Explore + Explore GitHub - Learn & contribute + Topics - + Collections - + Trending - + Learning Lab - + Open source guides - Connect with others + The ReadME Project - + Events - + Community forum - + GitHub Education - + GitHub Stars program - * Marketplace * Pricing Plans - + Compare plans - + Contact Sales - + Nonprofit - + Education - [ ] [search-key] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this user All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} mwilliamson / python-precisely * Sponsor Sponsor mwilliamson/python-precisely * Watch 4 * Star 120 * Fork 6 Matcher library for Python BSD-2-Clause License 120 stars 6 forks Star Watch * Code * Issues 1 * Pull requests 1 * Actions * Projects 0 * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Security * Insights master Switch branches/tags [ ] Branches Tags Nothing to show {{ refName }} default View all branches Nothing to show {{ refName }} default View all tags 3 branches 10 tags Go to file Code Clone HTTPS GitHub CLI [https://github.com/m] Use Git or checkout with SVN using the web URL. [gh repo clone mwilli] Work fast with our official CLI. Learn more. * Open with GitHub Desktop * Download ZIP Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching Xcode If nothing happens, download Xcode and try again. Go back Launching Visual Studio If nothing happens, download the GitHub extension for Visual Studio and try again. Go back Latest commit @mwilliamson mwilliamson Replace Travis CI with GitHub Actions ... 9c7fe4d Feb 18, 2021 Replace Travis CI with GitHub Actions 9c7fe4d Git stats * 140 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .github/workflows Replace Travis CI with GitHub Actions Feb 18, 2021 examples Rename to precisely Dec 26, 2016 precisely Remove implementation inheritance Jul 26, 2019 tests Add mapping_includes matcher Jul 25, 2019 .gitignore Initial commit Apr 23, 2016 LICENSE Add LICENSE Mar 24, 2019 README.rst Fix formatting in README Oct 11, 2020 makefile Run pyflakes from virtualenv Apr 20, 2019 setup.cfg Build universal wheels Apr 20, 2019 setup.py Use HTTPS for url in setup.py Oct 11, 2020 test-requirements.txt Update pyflakes to 2.2.0 Oct 10, 2020 tox.ini Add support for Python 3.8 and Python 3.9 Oct 10, 2020 View code README.rst Precisely: better assertions for Python tests Precisely allows you to write precise assertions so you only test the behaviour you're really interested in. This makes it clearer to the reader what the expected behaviour is, and makes tests less brittle. This also allows better error messages to be generated when assertions fail. Inspired by Hamcrest. For instance, suppose we want to make sure that a unique function removes duplicates from a list. We might write a test like so: from precisely import assert_that, contains_exactly def test_unique_removes_duplicates(): result = unique(["a", "a", "b", "a", "b"]) assert_that(result, contains_exactly("a", "b")) The assertion will pass so long as result contains "a" and "b" in any order, but no other items. Unlike, say, assert result == ["a", "b"], our assertion ignores the ordering of elements. This is useful when: * the ordering of the result is non-determistic, such as when using set. * the ordering isn't specified in the contract of unique. If we assert a particular ordering, then we'd be testing the implementation rather than the contract. * the ordering is specified in the contract of unique, but the ordering is tested in a separate test case. When the assertion fails, rather than just stating the two values weren't equal, the error message will describe the failure in more detail. For instance, if unique has the value ["a", "a", "b"], we'd get the failure message: Expected: iterable containing in any order: * 'a' * 'b' but: had extra elements: * 'a' Installation pip install precisely API Use assert_that(value, matcher) to assert that a value satisfies a matcher. Many matchers are composed of other matchers. If they are given a value instead of a matcher, then that value is wrapped in equal_to(). For instance, has_attrs(name="bob") is equivalent to has_attrs(name= equal_to("bob")). * equal_to(value): matches a value if it is equal to value using = =. * has_attrs(**kwargs): matches a value if it has the specified attributes. For instance: assert_that(result, has_attrs(id=is_instance(int), name="bob")) * has_attr(attribute_name, matcher): matches a value if it has the specified attribute. Using has_attrs is generally considered more idiomatic when the attribute name is constant. For instance, instead of: assert_that(result, has_attr("id", is_instance(int))) use: assert_that(result, has_attrs(id=is_instance(int))) * contains_exactly(*args): matches an iterable if it has the same elements in any order. For instance: assert_that(result, contains_exactly("a", "b")) # Matches ["a", "b"] and ["b", "a"], # but not ["a", "a", "b"] nor ["a"] nor ["a", "b", "c"] * is_sequence(*args): matches an iterable if it has the same elements in the same order. For instance: assert_that(result, is_sequence("a", "b")) # Matches ["a", "b"] # but not ["b", "a"] nor ["a", "b", "c"] nor ["c", "a", "b"] * includes(*args): matches an iterable if it includes all of the elements. For instance: assert_that(result, includes("a", "b")) # Matches ["a", "b"], ["b", "a"] and ["a", "c", "b"] # but not ["a", "c"] nor ["a"] assert_that(result, includes("a", "a")) # Matches ["a", "a"] and ["a", "a", "a"] # but not ["a"] * all_elements(matcher): matches an iterable if every element matches matcher. For instance: assert_that(result, all_elements(equal_to(42))) # Matches [42], [42, 42, 42] and [] # but not [42, 43] * is_mapping(matchers): matches a mapping, such as a dict, if it has the same keys with matching values. An error will be raised if the mapping is missing any keys, or has any extra keys. For instance: assert_that(result, is_mapping({ "a": equal_to(1), "b": equal_to(4), })) * mapping_includes(matchers): matches a mapping, such as a dict, if it has the same keys with matching values. An error will be raised if the mapping is missing any keys, but extra keys are allowed. For instance: assert_that(result, mapping_includes({ "a": equal_to(1), "b": equal_to(4), })) # Matches {"a": 1, "b": 4} and {"a": 1, "b": 4, "c": 5} # but not {"a": 1} nor {"a": 1, "b": 5} * anything: matches all values. * is_instance(type): matches any value where isinstance(value, type). * all_of(*matchers): matchers a value if all sub-matchers match. For instance: assert_that(result, all_of( is_instance(User), has_attrs(name="bob"), )) * any_of(*matchers): matchers a value if any sub-matcher matches. For instance: assert_that(result, any_of( equal_to("x=1, y=2"), equal_to("y=2, x=1"), )) * not_(matcher): negates a matcher. For instance: assert_that(result, not_(equal_to("hello"))) * starts_with(prefix): matches a string if it starts with prefix. * contains_string(substring): matches a string if it contains substring. * greater_than(value): matches values greater than value. * greater_than_or_equal_to(value): matches values greater than or equal to value. * less_than(value): matches values less than value. * less_than_or_equal_to(value): matches values less than or equal to value. * close_to(value, delta): matches values close to value within a tolerance of +/- delta. * has_feature(name, extract, matcher): matches value if extract (value) matches matcher. For instance: assert_that(result, has_feature("len", len, equal_to(2))) For clarity, it often helps to extract the use of has_feature into its own function: def has_len(matcher): return has_feature("len", len, matcher) assert_that(result, has_len(equal_to(2))) * raises(matcher): matches value if value() raises an exception matched by matcher. For instance: assert_that(lambda: func("arg"), raises(is_instance(ValueError))) Alternatives PyHamcrest is another Python implemention of matchers. I prefer the error messages that this project produces, but feel free to judge for yourself: # Precisely from precisely import assert_that, is_sequence, has_attrs assert_that( [ User("bob", "jim@example.com"), User("jim", "bob@example.com"), ], is_sequence( has_attrs(username="bob", email_address="bob@example.com"), has_attrs(username="jim", email_address="jim@example.com"), ) ) # Expected: iterable containing in order: # 0: attributes: # * username: 'bob' # * email_address: 'bob@example.com' # 1: attributes: # * username: 'jim' # * email_address: 'jim@example.com' # but: element at index 0 mismatched: # * attribute email_address: was 'jim@example.com' # Hamcrest from hamcrest import assert_that, contains, has_properties assert_that( [ User("bob", "jim@example.com"), User("jim", "bob@example.com"), ], contains( has_properties(username="bob", email_address="bob@example.com"), has_properties(username="jim", email_address="jim@example.com"), ) ) # Hamcrest error: # Expected: a sequence containing [(an object with a property 'username' matching 'bob' and an object with a property 'email_address' matching 'bob@example.com'), (an object with a property 'username' matching 'jim' and an object with a property 'email_address' matching 'jim@example.com')] # but: item 0: an object with a property 'email_address' matching 'bob@example.com' property 'email_address' was 'jim@example.com' About Matcher library for Python Resources Readme License BSD-2-Clause License Releases 10 tags Sponsor this project * liberapay liberapay.com/mwilliamson * ko_fi ko-fi.com/mwilliamson Packages 0 No packages published Used by 12 * @threfo * @bigpiventures * @healx * @huyuben11 * @mwilliamson * @danodonovan * @mwilliamson * @mwilliamson + 4 Contributors 4 * @mwilliamson mwilliamson Michael Williamson * @danodonovan danodonovan Dan O'Donovan * @ErwinJunge ErwinJunge Erwin Junge * @mwilliamson-healx mwilliamson-healx Michael Williamson Languages * Python 98.8% * Makefile 1.2% * (c) 2021 GitHub, Inc. * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.