Examples of usage

The “brunns.matchers” package

The “brunns.matchers.bytestring” module

Code under test:

def my_function(a_string: str) -> bytes:
    return a_string.upper().encode("utf-8")

Test:

from hamcrest import assert_that
from brunns.matchers.bytestring import contains_bytestring

def test_bytestrings():
    # Given
    a_string = "hello"

    # When
    actual = my_function(a_string)

    # Then
    assert_that(actual, contains_bytestring(b"ELL"))

The “brunns.matchers.data” module

import json

from brunns.matchers.data import json_matching
from hamcrest import assert_that, contains_exactly, not_


def make_data() -> str:
    return json.dumps([1, 2, 3])


def test_json():
    # Given
    actual = make_data()

    # Then
    assert_that(actual, json_matching([1, 2, 3]))
    assert_that(actual, json_matching(contains_exactly(1, 2, 3)))
    assert_that(actual, not_(json_matching([1, 2, 5])))

The “brunns.matchers.datetime” module

import datetime

from brunns.matchers.datetime import is_weekday
from hamcrest import assert_that, not_


def test_weekday():
    # 1968-07-19 is a Friday; 1968-07-21 is a Sunday.
    assert_that(datetime.date(1968, 7, 19), is_weekday())
    assert_that(datetime.date(1968, 7, 21), not_(is_weekday()))

The “brunns.matchers.dbapi” module

import sqlite3

from brunns.matchers.dbapi import has_table, has_table_with_rows
from hamcrest import assert_that, contains_inanyorder, has_properties, not_


def make_db() -> sqlite3.Connection:
    db = sqlite3.connect(":memory:")
    db.execute("CREATE TABLE sausages (kind VARCHAR, rating INT);")
    for kind, rating in (("cumberland", 10), ("vegetarian", 0), ("lincolnshire", 9)):
        db.execute("INSERT INTO sausages VALUES (?, ?);", (kind, rating))
    db.commit()
    return db


def test_db():
    # Given
    db = make_db()

    # Then
    assert_that(db, has_table("sausages"))
    assert_that(db, not_(has_table("bacon")))
    assert_that(
        db,
        has_table_with_rows(
            "sausages",
            contains_inanyorder(
                has_properties(kind="cumberland"),
                has_properties(kind="lincolnshire"),
                has_properties(kind="vegetarian"),
            ),
        ),
    )

The “brunns.matchers.html” module

The HTML matchers require the html extra (pip install brunns-matchers[html]).

from brunns.matchers.html import (
    has_attributes,
    has_class,
    has_header_row,
    has_id,
    has_id_tag,
    has_image,
    has_link,
    has_named_tag,
    has_row,
    has_table,
    has_title,
    tag_has_string,
)
from brunns.matchers.url import is_url
from bs4 import BeautifulSoup
from hamcrest import assert_that, contains_exactly, has_entries, not_


HTML = """\
<html>
    <head>
        <title>sausages</title>
    </head>
    <body>
        <h1 class="bacon egg">chips</h1>
        <a id="a-link" class="link-me-baby" href="https://brunni.ng">A link</a>
        <div id="fish" class="banana">some text</div>
        <img src="https://brunni.ng/some.png"/>
        <table>
            <thead>
                <tr><th>apples</th><th>oranges</th></tr>
            </thead>
            <tbody>
                <tr><td>foo</td><td>bar</td></tr>
                <tr class="bazz"><td>fizz</td><td>buzz</td></tr>
            </tbody>
        </table>
    </body>
</html>
"""


def test_html():
    # Tags by name, by id, and links / images.
    assert_that(HTML, has_title("sausages"))
    assert_that(HTML, not_(has_title("bacon")))
    assert_that(HTML, has_named_tag("h1", "chips"))
    assert_that(HTML, has_named_tag("h1", has_class("bacon")))
    assert_that(HTML, has_id_tag("fish", has_class("banana")))
    assert_that(HTML, has_named_tag("div", has_id("fish")))
    assert_that(HTML, has_named_tag("div", has_attributes(has_entries(id="fish"))))
    assert_that(HTML, has_link(href=is_url().with_host("brunni.ng")))
    assert_that(HTML, has_image(src="https://brunni.ng/some.png"))

    # Tables, rows, and header rows.
    assert_that(HTML, has_table(has_row(contains_exactly(tag_has_string("foo"), tag_has_string("bar")))))

    table = BeautifulSoup(HTML, "html.parser").table
    assert_that(
        table,
        has_row(
            index_matches=1,
            row_matches=has_class("bazz"),
            cells_match=contains_exactly(tag_has_string("fizz"), tag_has_string("buzz")),
        ),
    )
    assert_that(table, has_header_row(contains_exactly(tag_has_string("apples"), tag_has_string("oranges"))))

The “brunns.matchers.matcher” module

