API Reference¶

The “brunns.matchers” package¶

The “brunns.matchers.bytestring” module¶

class brunns.matchers.bytestring.ContainsBytestring(bytestring)[source]¶

Matches if object is a bytestring containing a given bytestring.

Parameters:: bytestring (bytes) – The string to search for.

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

brunns.matchers.bytestring.contains_bytestring(bytestring)[source]¶

Matches if object is a bytestring containing a given bytestring.

Parameters:: bytestring (bytes) – The string to search for.
Return type:: ContainsBytestring

The “brunns.matchers.data” module¶

class brunns.matchers.data.JsonMatching(matcher)[source]¶

Matches string containing JSON data.

Parameters:: matcher (Any | Matcher[Any]) – Value to match against deserialised JSON.

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(json_string, description)[source]¶

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.

Return type:

None

brunns.matchers.data.json_matching(matcher)[source]¶

Matches string containing JSON data.

Parameters:: matcher (Matcher[Any] | Any) – Value to match against deserialised JSON.
Return type:: JsonMatching

The “brunns.matchers.datetime” module¶

brunns.matchers.datetime.is_weekday()[source]¶

Match if date is a weekday.

Return type:: Matcher[date]

class brunns.matchers.datetime.HasWeekday(day)[source]¶

Match if date has matching day of the week.

Parameters:: day (int | Matcher[int]) – Day of week, with 0 being Monday, 1 being Tuesday, and so on.

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(actual, description)[source]¶

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.

Return type:

None

The “brunns.matchers.dbapi” module¶

class brunns.matchers.dbapi.Cursor(*args, **kwargs)[source]¶

class brunns.matchers.dbapi.Connection(*args, **kwargs)[source]¶

class brunns.matchers.dbapi.SelectReturnsRowsMatching(select, row_matcher)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(conn, mismatch_description)[source]¶

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

Return type:

None

brunns.matchers.dbapi.has_table(table)[source]¶

Matches if database has table with name.

Parameters:: table (str) – Table name.
Return type:: Matcher[Connection]

brunns.matchers.dbapi.has_table_with_rows(table, row_matcher)[source]¶

Matches if database has table with rows matching.

Parameters:

table (str) – Table name.
row_matcher (Matcher[list[Any]]) – Row matchers.

Return type:

Matcher[Connection]

The “brunns.matchers.html” module¶

class brunns.matchers.html.HtmlWithTag(tag_matcher, name=None, id_=None)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(actual, mismatch_description)[source]¶

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

Return type:

None

class brunns.matchers.html.TagWith(name=<IsAnything(ANYTHING)>, string=<IsAnything(ANYTHING)>, clazz=<IsAnything(ANYTHING)>, attributes=<IsAnything(ANYTHING)>)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

class brunns.matchers.html.HtmlHasTable(table_matcher, id_=<IsAnything(ANYTHING)>)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

class brunns.matchers.html.TableHasRow(row_matcher=<IsAnything(ANYTHING)>, cells_matcher=<IsAnything(ANYTHING)>, index_matcher=<IsAnything(ANYTHING)>, *, header_row=False)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(table, mismatch_description)[source]¶

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

Return type:

None

brunns.matchers.html.has_title(title)[source]¶

Matches HTML containing a <title> tag with the specified text content.

Parameters:: title (str | Matcher[str]) – The string content or a matcher for the content of the title tag.
Return type:: HtmlWithTag

brunns.matchers.html.has_named_tag(name, matcher)[source]¶

Matches HTML containing a tag with a specific name that satisfies a matcher.

Parameters:

name – The HTML tag name to find (e.g., ‘div’, ‘span’).
matcher – A matcher to apply to the found tag(s).

Return type:

HtmlWithTag

brunns.matchers.html.has_id_tag(id_, matcher)[source]¶

Matches HTML containing a tag with a specific ‘id’ attribute that satisfies a matcher.

Parameters:

id – The HTML id attribute to find.
matcher – A matcher to apply to the found tag(s).

Return type:

HtmlWithTag

brunns.matchers.html.tag_has_string(matcher)[source]¶

Matches a BeautifulSoup Tag if its text content matches the given criteria.

Parameters:: matcher (str | Matcher[str]) – A string or string matcher to validate against the tag’s content.
Return type:: TagWith

brunns.matchers.html.has_class(clazz)[source]¶

Matches a BeautifulSoup Tag if it possesses the specified CSS class.

Parameters:: clazz (str | Matcher[str]) – A string or string matcher to find within the tag’s ‘class’ attribute list.
Return type:: TagWith

brunns.matchers.html.has_table(matcher, id_=<IsAnything(ANYTHING)>)[source]¶

Matches HTML containing a <table> element satisfying the given table matcher.

Parameters:

matcher – A matcher to apply to the table Tag.
id – Optional matcher or string for the table’s ‘id’ attribute.

Return type:

HtmlHasTable

