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 (str | int | float | bool | Sequence[str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | Mapping[str, str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | None | Matcher[str | int | float | bool | Sequence[str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | Mapping[str, str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | None]) – 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(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

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

Matches string containing JSON data.

Parameters:

matcher (Matcher[str | int | float | bool | Sequence[str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | Mapping[str, str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | None] | str | int | float | bool | Sequence[str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | Mapping[str, str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | None) – 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(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 (date) – The item that the Matcher has rejected.

  • mismatch_description (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(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 (Connection) – 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:
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(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

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(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 (Tag) – 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.

Requires brunns-matchers to have been installed with the html extra.

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.

Requires brunns-matchers to have been installed with the html extra.

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.

Requires brunns-matchers to have been installed with the html extra.

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.

Requires brunns-matchers to have been installed with the html extra.

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.

Requires brunns-matchers to have been installed with the html extra.

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.

Requires brunns-matchers to have been installed with the html extra.

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.

Requires brunns-matchers to have been installed with the html extra.

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.

Requires brunns-matchers to have been installed with the html extra.

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.

Requires brunns-matchers to have been installed with the html extra.

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.

Requires brunns-matchers to have been installed with the html extra.

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

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

Requires brunns-matchers to have been installed with the html extra.

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.

Requires brunns-matchers to have been installed with the html extra.

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(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 (Matcher[Any]) – The item that the Matcher has rejected.

  • mismatch_description (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(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 (Matcher[Any]) – The item that the Matcher has rejected.

  • mismatch_description (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(code="ACTIVE", id=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(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 (_Call) – 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(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 (_Call) – 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(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 (Mock) – 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(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 (_Call) – 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.path” module

class brunns.matchers.path.PathMatcher[source]
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 (Path | 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 (Path | str) – The item that the Matcher has accepted.

  • match_description (Description) – The description to be built or appended to.

Return type:

None

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

with_anchor(item)[source]

Matches the path’s anchor (drive and root combined).

Parameters:

item (str | Matcher[str]) – Expected anchor string or a matcher for the anchor.

Return type:

Self

Returns:

This matcher instance for chaining.

and_anchor(item)

Matches the path’s anchor (drive and root combined).

Parameters:

item (str | Matcher[str]) – Expected anchor string or a matcher for the anchor.

Return type:

Self

Returns:

This matcher instance for chaining.

with_name(item)[source]

Matches the path’s name (final component).

Parameters:

item (str | Matcher[str]) – Expected name string or a matcher for the name.

Return type:

Self

Returns:

This matcher instance for chaining.

and_name(item)

Matches the path’s name (final component).

Parameters:

item (str | Matcher[str]) – Expected name string or a matcher for the name.

Return type:

Self

Returns:

This matcher instance for chaining.

with_parent(item)[source]

Matches the path’s parent directory.

Parameters:

item (Any | Matcher[Any]) – Expected parent path or a matcher for the parent.

Return type:

Self

Returns:

This matcher instance for chaining.

and_parent(item)

Matches the path’s parent directory.

Parameters:

item (Any | Matcher[Any]) – Expected parent path or a matcher for the parent.

Return type:

Self

Returns:

This matcher instance for chaining.

with_parents(item)[source]

Matches the path’s sequence of parent directories.

Parameters:

item (Sequence[Any] | Matcher[Sequence[Any]]) – Expected sequence of parent paths or a matcher for ancestors.

Return type:

Self

Returns:

This matcher instance for chaining.

and_parents(item)

Matches the path’s sequence of parent directories.

Parameters:

item (Sequence[Any] | Matcher[Sequence[Any]]) – Expected sequence of parent paths or a matcher for ancestors.

Return type:

Self

Returns:

This matcher instance for chaining.

with_parts(item)[source]

Matches the path’s component sequence.

Parameters:

item (Sequence[str] | Matcher[Sequence[str]]) – Expected sequence of path part strings or a matcher for them.

Return type:

Self

Returns:

This matcher instance for chaining.

and_parts(item)

Matches the path’s component sequence.

Parameters:

item (Sequence[str] | Matcher[Sequence[str]]) – Expected sequence of path part strings or a matcher for them.

Return type:

Self

Returns:

This matcher instance for chaining.

with_root(item)[source]

Matches the path’s root string.

Parameters:

item (str | Matcher[str]) – Expected root string or a matcher for the root.

Return type:

Self

Returns:

This matcher instance for chaining.

and_root(item)

Matches the path’s root string.

Parameters:

item (str | Matcher[str]) – Expected root string or a matcher for the root.

Return type:

Self

Returns:

This matcher instance for chaining.

with_stem(item)[source]

Matches the path’s stem (final component without its extension).

Parameters:

item (str | Matcher[str]) – Expected stem string or a matcher for the stem.

Return type:

Self

Returns:

This matcher instance for chaining.

and_stem(item)

Matches the path’s stem (final component without its extension).

Parameters:

item (str | Matcher[str]) – Expected stem string or a matcher for the stem.

Return type:

Self

Returns:

This matcher instance for chaining.

with_suffix(item)[source]

Matches the path’s file suffix (extension).

Parameters:

item (str | Matcher[str]) – Expected suffix string or a matcher for the suffix.

Return type:

Self

Returns:

This matcher instance for chaining.

and_suffix(item)

Matches the path’s file suffix (extension).

Parameters:

item (str | Matcher[str]) – Expected suffix string or a matcher for the suffix.

Return type:

Self

Returns:

This matcher instance for chaining.

with_suffixes(item)[source]

Matches the path’s list of file suffixes (extensions).

Parameters:

item (Sequence[str] | Matcher[Sequence[str]]) – Expected sequence of suffix strings or a matcher for them.

Return type:

Self

Returns:

This matcher instance for chaining.

and_suffixes(item)

Matches the path’s list of file suffixes (extensions).

Parameters:

item (Sequence[str] | Matcher[Sequence[str]]) – Expected sequence of suffix strings or a matcher for them.

Return type:

Self

Returns:

This matcher instance for chaining.

which_exists()[source]

Matches that the path exists on the filesystem.

Return type:

Self

Returns:

This matcher instance for chaining.

and_which_exists()

Matches that the path exists on the filesystem.

Return type:

Self

Returns:

This matcher instance for chaining.

which_does_not_exist()[source]

Matches that the path does not exist on the filesystem.

Return type:

Self

Returns:

This matcher instance for chaining.

and_which_does_not_exist()

Matches that the path does not exist on the filesystem.

Return type:

Self

Returns:

This matcher instance for chaining.

which_is_a_file()[source]

Matches that the path is a regular file.

Return type:

Self

Returns:

This matcher instance for chaining.

and_is_a_file()

Matches that the path is a regular file.

Return type:

Self

Returns:

This matcher instance for chaining.

which_is_a_directory()[source]

Matches that the path is a directory.

Return type:

Self

Returns:

This matcher instance for chaining.

and_is_a_directory()

Matches that the path is a directory.

Return type:

Self

Returns:

This matcher instance for chaining.

which_is_absolute()[source]

Matches that the path is absolute.

Return type:

Self

Returns:

This matcher instance for chaining.

and_is_absolute()

Matches that the path is absolute.

Return type:

Self

Returns:

This matcher instance for chaining.

which_is_relative()[source]

Matches that the path is not absolute.

Return type:

Self

Returns:

This matcher instance for chaining.

and_is_relative()

Matches that the path is not absolute.

Return type:

Self

Returns:

This matcher instance for chaining.

which_is_relative_to(relative_path)[source]

Matches that the path is relative to another Path.

Return type:

Self

Returns:

This matcher instance for chaining.

brunns.matchers.path.is_path()[source]

Matches a pathlib.Path or string filepath.

This function returns a PathMatcher which can be refined using builder methods to match specific parts of the pathlib.Path (e.g. .with_name(...), .with_suffix(...)).

Return type:

PathMatcher

Returns:

A matcher for pathlib.Path objects or string filepaths.

The “brunns.matchers.response” module

class brunns.matchers.response.ResponseProtocol(*args, **kwargs)[source]

Structural typing for HTTP Response objects.

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

Matches an HTTP response object (requests, httpx, etc.).

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]
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:
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:
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)).

Return type:

ResponseMatcher

Returns:

ResponseMatcher, for chaining.

and_status_code(status_code)

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)).

Return type:

ResponseMatcher

Returns:

ResponseMatcher, 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.

Return type:

Self

Returns:

ResponseMatcher, for chaining.

and_body(body)

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

Parameters:

body (str | Matcher[str]) – The expected body string or matcher.

Return type:

Self

Returns:

ResponseMatcher, 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.

Return type:

Self

Returns:

ResponseMatcher, for chaining.

and_content(content)

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

Parameters:

content (bytes | Matcher[bytes]) – The expected bytes or matcher.

Return type:

Self

Returns:

ResponseMatcher, 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 (str | int | float | bool | Sequence[str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | Mapping[str, str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | None | Matcher[str | int | float | bool | Sequence[str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | Mapping[str, str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | None]) – The expected JSON structure (dict, list, etc.) or matcher.

Return type:

Self

Returns:

ResponseMatcher, for chaining.

and_json(json)

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

The response body is parsed as JSON before matching.

Parameters:

json (str | int | float | bool | Sequence[str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | Mapping[str, str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | None | Matcher[str | int | float | bool | Sequence[str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | Mapping[str, str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | None]) – The expected JSON structure (dict, list, etc.) or matcher.

Return type:

Self

Returns:

ResponseMatcher, 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:

Self

Returns:

ResponseMatcher, for chaining.

and_headers(headers)

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:

Self

Returns:

ResponseMatcher, 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.

Return type:

Self

Returns:

ResponseMatcher, for chaining.

and_cookies(cookies)

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.

Return type:

Self

Returns:

ResponseMatcher, 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.

Return type:

Self

Returns:

ResponseMatcher, for chaining.

and_elapsed(elapsed)

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

Parameters:

elapsed (timedelta | Matcher[timedelta]) – The expected timedelta or matcher.

Return type:

Self

Returns:

ResponseMatcher, for chaining.

with_history(history)[source]

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

Parameters:

history (Sequence[ResponseProtocol | Matcher[ResponseProtocol]] | Matcher[Sequence[ResponseProtocol | Matcher[ResponseProtocol]]]) – The expected sequence of responses/matchers or a sequence matcher.

Return type:

Self

Returns:

ResponseMatcher, for chaining.

and_history(history)

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

Parameters:

history (Sequence[ResponseProtocol | Matcher[ResponseProtocol]] | Matcher[Sequence[ResponseProtocol | Matcher[ResponseProtocol]]]) – The expected sequence of responses/matchers or a sequence matcher.

Return type:

Self

Returns:

ResponseMatcher, for chaining.

with_url(url)[source]

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

Parameters:

url (UrlProtocol | Matcher[UrlProtocol]) – The expected URL string, object, or matcher.

Return type:

Self

Returns:

ResponseMatcher, for chaining.

and_url(url)

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

Parameters:

url (UrlProtocol | Matcher[UrlProtocol]) – The expected URL string, object, or matcher.

Return type:

Self

Returns:

ResponseMatcher, for chaining.

with_encoding(encoding)[source]

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

Parameters:

encoding (str | Matcher[str | None] | None) – The expected encoding string or matcher.

Return type:

Self

Returns:

ResponseMatcher, for chaining.

and_encoding(encoding)

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

Parameters:

encoding (str | Matcher[str | None] | None) – The expected encoding string or matcher.

Return type:

Self

Returns:

ResponseMatcher, 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 (UrlProtocol | Matcher[UrlProtocol]) – The expected URL (string or matcher) found in the Location header.

Return type:

Matcher[ResponseProtocol]

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 (UrlProtocol) – 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:
Return type:

None

with_title(title)[source]

Matches the title of the RSS feed.

Parameters:

title (str | Matcher[str]) – Expected title string or a matcher for the title.

Return type:

Self

Returns:

This matcher instance for chaining.

and_title(title)

Matches the title of the RSS feed.

Parameters:

title (str | Matcher[str]) – Expected title string or a matcher for the title.

Return type:

Self

Returns:

This matcher instance for chaining.

Matches the link URL of the RSS feed.

Parameters:

link (UrlProtocol | Matcher[UrlProtocol]) – Expected link URL or a matcher for the link.

Return type:

Self

Returns:

This matcher instance for chaining.

Matches the link URL of the RSS feed.

Parameters:

link (UrlProtocol | Matcher[UrlProtocol]) – Expected link URL or a matcher for the link.

Return type:

Self

Returns:

This matcher instance for chaining.

with_description(description)[source]

Matches the description of the RSS feed.

Parameters:

description (str | Matcher[str]) – Expected description string or a matcher for the description.

Return type:

Self

Returns:

This matcher instance for chaining.

and_description(description)

Matches the description of the RSS feed.

Parameters:

description (str | Matcher[str]) – Expected description string or a matcher for the description.

Return type:

Self

Returns:

This matcher instance for chaining.

with_published(published)[source]

Matches the publication datetime of the RSS feed.

Parameters:

published (datetime | Matcher[datetime | None] | None) – Expected publication datetime or a matcher for the published date.

Return type:

Self

Returns:

This matcher instance for chaining.

and_published(published)

Matches the publication datetime of the RSS feed.

Parameters:

published (datetime | Matcher[datetime | None] | None) – Expected publication datetime or a matcher for the published date.

Return type:

Self

Returns:

This matcher instance for chaining.

with_entries(entries)[source]

Matches the entries (items) within the RSS feed.

Parameters:

entries (list[FeedParserDict] | Matcher[list[FeedParserDict]]) – Expected list of entries or a matcher for the entries.

Return type:

Self

Returns:

This matcher instance for chaining.

and_entries(entries)

Matches the entries (items) within the RSS feed.

Parameters:

entries (list[FeedParserDict] | Matcher[list[FeedParserDict]]) – Expected list of entries or a matcher for the entries.

Return type:

Self

Returns:

This matcher instance for chaining.

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 | str) – 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 | str) – The item that the Matcher has rejected.

  • mismatch_description (Description) – The description to be built or appended to.

Return type:

None

with_title(title)[source]

Matches the title of the RSS feed entry.

Parameters:

title (str | Matcher[str]) – Expected title string or a matcher for the title.

Return type:

Self

Returns:

This matcher instance for chaining.

and_title(title)

Matches the title of the RSS feed entry.

Parameters:

title (str | Matcher[str]) – Expected title string or a matcher for the title.

Return type:

Self

Returns:

This matcher instance for chaining.

Matches the link URL of the RSS feed entry.

Parameters:

link (URL | Matcher[URL]) – Expected link URL or a matcher for the link.

Return type:

Self

Returns:

This matcher instance for chaining.

Matches the link URL of the RSS feed entry.

Parameters:

link (URL | Matcher[URL]) – Expected link URL or a matcher for the link.

Return type:

Self

Returns:

This matcher instance for chaining.

with_description(description)[source]

Matches the description of the RSS feed entry.

Parameters:

description (str | Matcher[str]) – Expected description string or a matcher for the description.

Return type:

Self

Returns:

This matcher instance for chaining.

and_description(description)

Matches the description of the RSS feed entry.

Parameters:

description (str | Matcher[str]) – Expected description string or a matcher for the description.

Return type:

Self

Returns:

This matcher instance for chaining.

with_published(published)[source]

Matches the publication datetime of the RSS feed entry.

Parameters:

published (datetime | Matcher[datetime | None] | None) – Expected publication datetime or a matcher for the published date.

Return type:

Self

Returns:

This matcher instance for chaining.

and_published(published)

Matches the publication datetime of the RSS feed entry.

Parameters:

published (datetime | Matcher[datetime | None] | None) – Expected publication datetime or a matcher for the published date.

Return type:

Self

Returns:

This matcher instance for chaining.

with_authors(authors)[source]

Matches the list of author names for the RSS feed entry.

Parameters:

authors (Sequence[str] | Matcher[Sequence[str]]) – Expected sequence of author names or a matcher for the authors.

Return type:

Self

Returns:

This matcher instance for chaining.

and_authors(authors)

Matches the list of author names for the RSS feed entry.

Parameters:

authors (Sequence[str] | Matcher[Sequence[str]]) – Expected sequence of author names or a matcher for the authors.

Return type:

Self

Returns:

This matcher instance for chaining.

with_categories(categories)[source]

Matches the list of categories (tags) for the RSS feed entry.

Parameters:

categories (list[FeedParserDict] | Matcher[list[FeedParserDict]]) – Expected list of categories or a matcher for the categories.

Return type:

Self

Returns:

This matcher instance for chaining.

and_categories(categories)

Matches the list of categories (tags) for the RSS feed entry.

Parameters:

categories (list[FeedParserDict] | Matcher[list[FeedParserDict]]) – Expected list of categories or a matcher for the categories.

Return type:

Self

Returns:

This matcher instance for chaining.

class brunns.matchers.rss.RssCategoryMatcher[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 (FeedParserDict) – 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 (FeedParserDict) – The item that the Matcher has accepted.

  • match_description (Description) – The description to be built or appended to.

Return type:

None

with_text(text)[source]

Matches the category text (term) of the RSS category.

Parameters:

text (str | Matcher[str]) – Expected category text string or a matcher for the text.

Return type:

Self

Returns:

This matcher instance for chaining.

and_text(text)

Matches the category text (term) of the RSS category.

Parameters:

text (str | Matcher[str]) – Expected category text string or a matcher for the text.

Return type:

Self

Returns:

This matcher instance for chaining.

with_domain(domain)[source]

Matches the domain (scheme URL) of the RSS category.

Parameters:

domain (URL | Matcher[URL]) – Expected domain URL or a matcher for the domain.

Return type:

Self

Returns:

This matcher instance for chaining.

and_domain(domain)

Matches the domain (scheme URL) of the RSS category.

Parameters:

domain (URL | Matcher[URL]) – Expected domain URL or a matcher for the domain.

Return type:

Self

Returns:

This matcher instance for chaining.

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.

Requires brunns-matchers to have been installed with the rss extra.

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.

Requires brunns-matchers to have been installed with the rss extra.

Return type:

RssFeedEntryMatcher

Returns:

A matcher for an RSS feed entry.

brunns.matchers.rss.is_rss_category()[source]

Matches a single RSS category.

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

Requires brunns-matchers to have been installed with the rss extra.

Return type:

RssCategoryMatcher

Returns:

A matcher for an RSS category.

The “brunns.matchers.scripttest” module

PyHamcrest matchers for scripttest ProcResult objects.

class brunns.matchers.scripttest.ProcResultProtocol(*args, **kwargs)[source]

Structural typing for scripttest.ProcResult objects.

brunns.matchers.scripttest.is_proc_result()[source]

Matches a scripttest.ProcResult object.

This function returns a ProcResultMatcher which can be refined using builder methods (e.g. .with_returncode(0)).

Return type:

ProcResultMatcher

Returns:

A matcher for scripttest ProcResult objects.

class brunns.matchers.scripttest.ProcResultMatcher(*, returncode=<IsAnything(ANYTHING)>, stdout=<IsAnything(ANYTHING)>, stderr=<IsAnything(ANYTHING)>, args=<IsAnything(ANYTHING)>, stdin=<IsAnything(ANYTHING)>, files_created=<IsAnything(ANYTHING)>, files_deleted=<IsAnything(ANYTHING)>, files_updated=<IsAnything(ANYTHING)>)[source]

Matches scripttest.ProcResult.

Parameters:
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:
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:
Return type:

None

with_returncode(returncode)[source]

Matches if the return code matches the given value or matcher.

Parameters:

returncode (int | Matcher[int]) – The expected return code (e.g. 0) or a matcher.

Return type:

Self

Returns:

Self, for chaining.

and_returncode(returncode)

Matches if the return code matches the given value or matcher.

Parameters:

returncode (int | Matcher[int]) – The expected return code (e.g. 0) or a matcher.

Return type:

Self

Returns:

Self, for chaining.

with_stdout(stdout)[source]

Matches if the stdout text matches the given value or matcher.

Parameters:

stdout (str | Matcher[str]) – The expected stdout string or matcher.

Return type:

Self

Returns:

Self, for chaining.

and_stdout(stdout)

Matches if the stdout text matches the given value or matcher.

Parameters:

stdout (str | Matcher[str]) – The expected stdout string or matcher.

Return type:

Self

Returns:

Self, for chaining.

with_stderr(stderr)[source]

Matches if the stderr text matches the given value or matcher.

Parameters:

stderr (str | Matcher[str]) – The expected stderr string or matcher.

Return type:

Self

Returns:

Self, for chaining.

and_stderr(stderr)

Matches if the stderr text matches the given value or matcher.

Parameters:

stderr (str | Matcher[str]) – The expected stderr string or matcher.

Return type:

Self

Returns:

Self, for chaining.

with_args(args)[source]

Matches if the command arguments match the given value or matcher.

Parameters:

args (Sequence[str] | Matcher[Sequence[str]]) – The expected args sequence or matcher.

Return type:

Self

Returns:

Self, for chaining.

and_args(args)

Matches if the command arguments match the given value or matcher.

Parameters:

args (Sequence[str] | Matcher[Sequence[str]]) – The expected args sequence or matcher.

Return type:

Self

Returns:

Self, for chaining.

with_stdin(stdin)[source]

Matches if the stdin bytes match the given value or matcher.

Parameters:

stdin (bytes | Matcher[bytes]) – The expected stdin bytes or matcher.

Return type:

Self

Returns:

Self, for chaining.

and_stdin(stdin)

Matches if the stdin bytes match the given value or matcher.

Parameters:

stdin (bytes | Matcher[bytes]) – The expected stdin bytes or matcher.

Return type:

Self

Returns:

Self, for chaining.

with_files_created(files_created)[source]

Matches if the files created dictionary matches the given value or matcher.

Parameters:

files_created (Mapping[str, Any] | Matcher[Mapping[str, Any]]) – The expected files created dictionary or matcher.

Return type:

Self

Returns:

Self, for chaining.

and_files_created(files_created)

Matches if the files created dictionary matches the given value or matcher.

Parameters:

files_created (Mapping[str, Any] | Matcher[Mapping[str, Any]]) – The expected files created dictionary or matcher.

Return type:

Self

Returns:

Self, for chaining.

with_files_deleted(files_deleted)[source]

Matches if the files deleted dictionary matches the given value or matcher.

Parameters:

files_deleted (Mapping[str, Any] | Matcher[Mapping[str, Any]]) – The expected files deleted dictionary or matcher.

Return type:

Self

Returns:

Self, for chaining.

and_files_deleted(files_deleted)

Matches if the files deleted dictionary matches the given value or matcher.

Parameters:

files_deleted (Mapping[str, Any] | Matcher[Mapping[str, Any]]) – The expected files deleted dictionary or matcher.

Return type:

Self

Returns:

Self, for chaining.

with_files_updated(files_updated)[source]

Matches if the files updated dictionary matches the given value or matcher.

Parameters:

files_updated (Mapping[str, Any] | Matcher[Mapping[str, Any]]) – The expected files updated dictionary or matcher.

Return type:

Self

Returns:

Self, for chaining.

and_files_updated(files_updated)

Matches if the files updated dictionary matches the given value or matcher.

Parameters:

files_updated (Mapping[str, Any] | Matcher[Mapping[str, Any]]) – The expected files updated dictionary or matcher.

Return type:

Self

Returns:

Self, for chaining.

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(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 (str) – 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.

Return type:

Self

Returns:

Self, for chaining.

and_to_name(to_name)

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

Parameters:

to_name (str | Matcher[str]) – The expected recipient name or matcher.

Return type:

Self

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.

Return type:

Self

Returns:

Self, for chaining.

and_to_address(to_address)

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.

Return type:

Self

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.

Return type:

Self

Returns:

Self, for chaining.

and_from_name(from_name)

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

Parameters:

from_name (str | Matcher[str]) – The expected sender name or matcher.

Return type:

Self

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.

Return type:

Self

Returns:

Self, for chaining.

and_from_address(from_address)

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.

Return type:

Self

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.

Return type:

Self

Returns:

Self, for chaining.

and_subject(subject)

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

Parameters:

subject (str | Matcher[str]) – The expected subject string or matcher.

Return type:

Self

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.

Return type:

Self

Returns:

Self, for chaining.

and_body_text(body_text)

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

Parameters:

body_text (str | Matcher[str]) – The expected body string or matcher.

Return type:

Self

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:
Return type:

Matcher

Returns:

A matcher for email strings.

The “brunns.matchers.url” module

class brunns.matchers.url.UrlProtocol(*args, **kwargs)[source]

Structural typing for URL objects.

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

Requires brunns-matchers to have been installed with the url extra.

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:
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:
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:
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.

Return type:

Self

Returns:

UrlWith, for chaining.

and_scheme(scheme)

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

Parameters:

scheme (str | Matcher[str]) – The expected scheme (e.g. “https”) or matcher.

Return type:

Self

Returns:

UrlWith, for chaining.

with_username(username)[source]

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

Parameters:

username (str | Matcher[str | None] | None) – The expected username or matcher.

Return type:

Self

Returns:

UrlWith, for chaining.

and_username(username)

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

Parameters:

username (str | Matcher[str | None] | None) – The expected username or matcher.

Return type:

Self

Returns:

UrlWith, for chaining.

with_user(username)

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

Parameters:

username (str | Matcher[str | None] | None) – The expected username or matcher.

Return type:

Self

Returns:

UrlWith, for chaining.

and_user(username)

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

Parameters:

username (str | Matcher[str | None] | None) – The expected username or matcher.

Return type:

Self

Returns:

UrlWith, for chaining.

with_password(password)[source]

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

Parameters:

password (str | Matcher[str | None] | None) – The expected password or matcher.

Return type:

Self

Returns:

UrlWith, for chaining.

and_password(password)

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

Parameters:

password (str | Matcher[str | None] | None) – The expected password or matcher.

Return type:

Self

Returns:

UrlWith, for chaining.

with_host(host)[source]

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

Parameters:

host (str | Matcher[str | None] | None) – The expected hostname or matcher.

Return type:

Self

Returns:

UrlWith, for chaining.

and_host(host)

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

Parameters:

host (str | Matcher[str | None] | None) – The expected hostname or matcher.

Return type:

Self

Returns:

UrlWith, for chaining.

with_port(port)[source]

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

Parameters:

port (int | Matcher[int | None] | None) – The expected port integer or matcher.

Return type:

Self

Returns:

UrlWith, for chaining.

and_port(port)

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

Parameters:

port (int | Matcher[int | None] | None) – The expected port integer or matcher.

Return type:

Self

Returns:

UrlWith, 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.

Return type:

Self

Returns:

UrlWith, for chaining.

and_path(path)

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.

Return type:

Self

Returns:

UrlWith, 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.

Return type:

Self

Returns:

UrlWith, for chaining.

and_path_segments(path_segments)

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.

Return type:

Self

Returns:

UrlWith, 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.

Return type:

Self

Returns:

UrlWith, for chaining.

and_query(query)

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.

Return type:

Self

Returns:

UrlWith, 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.

Return type:

Self

Returns:

UrlWith, for chaining.

and_fragment(fragment)

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

Parameters:

fragment (str | Matcher[str]) – The expected fragment string or matcher.

Return type:

Self

Returns:

UrlWith, 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

class brunns.matchers.werkzeug.ResponseProtocol(*args, **kwargs)[source]

Structural typing for Werkzeug Response objects.

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(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:
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:
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:

Self

Returns:

Self, for chaining.

and_status_code(status_code)

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:

Self

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:

Self

Returns:

Self, for chaining.

and_text(text)

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:

Self

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:

Self

Returns:

Self, for chaining.

and_mimetype(mimetype)

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

Parameters:

mimetype (str | Matcher[str]) – The expected mimetype string or matcher.

Return type:

Self

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 (str | int | float | bool | Sequence[str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | Mapping[str, str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | None | Matcher[str | int | float | bool | Sequence[str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | Mapping[str, str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | None]) – The expected JSON structure or matcher.

Return type:

Self

Returns:

Self, for chaining.

and_json(json)

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

The response body is parsed as JSON before matching.

Parameters:

json (str | int | float | bool | Sequence[str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | Mapping[str, str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | None | Matcher[str | int | float | bool | Sequence[str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | Mapping[str, str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None] | None]) – The expected JSON structure or matcher.

Return type:

Self

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:

Self

Returns:

Self, for chaining.

and_headers(headers)

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:

Self

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

Returns:

A matcher for redirect responses.