Matcher

public struct Matcher<T>
extension Matcher: AsyncableMatcher

A Matcher is part of the new matcher API that provides assertions to expectations.

Given a code snippet:

expect(1).to(equal(2)) ^^^^^^^^ Called a “matcher”

A matcher consists of two parts a constructor function and the Matcher.

The Matcher provide the heavy lifting on how to assert against a given value. Internally, matchers are simple wrappers around closures to provide static type information and allow composition and wrapping of existing behaviors.

In the 2023 Apple Platform releases (macOS 14, iOS 17, watchOS 10, tvOS 17, visionOS 1), Apple renamed NSMatcher to Matcher. In response, we decided to rename Matcher to Matcher.

  • Constructs a matcher that knows how take a given value

    Declaration

    Swift

    public init(_ matcher: @escaping (Expression<T>) throws -> MatcherResult)
  • Uses a matcher on a given value to see if it passes the matcher.

    @param expression The value to run the matcher’s logic against @returns A matcher result indicate passing or failing and an associated error message.

    Declaration

    Swift

    public func satisfies(_ expression: Expression<T>) throws -> MatcherResult
  • satisfies(_:) Asynchronous

    Undocumented

    Declaration

    Swift

    public func satisfies(_ expression: AsyncExpression<T>) async throws -> MatcherResult
  • Like Matcher() constructor, but automatically guard against nil (actual) values

    Declaration

    Swift

    public static func define(matcher: @escaping (Expression<T>) throws -> MatcherResult) -> Matcher<T>
  • Defines a matcher with a default message that can be returned in the closure Also ensures the matcher’s actual value cannot pass with nil given.

    Declaration

    Swift

    public static func define(_ message: String = "match", matcher: @escaping (Expression<T>, ExpectationMessage) throws -> MatcherResult) -> Matcher<T>
  • Defines a matcher with a default message that can be returned in the closure Unlike define, this allows nil values to succeed if the given closure chooses to.

    Declaration

    Swift

    public static func defineNilable(_ message: String = "match", matcher: @escaping (Expression<T>, ExpectationMessage) throws -> MatcherResult) -> Matcher<T>
  • Provides a simple matcher definition that provides no control over the predefined error message.

    Also ensures the matcher’s actual value cannot pass with nil given.

    Declaration

    Swift

    public static func simple(_ message: String = "match", matcher: @escaping (Expression<T>) throws -> MatcherStatus) -> Matcher<T>
  • Provides a simple matcher definition that provides no control over the predefined error message.

    Unlike simple, this allows nil values to succeed if the given closure chooses to.

    Declaration

    Swift

    public static func simpleNilable(_ message: String = "match", matcher: @escaping (Expression<T>) throws -> MatcherStatus) -> Matcher<T>
  • Returns a new Matcher based on the current one that always fails if nil is given as the actual value.

    Declaration

    Swift

    public var requireNonNil: Matcher<T> { get }