These matchers test other matchers – useful when writing tests for your own custom matchers.

from brunns.matchers.matcher import matches, matches_with, mismatches, mismatches_with
from hamcrest import assert_that, contains_string


def test_matchers():
    matcher = contains_string("Banana")

    # matches / mismatches: did the matcher accept / reject the value?
    assert_that(matcher, matches("Banana"))
    assert_that(matcher, mismatches("Apple"))

    # The *_with variants also describe the text reported on match / mismatch.
    assert_that(matcher, matches_with("Banana", "was 'Banana'"))
    assert_that(matcher, mismatches_with("Apple", "was 'Apple'"))

The “brunns.matchers.meta” module

Subclassing BaseAutoMatcher with a domain type generates with_<field>() / and_<field>() builders for every annotated field, so you can build a fluent matcher for a dataclass or pydantic model.

from dataclasses import dataclass

from brunns.matchers.meta import BaseAutoMatcher
from hamcrest import assert_that, not_, starts_with


@dataclass
class Status:
    id: int
    code: str
    reason: str | None = None


class StatusMatcher(BaseAutoMatcher[Status]):
    pass


def test_meta():
    status = Status(id=99, code="ACTIVE")

    assert_that(status, StatusMatcher().with_code(starts_with("ACT")).and_reason(None))
    assert_that(status, not_(StatusMatcher().with_id(42)))

The “brunns.matchers.mock” module

from brunns.matchers.mock import call_has_arg, call_has_args, has_call
from hamcrest import assert_that, contains_string, not_
from unittest import mock


def test_mocks():
    m = mock.MagicMock()
    m("first", "second", "third", key="forth")
    call = m.mock_calls[0]

    # call_has_arg / call_has_args inspect a single recorded call.
    assert_that(call, call_has_arg(1, "second"))
    assert_that(call, call_has_arg(1, contains_string("eco")))      # "second" contains "eco"
    assert_that(call, call_has_args("first", "second", "third", key="forth"))
    assert_that(call, not_(call_has_args("first", "second", "third", key="banana")))

    # has_call checks whether a mock was ever called a particular way.
    method = m.m
    method("first")
    assert_that(method, has_call(call_has_args("first")))

The “brunns.matchers.object” module

from brunns.matchers.object import (
    between,
    false,
    has_identical_properties_to,
    has_repr,
    true,
)
from hamcrest import assert_that, contains_string, not_


class Point:
    def __init__(self, x: int, y: int) -> None:
        self.x = x
        self.y = y


def test_object():
    # repr() of the object.
    assert_that([1, "2"], has_repr(contains_string("[1, '2']")))

    # Truthiness / falsiness.
    assert_that([1], true())
    assert_that([], false())

    # Ranges (inclusive by default; pass *_inclusive=False to exclude an endpoint).
    assert_that(2, between(1, 3))
    assert_that(1, not_(between(1, 3, lower_inclusive=False)))

    # Structural comparison of an object's public attributes / properties.
    assert_that(Point(1, 2), has_identical_properties_to(Point(1, 2)))

The “brunns.matchers.path” module

from brunns.matchers.path import is_path
from hamcrest import assert_that, contains_exactly, equal_to, not_
from pathlib import Path


def test_path():
    path = Path("/usr/bin/python3.tar.gz")

    assert_that(
        path,
        is_path()
        .with_name("python3.tar.gz")
        .and_stem("python3.tar")
        .and_suffix(".gz")
        .and_suffixes(contains_exactly(".tar", ".gz"))
        .and_parts(contains_exactly("/", "usr", "bin", "python3.tar.gz"))
        .and_parent(equal_to(Path("/usr/bin")))
        .and_root("/"),
    )
    assert_that(path, not_(is_path().with_name("python2.zip")))

The “brunns.matchers.response” module

The response matchers duck-type a requests.Response / httpx response, so no extra is needed as long as one of those libraries is available. redirects_to uses the url matcher, so install the url extra.

import httpx

from brunns.matchers.response import is_response, redirects_to
from brunns.matchers.url import is_url
from hamcrest import assert_that


def test_response():
    # is_response() matches a response, refined with builders.
    response = httpx.get("https://httpbin.org/status/345", timeout=5)
    assert_that(response, is_response().with_status_code(345))

    # redirects_to() checks a redirecting response's Location header.
    redirect = httpx.get(
        "https://httpb.in/redirect-to?url=https://httpbin.org/sausages",
        follow_redirects=False,
    )
    assert_that(redirect, redirects_to(is_url().with_path("/sausages")))

The “brunns.matchers.rss” module

The RSS matchers require the rss extra (pip install brunns-matchers[rss]).

import feedparser

from brunns.matchers.rss import is_rss_category, is_rss_entry, is_rss_feed
from brunns.matchers.url import is_url
from hamcrest import assert_that, contains_inanyorder
from yarl import URL