brunns.matchers.html.has_row(row_matches=<IsAnything(ANYTHING)>, cells_match=<IsAnything(ANYTHING)>, index_matches=<IsAnything(ANYTHING)>, *, header_row=False)[source]¶

Matches a table Tag if it contains a row satisfying the specified criteria.

Parameters:

row_matches – Matcher for the <tr> Tag itself.
cells_match – Matcher for the sequence of cells (<td>) within the row.
index_matches – Matcher for the row’s index within the table.
header_row – If True, looks for <th> cells instead of <td>.

Return type:

TableHasRow

brunns.matchers.html.has_header_row(cells_matcher=<IsAnything(ANYTHING)>, row_matcher=<IsAnything(ANYTHING)>)[source]¶

Matches a table Tag if it contains a header row satisfying the specified criteria.

This is a convenience wrapper around has_row with header_row=True.

Parameters:

cells_matcher – Matcher for the sequence of header cells (<th>) within the row.
row_matcher – Matcher for the <tr> Tag itself.

Return type:

TableHasRow

brunns.matchers.html.has_id(id_)[source]¶

Matches a BeautifulSoup Tag if it has the specified element ID.

Parameters:: id – The string ID or a matcher for the ID.
Return type:: TagWith

brunns.matchers.html.has_attributes(matcher)[source]¶

Matches a BeautifulSoup Tag if its attributes dictionary matches the provided matcher.

Parameters:: matcher (Mapping[str, str | Matcher[str]] | Matcher[Mapping[str, str | Matcher[str]]]) – A dictionary or matcher to validate the tag’s attributes.
Return type:: TagWith

brunns.matchers.html.has_link(id_=<IsAnything(ANYTHING)>, clazz=<IsAnything(ANYTHING)>, href=<IsAnything(ANYTHING)>)[source]¶

Matches HTML containing an anchor (<a>) tag with specific attributes.

Parameters:

id – Matcher or string for the ‘id’ attribute.
clazz (str | Matcher[str]) – Matcher or string for the ‘class’ attribute.
href (str | Matcher[str]) – Matcher or string for the ‘href’ attribute.

Return type:

HtmlWithTag

brunns.matchers.html.has_image(id_=<IsAnything(ANYTHING)>, clazz=<IsAnything(ANYTHING)>, src=<IsAnything(ANYTHING)>)[source]¶

Matches HTML containing an image (<img>) tag with specific attributes.

Parameters:

id – Matcher or string for the ‘id’ attribute.
clazz (str | Matcher[str]) – Matcher or string for the ‘class’ attribute.
src (str | Matcher[str]) – Matcher or string for the ‘src’ attribute.

Return type:

HtmlWithTag

The “brunns.matchers.matcher” module¶

class brunns.matchers.matcher.MismatchesWith(value_not_to_match, expected_message)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(matcher_under_test, description)[source]¶

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.

Return type:

None

brunns.matchers.matcher.mismatches_with(value_not_to_match, expected_message)[source]¶

Matches if the matcher under test fails to match the value, and provides the expected mismatch message.

This is useful for testing custom matchers to ensure they reject invalid values and provide helpful diagnostics.

Parameters:

value_not_to_match (Any) – The value that the matcher under test should reject.
expected_message (str | Matcher[str]) – The expected string (or matcher for the string) generated by the matcher’s describe_mismatch method.

Return type:

MismatchesWith

brunns.matchers.matcher.mismatches(value_not_to_match)[source]¶

Matches if the matcher under test fails to match the value, regardless of the message.

Parameters:: value_not_to_match (Any) – The value that the matcher under test should reject.
Return type:: MismatchesWith

class brunns.matchers.matcher.MatchesWith(value_to_match, expected_message)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(matcher_under_test, description)[source]¶

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.

Return type:

None

brunns.matchers.matcher.matches_with(value_to_match, expected_message)[source]¶

Matches if the matcher under test successfully matches the value, and provides the expected match description.

Parameters:

value_to_match (Any) – The value that the matcher under test should accept.
expected_message (str | Matcher[str]) – The expected string (or matcher for the string) generated by the matcher’s describe_match method.

Return type:

MatchesWith

brunns.matchers.matcher.matches(value_to_match)[source]¶

Matches if the matcher under test successfully matches the value, regardless of the message.

Parameters:: value_to_match (Any) – The value that the matcher under test should accept.
Return type:: MatchesWith

The “brunns.matchers.meta” module¶

class brunns.matchers.meta.BaseAutoMatcher[source]¶

Dynamically create matchers for classes. Use like so:

from dataclasses import dataclass
from typing import Optional

from hamcrest import assert_that, starts_with
from hamcrest.core.matcher import Matcher
from pydantic import BaseModel

from brunns.matchers.meta import BaseAutoMatcher

@dataclass
class Status:
    id: int
    code: str
    reason: Optional[str] = None

class StatusMatcher(BaseAutoMatcher[Status]): ...

def is_status() -> Matcher[Status]: return StatusMatcher()

actual = Status(status_code="ACTIVE", count=99)
assert_that(actual, is_status().with_code(starts_with("ACT")).and_reason(None))
assert_that(actual, is_status().with_id(42))  # Will fail

Works only for classes with __annotations__; typically manually annotated classes, dataclasses.dataclass and pydantic.BaseModel instances.

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(item, mismatch_description)[source]¶

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 (TypeVar(T)) – The item that the Matcher has rejected.
mismatch_description (Description) – The description to be built or appended to.

Return type:

None

describe_match(item, match_description)[source]¶

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 (TypeVar(T)) – The item that the Matcher has accepted.
match_description (Description) – The description to be built or appended to.

Return type:

None

The “brunns.matchers.mock” module¶

class brunns.matchers.mock.CallHasPositionalArg(index, expected)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(actual_call, mismatch_description)[source]¶

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

Return type:

None

class brunns.matchers.mock.CallHasKeywordArg(key, expected)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(actual_call, mismatch_description)[source]¶

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

Return type:

None

class brunns.matchers.mock.HasCall(call_matcher)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(mock, mismatch_description)[source]¶

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

Return type:

None

class brunns.matchers.mock.CallHasArgs(*args, **kwargs)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(call, mismatch_description)[source]¶

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

Return type:

None

brunns.matchers.mock.call_has_arg(arg, expected)[source]¶

Matches a mock.call if a specific positional or keyword argument satisfies the matcher.

Parameters:

arg (int | str) – If an integer, refers to the index of a positional argument. If a string, refers to the name of a keyword argument.
expected (Any) – The expected value or matcher for that argument.

Return type:

BaseMatcher[_Call]

brunns.matchers.mock.has_call(call_matcher)[source]¶

Matches a unittest.mock.Mock object if any of its calls satisfy the given matcher.

Parameters:: call_matcher (Matcher) – A matcher that validates a single mock.call object (e.g., created by call_has_arg or call_has_args).
Return type:: HasCall

brunns.matchers.mock.call_has_args(*args, **kwargs)[source]¶

Matches a mock.call if it matches all provided positional and keyword arguments.

The match is loose for keyword arguments (only specified keys are checked), but positional arguments are checked in order.

Parameters:

args – Expected values or matchers for positional arguments.
kwargs – Expected values or matchers for keyword arguments.

Return type:

CallHasArgs

The “brunns.matchers.object” module¶

brunns.matchers.object.has_repr(expected)[source]¶

Matches if the object’s repr() matches the expected string or matcher.

Parameters:: expected (Any) – The expected string representation or a string matcher.
Return type:: Matcher[Any]
Returns:: A matcher that validates repr(obj).

class brunns.matchers.object.HasRepr(expected)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

brunns.matchers.object.has_identical_properties_to(expected, ignoring=None)[source]¶

Matches an object if its public properties and attributes are identical to the expected object’s.

This matcher performs a deep recursive comparison of all public attributes (those not starting with _) and properties. It gracefully handles nested dictionaries and sequences.

Parameters:

expected (Any) – The reference object to compare against.
ignoring (Iterable[str] | None) – A collection of attribute names to exclude from the comparison.

Return type:

Matcher[Any]

Returns:

A matcher for object equality based on public state.

class brunns.matchers.object.HasIdenticalPropertiesTo(expected, ignoring=None)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

brunns.matchers.object.equal_vars(left, right, ignoring=None)[source]¶

Test if two objects are equal using public vars() and properties if available, with == otherwise.

Parameters:

left (Any) – The first object to compare.
right (Any) – The second object to compare.
ignoring (Iterable[str] | None) – Optional list of attribute names to ignore.

Return type:

bool

Returns:

True if objects are equivalent, False otherwise.