RSS = """\
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
    <channel>
        <title>Test channel</title>
        <link>https://example.com</link>
        <item>
            <title>An article</title>
            <link>https://example.com/article</link>
            <category term="Python" domain="https://example.com/category"/>
        </item>
    </channel>
</rss>
"""


def test_rss():
    # is_rss_feed() matches a feed parsed from a string or URL.
    assert_that(
        RSS,
        is_rss_feed()
        .with_title("Test channel")
        .and_link(URL("https://example.com")),
    )
    assert_that(
        RSS,
        is_rss_feed().with_entries(contains_inanyorder(is_rss_entry().with_title("An article"))),
    )

    # is_rss_entry() / is_rss_category() match a single entry and its categories.
    entry = feedparser.parse(RSS).entries[0]
    assert_that(
        entry,
        is_rss_entry()
        .with_title("An article")
        .and_link(URL("https://example.com/article"))
        .and_categories(
            contains_inanyorder(is_rss_category().with_text("Python")),
        ),
    )

The “brunns.matchers.scripttest” module

The scripttest matchers duck-type a scripttest.ProcResult produced by scripttest.TestFileEnvironment.run().

from brunns.matchers.scripttest import is_proc_result
from hamcrest import assert_that, contains_exactly, contains_string


def test_proc_result(test_env):
    result = test_env.run("python", "-c", "print('hello world')", expect_error=False)

    assert_that(
        result,
        is_proc_result()
        .with_returncode(0)
        .and_stdout(contains_string("hello world"))
        .and_stderr(""),
    )
    assert_that(
        result,
        is_proc_result().with_args(contains_exactly("python", "-c", "print('hello world')")),
    )

The “brunns.matchers.smtp” module

import email.message

from brunns.matchers.smtp import is_email
from hamcrest import assert_that, not_


def make_message() -> str:
    message = email.message.Message()
    message["To"] = "simon <simon@brunni.ng>"
    message["From"] = "fred <fred@beardy.dev>"
    message["Subject"] = "chips"
    message.set_payload("bananas")
    return message.as_string()


def test_email():
    # Given
    message = make_message()

    # Then
    assert_that(message, is_email().with_to_name("simon"))
    assert_that(message, not_(is_email().with_subject("bacon")))
    assert_that(
        message,
        is_email()
        .with_from_name("fred")
        .and_from_address("fred@beardy.dev")
        .and_subject("chips")
        .and_body_text("bananas"),
    )

The “brunns.matchers.url” module

The url matchers require the url extra (pip install brunns-matchers[url]).

from brunns.matchers.url import is_url
from hamcrest import assert_that, contains_exactly, has_entries, not_


URL = "https://username:password@brunni.ng:1234/path1/path2/path3?key1=value1&key2=value2#fragment"


def test_url():
    assert_that(URL, is_url().with_scheme("https"))
    assert_that(URL, is_url().with_host("brunni.ng"))
    assert_that(URL, not_(is_url().with_host("bacon.co")))
    assert_that(URL, is_url().with_path_segments(contains_exactly("path1", "path2", "path3")))
    assert_that(URL, is_url().with_query(has_entries(key1="value1", key2="value2")))
    assert_that(URL, is_url().with_fragment("fragment"))
    assert_that(
        URL,
        is_url()
        .with_scheme("https")
        .and_username("username")
        .and_password("password")
        .and_port(1234),
    )

The “brunns.matchers.werkzeug” module

The werkzeug matchers duck-type a werkzeug.test.TestResponse (e.g. from Flask’s test client), so any object exposing the same attributes works. As with the project’s own tests, the example below stubs one with mockito.mock(). redirects_to uses the url matcher, so install the url extra.

from brunns.matchers.url import is_url
from brunns.matchers.werkzeug import is_werkzeug_response, redirects_to
from hamcrest import assert_that, has_entries, not_
from mockito import mock


def test_werkzeug():
    response = mock(
        {
            "status_code": 200,
            "text": "sausages",
            "mimetype": "text/xml",
            "json": {"a": "b"},
            "headers": {"key": "value"},
        },
    )

    assert_that(response, is_werkzeug_response().with_status_code(200).and_text("sausages"))
    assert_that(response, is_werkzeug_response().with_mimetype("text/xml"))
    assert_that(response, is_werkzeug_response().with_json(has_entries(a="b")))
    assert_that(response, is_werkzeug_response().with_headers(has_entries(key="value")))
    assert_that(response, not_(is_werkzeug_response().with_status_code(404)))

    # redirects_to() checks a redirecting response's Location header.
    redirect = mock({"status_code": 301, "headers": {"Location": "https://brunni.ng/sausages"}})
    assert_that(redirect, redirects_to(is_url().with_path("/sausages")))