class brunns.matchers.object.Truthy[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

brunns.matchers.object.true()[source]¶

Matches any value that evaluates to True in a boolean context (truthy).

Return type:: Matcher[Any]
Returns:: A matcher for truthiness.

brunns.matchers.object.false()[source]¶

Matches any value that evaluates to False in a boolean context (falsy).

Return type:: Matcher[Any]
Returns:: A matcher for falsiness.

brunns.matchers.object.between(lower, upper, *, lower_inclusive=True, upper_inclusive=True)[source]¶

Matches if a value is within a specific range.

Parameters:

lower (Any) – The lower bound of the range.
upper (Any) – The upper bound of the range.
lower_inclusive – If True, the range includes the lower bound (>=). If False, it is exclusive (>). Defaults to True.
upper_inclusive – If True, the range includes the upper bound (<=). If False, it is exclusive (<). Defaults to True.

Return type:

Matcher[Any]

Returns:

A matcher for the specified range.

The “brunns.matchers.response” module¶

brunns.matchers.response.is_response()[source]¶

Matches a requests.Response or httpx.Response object.

This function returns a ResponseMatcher which can be refined using builder methods (e.g. .with_status_code(200)).

Return type:: ResponseMatcher
Returns:: A matcher for HTTP responses.

class brunns.matchers.response.ResponseMatcher(status_code=<IsAnything(ANYTHING)>, body=<IsAnything(ANYTHING)>, content=<IsAnything(ANYTHING)>, json=<IsAnything(ANYTHING)>, headers=<IsAnything(ANYTHING)>, cookies=<IsAnything(ANYTHING)>, elapsed=<IsAnything(ANYTHING)>, history=<IsAnything(ANYTHING)>, url=<IsAnything(ANYTHING)>, encoding=<IsAnything(ANYTHING)>)[source]¶

Matches requests.Response or httpx.Response.

Parameters:

status_code (int | Matcher[int]) – Expected status code.
body (str | Matcher[str]) – Expected body text.
content (bytes | Matcher[bytes]) – Expected raw binary content.
json (Any | Matcher[Any]) – Expected JSON body (parsed).
headers (Mapping[str, str | Matcher[str]] | Matcher[Mapping[str, str | Matcher[str]]]) – Expected headers dictionary.
cookies (Mapping[str, str | Matcher[str]] | Matcher[Mapping[str, str | Matcher[str]]]) – Expected cookies dictionary.
elapsed (timedelta | Matcher[timedelta]) – Expected elapsed time (timedelta).
history (Sequence[Response | Response | Matcher[Response | Response]] | Matcher[Sequence[Response | Response | Matcher[Response | Response]]]) – Expected history sequence.
url (furl | str | Matcher[furl | str]) – Expected URL.
encoding (str | None | Matcher[str | None]) – Expected encoding string.

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(response, mismatch_description)[source]¶

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

Return type:

None

describe_match(response, match_description)[source]¶

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

Return type:

None

with_status_code(status_code)[source]¶

Matches if the response status code matches the given value or matcher.

Parameters:: status_code (int | Matcher[int]) – The expected status code (e.g. 200) or a matcher (e.g. between(200, 299)).
Returns:: Self, for chaining.

and_status_code(status_code)[source]¶

Matches if the response status code matches the given value or matcher.

A synonym for with_status_code().

Parameters:: status_code (int | Matcher[int]) – The expected status code.
Returns:: Self, for chaining.

with_body(body)[source]¶

Matches if the response body text matches the given value or matcher.

Parameters:: body (str | Matcher[str]) – The expected body string or matcher.
Returns:: Self, for chaining.

and_body(body)[source]¶

Matches if the response body text matches the given value or matcher.

A synonym for with_body().

Parameters:: body (str | Matcher[str]) – The expected body string or matcher.
Returns:: Self, for chaining.

with_content(content)[source]¶

Matches if the response binary content matches the given value or matcher.

Parameters:: content (bytes | Matcher[bytes]) – The expected bytes or matcher.
Returns:: Self, for chaining.

and_content(content)[source]¶

Matches if the response binary content matches the given value or matcher.

A synonym for with_content().

Parameters:: content (bytes | Matcher[bytes]) – The expected bytes or matcher.
Returns:: Self, for chaining.

with_json(json)[source]¶

Matches if the response JSON body matches the given value or matcher.

The response body is parsed as JSON before matching.

Parameters:: json (Any | Matcher[Any]) – The expected JSON structure (dict, list, etc.) or matcher.
Returns:: Self, for chaining.

and_json(json)[source]¶

Matches if the response JSON body matches the given value or matcher.

A synonym for with_json().

Parameters:: json (Any | Matcher[Any]) – The expected JSON structure or matcher.
Returns:: Self, for chaining.

with_headers(headers)[source]¶

Matches if the response headers match the given value or matcher.

Parameters:: headers (Mapping[str, str | Matcher[str]] | Matcher[Mapping[str, str | Matcher[str]]]) – The expected headers dictionary or matcher.
Returns:: Self, for chaining.

and_headers(headers)[source]¶

Matches if the response headers match the given value or matcher.

A synonym for with_headers().

Parameters:: headers (Mapping[str, str | Matcher[str]] | Matcher[Mapping[str, str | Matcher[str]]]) – The expected headers dictionary or matcher.
Returns:: Self, for chaining.

with_cookies(cookies)[source]¶

Matches if the response cookies match the given value or matcher.

Parameters:: cookies (Mapping[str, str | Matcher[str]] | Matcher[Mapping[str, str | Matcher[str]]]) – The expected cookies dictionary or matcher.
Returns:: Self, for chaining.

and_cookies(cookies)[source]¶

Matches if the response cookies match the given value or matcher.

A synonym for with_cookies().

Parameters:: cookies (Mapping[str, str | Matcher[str]] | Matcher[Mapping[str, str | Matcher[str]]]) – The expected cookies dictionary or matcher.
Returns:: Self, for chaining.

with_elapsed(elapsed)[source]¶

Matches if the response elapsed time matches the given value or matcher.

Parameters:: elapsed (timedelta | Matcher[timedelta]) – The expected timedelta or matcher.
Returns:: Self, for chaining.

and_elapsed(elapsed)[source]¶

Matches if the response elapsed time matches the given value or matcher.

A synonym for with_elapsed().

Parameters:: elapsed (timedelta | Matcher[timedelta]) – The expected timedelta or matcher.
Returns:: Self, for chaining.

with_history(history)[source]¶

Matches if the response history (redirects) matches the given sequence or matcher.

Parameters:: history (Sequence[Response | Response | Matcher[Response | Response]] | Matcher[Sequence[Response | Response | Matcher[Response | Response]]]) – The expected sequence of responses/matchers or a sequence matcher.
Returns:: Self, for chaining.

and_history(history)[source]¶

Matches if the response history (redirects) matches the given sequence or matcher.

A synonym for with_history().

Parameters:: history (Sequence[Response | Response | Matcher[Response | Response]] | Matcher[Sequence[Response | Response | Matcher[Response | Response]]]) – The expected sequence or matcher.
Returns:: Self, for chaining.

with_url(url)[source]¶

Matches if the response URL matches the given value or matcher.

Parameters:: url (furl | str | Matcher[furl | str]) – The expected URL string, object, or matcher.
Returns:: Self, for chaining.

and_url(url)[source]¶

Matches if the response URL matches the given value or matcher.

A synonym for with_url().

Parameters:: url (furl | str | Matcher[furl | str]) – The expected URL string, object, or matcher.
Returns:: Self, for chaining.

with_encoding(encoding)[source]¶

Matches if the response encoding matches the given value or matcher.

Parameters:: encoding (str | None | Matcher[str | None]) – The expected encoding string or matcher.
Returns:: Self, for chaining.

and_encoding(encoding)[source]¶

Matches if the response encoding matches the given value or matcher.

A synonym for with_encoding().

Parameters:: encoding (str | None | Matcher[str | None]) – The expected encoding string or matcher.
Returns:: Self, for chaining.

brunns.matchers.response.redirects_to(url_matcher)[source]¶

Is a response a redirect to a URL matching the supplied matcher?

Matches if the status code is between 300 and 399 and the Location header matches the provided URL matcher.

Parameters:: url_matcher (str | Matcher[str] | URL | Matcher[URL]) – The expected URL (string or matcher) found in the Location header.
Return type:: Matcher[Response | Response]
Returns:: A matcher for redirect responses.

brunns.matchers.response.response_with(status_code=<IsAnything(ANYTHING)>, body=<IsAnything(ANYTHING)>, content=<IsAnything(ANYTHING)>, json=<IsAnything(ANYTHING)>, headers=<IsAnything(ANYTHING)>)[source]¶

Matches a response with specific attributes.

Deprecated since version 2.3.0: Use is_response() and its builder methods instead.

Return type:: ResponseMatcher

The “brunns.matchers.rss” module¶

class brunns.matchers.rss.RssFeedMatcher[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(item, mismatch_description)[source]¶

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 (str) – The item that the Matcher has rejected.
mismatch_description (Description) – The description to be built or appended to.

Return type:

None

describe_match(item, match_description)[source]¶

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 (TypeVar(T)) – The item that the Matcher has accepted.
match_description (Description) – The description to be built or appended to.

Return type:

None

class brunns.matchers.rss.RssFeedEntryMatcher[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_match(item, match_description)[source]¶

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 (FeedParserDict) – The item that the Matcher has accepted.
match_description (Description) – The description to be built or appended to.

Return type:

None

describe_mismatch(item, mismatch_description)[source]¶

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 (FeedParserDict) – The item that the Matcher has rejected.
mismatch_description (Description) – The description to be built or appended to.

Return type:

None

brunns.matchers.rss.is_rss_feed()[source]¶

Matches a string (or URL-like object) as an RSS feed using feedparser.

The string is parsed as an RSS feed, and the resulting structure is checked. This matcher uses a builder pattern (e.g., .with_title(...)) to refine the match.

Return type:: RssFeedMatcher
Returns:: A matcher for RSS feed content.

brunns.matchers.rss.is_rss_entry()[source]¶

Matches a single RSS feed entry (item) within an RSS feed.

This matcher operates on feedparser.FeedParserDict objects, typically found in the entries list of a parsed feed.

Return type:: RssFeedEntryMatcher
Returns:: A matcher for an RSS feed entry.

The “brunns.matchers.smtp” module¶

class brunns.matchers.smtp.Email(to_name, to_address, from_name, from_address, subject, body_text)[source]¶

brunns.matchers.smtp.is_email()[source]¶

Matches a string as an RFC 822 / MIME email message.

This function returns an EmailWith matcher which can be refined using builder methods (e.g., .with_subject(...)). It parses the string using Python’s email module.

Return type:: EmailWith
Returns:: A matcher for email strings.

class brunns.matchers.smtp.EmailWith(to_name=<IsAnything(ANYTHING)>, to_address=<IsAnything(ANYTHING)>, from_name=<IsAnything(ANYTHING)>, from_address=<IsAnything(ANYTHING)>, subject=<IsAnything(ANYTHING)>, body_text=<IsAnything(ANYTHING)>)[source]¶

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(actual_email, mismatch_description)[source]¶

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

Return type:

None

describe_match(actual_email, match_description)[source]¶

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

Return type:

None

with_to_name(to_name)[source]¶

Matches if the email ‘To’ name matches the given value or matcher.

Parameters:: to_name (str | Matcher[str]) – The expected recipient name or matcher.
Returns:: Self, for chaining.

and_to_name(to_name)[source]¶

Matches if the email ‘To’ name matches the given value or matcher.

A synonym for with_to_name().

Parameters:: to_name (str | Matcher[str]) – The expected recipient name or matcher.
Returns:: Self, for chaining.

with_to_address(to_address)[source]¶

Matches if the email ‘To’ address matches the given value or matcher.

Parameters:: to_address (str | Matcher[str]) – The expected recipient email address or matcher.
Returns:: Self, for chaining.

and_to_address(to_address)[source]¶

Matches if the email ‘To’ address matches the given value or matcher.

A synonym for with_to_address().

Parameters:: to_address (str | Matcher[str]) – The expected recipient email address or matcher.
Returns:: Self, for chaining.

with_from_name(from_name)[source]¶

Matches if the email ‘From’ name matches the given value or matcher.

Parameters:: from_name (str | Matcher[str]) – The expected sender name or matcher.
Returns:: Self, for chaining.

and_from_name(from_name)[source]¶

Matches if the email ‘From’ name matches the given value or matcher.

A synonym for with_from_name().

Parameters:: from_name (str | Matcher[str]) – The expected sender name or matcher.
Returns:: Self, for chaining.

with_from_address(from_address)[source]¶

Matches if the email ‘From’ address matches the given value or matcher.

Parameters:: from_address (str | Matcher[str]) – The expected sender email address or matcher.
Returns:: Self, for chaining.

and_from_address(from_address)[source]¶

Matches if the email ‘From’ address matches the given value or matcher.

A synonym for with_from_address().

Parameters:: from_address (str | Matcher[str]) – The expected sender email address or matcher.
Returns:: Self, for chaining.

with_subject(subject)[source]¶

Matches if the email subject matches the given value or matcher.

Parameters:: subject (str | Matcher[str]) – The expected subject string or matcher.
Returns:: Self, for chaining.

and_subject(subject)[source]¶

Matches if the email subject matches the given value or matcher.

A synonym for with_subject().

Parameters:: subject (str | Matcher[str]) – The expected subject string or matcher.
Returns:: Self, for chaining.

with_body_text(body_text)[source]¶

Matches if the email body text matches the given value or matcher.

Parameters:: body_text (str | Matcher[str]) – The expected body string or matcher.
Returns:: Self, for chaining.

and_body_text(body_text)[source]¶

Matches if the email body text matches the given value or matcher.

A synonym for with_body_text().

Parameters:: body_text (str | Matcher[str]) – The expected body string or matcher.
Returns:: Self, for chaining.

brunns.matchers.smtp.email_with(to_name=<IsAnything(ANYTHING)>, to_address=<IsAnything(ANYTHING)>, from_name=<IsAnything(ANYTHING)>, from_address=<IsAnything(ANYTHING)>, subject=<IsAnything(ANYTHING)>, body_text=<IsAnything(ANYTHING)>)[source]¶

Matches an email string with specific attributes.

Deprecated since version 2.3.0: Use is_email() and its builder methods instead.

Parameters:

to_name (str | Matcher[str]) – Expected recipient name.
to_address (str | Matcher[str]) – Expected recipient email address.
from_name (str | Matcher[str]) – Expected sender name.
from_address (str | Matcher[str]) – Expected sender email address.
subject (str | Matcher[str]) – Expected subject line.
body_text (str | Matcher[str]) – Expected body content.

Return type:

Matcher

Returns:

A matcher for email strings.

The “brunns.matchers.url” module¶

brunns.matchers.url.is_url()[source]¶

Matches a string (or furl / yarl.URL object) as a URL.

This function returns a UrlWith matcher which can be refined using builder methods to match specific parts of the URL (e.g. .with_host(...), .with_query(...)).

Return type:: UrlWith
Returns:: A matcher for URL components.

class brunns.matchers.url.UrlWith(host=<IsAnything(ANYTHING)>, path=<IsAnything(ANYTHING)>, query=<IsAnything(ANYTHING)>, fragment=<IsAnything(ANYTHING)>)[source]¶

Matches specific components of a URL.

The matcher parses the actual value using the furl library.

Parameters:

host (str | Matcher[str]) – Expected hostname (e.g., “google.com”).
path (str | Matcher[str]) – Expected path string (e.g., “/search”).
query (Mapping[str, str | Matcher[str]] | Matcher[Mapping[str, str | Matcher[str]]]) – Expected query parameters dictionary.
fragment (str | Matcher[str]) – Expected URL fragment (hash).

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(url, mismatch_description)[source]¶

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

Return type:

None

describe_match(url, match_description)[source]¶

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

Return type:

None

with_scheme(scheme)[source]¶

Matches if the URL scheme matches the given value or matcher.

Parameters:: scheme (str | Matcher[str]) – The expected scheme (e.g. “https”) or matcher.
Returns:: Self, for chaining.

and_scheme(scheme)[source]¶

Matches if the URL scheme matches the given value or matcher.

A synonym for with_scheme().

Parameters:: scheme (str | Matcher[str]) – The expected scheme or matcher.
Returns:: Self, for chaining.

with_username(username)[source]¶

Matches if the URL username matches the given value or matcher.

Parameters:: username (str | Matcher[str]) – The expected username or matcher.
Returns:: Self, for chaining.

and_username(username)[source]¶

Matches if the URL username matches the given value or matcher.

A synonym for with_username().

Parameters:: username (str | Matcher[str]) – The expected username or matcher.
Returns:: Self, for chaining.

with_password(password)[source]¶

Matches if the URL password matches the given value or matcher.

Parameters:: password (str | Matcher[str]) – The expected password or matcher.
Returns:: Self, for chaining.

and_password(password)[source]¶

Matches if the URL password matches the given value or matcher.

A synonym for with_password().

Parameters:: password (str | Matcher[str]) – The expected password or matcher.
Returns:: Self, for chaining.

with_host(host)[source]¶

Matches if the URL host matches the given value or matcher.

Parameters:: host (str | Matcher[str]) – The expected hostname or matcher.
Returns:: Self, for chaining.

and_host(host)[source]¶

Matches if the URL host matches the given value or matcher.

A synonym for with_host().

Parameters:: host (str | Matcher[str]) – The expected hostname or matcher.
Returns:: Self, for chaining.

with_port(port)[source]¶

Matches if the URL port matches the given value or matcher.

Parameters:: port (int | Matcher[int]) – The expected port integer or matcher.
Returns:: Self, for chaining.

and_port(port)[source]¶

Matches if the URL port matches the given value or matcher.

A synonym for with_port().

Parameters:: port (int | Matcher[int]) – The expected port integer or matcher.
Returns:: Self, for chaining.

with_path(path)[source]¶

Matches if the URL path matches the given value or matcher.

Parameters:: path (str | Matcher[str]) – The expected path string (e.g. “/foo/bar”) or matcher.
Returns:: Self, for chaining.

and_path(path)[source]¶

Matches if the URL path matches the given value or matcher.

A synonym for with_path().

Parameters:: path (str | Matcher[str]) – The expected path string or matcher.
Returns:: Self, for chaining.

with_path_segments(path_segments)[source]¶

Matches if the URL path segments match the given sequence or matcher.

Parameters:: path_segments (Sequence[str] | Matcher[Sequence[str]]) – The expected sequence of path segments (e.g. [“foo”, “bar”]) or matcher.
Returns:: Self, for chaining.

and_path_segments(path_segments)[source]¶

Matches if the URL path segments match the given sequence or matcher.

A synonym for with_path_segments().

Parameters:: path_segments (Sequence[str] | Matcher[Sequence[str]]) – The expected sequence of path segments or matcher.
Returns:: Self, for chaining.

with_query(query)[source]¶

Matches if the URL query parameters match the given dictionary or matcher.

Parameters:: query (Mapping[str, str | Matcher[str]] | Matcher[Mapping[str, str | Matcher[str]]]) – The expected query parameters dictionary or matcher.
Returns:: Self, for chaining.

and_query(query)[source]¶

Matches if the URL query parameters match the given dictionary or matcher.

A synonym for with_query().

Parameters:: query (Mapping[str, str | Matcher[str]] | Matcher[Mapping[str, str | Matcher[str]]]) – The expected query parameters dictionary or matcher.
Returns:: Self, for chaining.

with_fragment(fragment)[source]¶

Matches if the URL fragment (hash) matches the given value or matcher.

Parameters:: fragment (str | Matcher[str]) – The expected fragment string or matcher.
Returns:: Self, for chaining.

and_fragment(fragment)[source]¶

Matches if the URL fragment (hash) matches the given value or matcher.

A synonym for with_fragment().

Parameters:: fragment (str | Matcher[str]) – The expected fragment string or matcher.
Returns:: Self, for chaining.

brunns.matchers.url.url_with_host(matcher)[source]¶: Matches URL with specific host.

Deprecated since version 2.3.0: Use is_url().with_host(...) instead.

brunns.matchers.url.url_with_path(matcher)[source]¶: Matches URL with specific path.

Deprecated since version 2.3.0: Use is_url().with_path(...) instead.

brunns.matchers.url.url_with_query(matcher)[source]¶: Matches URL with specific query parameters.

Deprecated since version 2.3.0: Use is_url().with_query(...) instead.

brunns.matchers.url.url_with_fragment(matcher)[source]¶: Matches URL with specific fragment.

Deprecated since version 2.3.0: Use is_url().with_fragment(...) instead.

brunns.matchers.url.to_host(matcher)[source]¶: Matches URL with specific host.

Deprecated since version 2.2.0: Use is_url().with_host(...) instead.

brunns.matchers.url.with_path(matcher)[source]¶: Matches URL with specific path.

Deprecated since version 2.2.0: Use is_url().with_path(...) instead.

brunns.matchers.url.with_query(matcher)[source]¶: Matches URL with specific query parameters.

Deprecated since version 2.2.0: Use is_url().with_query(...) instead.

brunns.matchers.url.with_fragment(matcher)[source]¶: Matches URL with specific fragment.

Deprecated since version 2.2.0: Use is_url().with_fragment(...) instead.

The “brunns.matchers.werkzeug” module¶

brunns.matchers.werkzeug.is_werkzeug_response()[source]¶

Matches a werkzeug.test.TestResponse object (e.g. from Flask test client).

This function returns a WerkzeugResponseMatcher which can be refined using builder methods (e.g., .with_status_code(200)).

Return type:: WerkzeugResponseMatcher
Returns:: A matcher for Werkzeug/Flask test responses.

class brunns.matchers.werkzeug.WerkzeugResponseMatcher[source]¶

Matches a werkzeug.test.TestResponse object.

This matcher is useful for testing Flask applications using the built-in test client.

describe_to(description)[source]¶

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 (Description) – The description to be built or appended to.
Return type:: None

describe_mismatch(response, mismatch_description)[source]¶

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

Return type:

None

describe_match(response, match_description)[source]¶

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

Return type:

None

with_status_code(status_code)[source]¶

Matches if the response status code matches the given value or matcher.

Parameters:: status_code (int | Matcher[int]) – The expected status code (e.g. 200) or matcher.
Return type:: WerkzeugResponseMatcher
Returns:: Self, for chaining.

and_status_code(status_code)[source]¶

Matches if the response status code matches the given value or matcher.

A synonym for with_status_code().

Parameters:: status_code (int | Matcher[int]) – The expected status code or matcher.
Return type:: WerkzeugResponseMatcher
Returns:: Self, for chaining.

with_text(text)[source]¶

Matches if the response body text matches the given value or matcher.

Parameters:: text (str | Matcher[str]) – The expected body text string or matcher.
Return type:: WerkzeugResponseMatcher
Returns:: Self, for chaining.

and_text(text)[source]¶

Matches if the response body text matches the given value or matcher.

A synonym for with_text().

Parameters:: text (str | Matcher[str]) – The expected body text string or matcher.
Return type:: WerkzeugResponseMatcher
Returns:: Self, for chaining.

with_mimetype(mimetype)[source]¶

Matches if the response mimetype matches the given value or matcher.

Parameters:: mimetype (str | Matcher[str]) – The expected mimetype string or matcher.
Return type:: WerkzeugResponseMatcher
Returns:: Self, for chaining.

and_mimetype(mimetype)[source]¶

Matches if the response mimetype matches the given value or matcher.

A synonym for with_mimetype().

Parameters:: mimetype (str | Matcher[str]) – The expected mimetype string or matcher.
Return type:: WerkzeugResponseMatcher
Returns:: Self, for chaining.

with_json(json)[source]¶

Matches if the response JSON body matches the given value or matcher.

The response body is parsed as JSON before matching.

Parameters:: json (Any | Matcher[Any]) – The expected JSON structure or matcher.
Return type:: WerkzeugResponseMatcher
Returns:: Self, for chaining.

and_json(json)[source]¶

Matches if the response JSON body matches the given value or matcher.

A synonym for with_json().

Parameters:: json (Any | Matcher[Any]) – The expected JSON structure or matcher.
Return type:: WerkzeugResponseMatcher
Returns:: Self, for chaining.

with_headers(headers)[source]¶

Matches if the response headers match the given value or matcher.

Parameters:: headers (Mapping[str, str | Matcher[str]] | Matcher[Mapping[str, str | Matcher[str]]]) – The expected headers dictionary or matcher.
Return type:: WerkzeugResponseMatcher
Returns:: Self, for chaining.

and_headers(headers)[source]¶

Matches if the response headers match the given value or matcher.

A synonym for with_headers().

Parameters:: headers (Mapping[str, str | Matcher[str]] | Matcher[Mapping[str, str | Matcher[str]]]) – The expected headers dictionary or matcher.
Return type:: WerkzeugResponseMatcher
Returns:: Self, for chaining.

brunns.matchers.werkzeug.redirects_to(url_matcher)[source]¶

Matches if the Werkzeug response is a redirect to the specified URL.

Checks if the status code is between 300 and 399 and the Location header matches.

Parameters:: url_matcher (str | Matcher) – The expected URL string or matcher.
Return type:: Matcher[TestResponse]
Returns:: A matcher for redirect responses.