类

class Matchers

public class Matchers {}

功能：该类提供生成匹配器的静态函数。匹配器对象仅可通过此处的静态函数生成。匹配器可在桩链中使用。

例如：@On(foo.bar(ofType<Int64>())).returns(1)

参数匹配器可以在 @On 宏调用表达式入参处使用，来描述期望将哪些参数传递到桩签名中。参数匹配器有两个最常见的用途：

为不同的参数指定不同的行为。例如：

// 当 bar 的入参为 5 时，返回某个值
@On(foo.bar(eq(5))).returns(...)
// 当 bar 的入参为 6 时，抛出异常
@On(foo.bar(eq(6))).throws(...)

确保只有某些参数被传递到某些桩签名中。

let foo = mock<Foo>()
// bar 的入参只能为正数，否则将抛出 UnhandledCallException 异常
@On(foo.bar(argThat<Int64> { arg => arg > 0 })).returns(...)

注意：

上例仅适用于 mock object 。spy object 的行为不同。

let foo = spy(Foo())
// 当 bar 的入参不为正数时，将调用 Foo() 对象的成员函数。
@On(foo.bar(argThat<Int64> { arg => arg <= 0 })).fails()

static func any()

public static func any(): AnyMatcher

功能：允许将任何值作为参数。

返回值：

AnyMatcher - 允许任意值的参数匹配器。

static func argThat<T>(ValueListener<T>, (T) -> Bool)

public static func argThat<T>(listener: ValueListener<T>, predicate: (T) -> Bool): TypedMatcher<T>

功能：通过传入的 predicate 闭包函数过滤传入的参数值，允许 listener 值监听器对满足条件的传入参数值进行处理。

参数：

listener: ValueListener<T> - 值监听器。
predicate: (T) ->Bool - 过滤器，可通过此函数定义过滤参数值的匹配条件。

返回值：

TypedMatcher<T> - 拥有值监听器和过滤器的类型匹配器。

static func argThat<T>((T) -> Bool)

public static func argThat<T>(predicate: (T) -> Bool): TypedMatcher<T>

功能：根据提供的过滤器闭包过滤输入值。

参数：

predicate: (T) ->Bool - 过滤器。

返回值：

TypedMatcher<T> - 参数过滤类型匹配器实例。

static func capture<T>(ValueListener<T>)

public static func capture<T>(listener: ValueListener<T>): TypedMatcher<T>

允许 listener 值监听器对类型为 T 的传入参数值进行处理。当 capture 的类型参数未指定时，将使用值监听器的类型参数值。

参数：

listener: ValueListener<T> - 值监听器。

返回值：

TypedMatcher<T> - 拥有值监听器的类型匹配器。

注意：值监听器不允许在 @Called 的参数范围内使用。

static func default<T>(T)

public static func default<T>(target: T): TypedMatcher<T>

功能：根据结构（更高优先级）或引用相等性来匹配值。如果传入的参数既不是 Equatable<T> 也不是引用类型，则会在运行时抛出异常（编译期不做检查）。

参数：

target: T - 必须通过结构或引用相等来匹配的匹配对象。

返回值：

TypedMatcher<T> - 默认类型匹配器。

异常：

MockFrameworkException - 如果参数 target 既不是 Equatable<T> 类型也不是引用类型，则抛出异常。

static func eq<T>(T)

public static func eq<T>(target: T): TypedMatcher<T> where T <: Equatable<T>

功能：根据与提供的值的结构相等性过滤输入值。

参数：

target: T - 匹配对象。

返回值：

TypedMatcher<T> - 仅允许结构上等于给定值的参数匹配器。

static func ofType<T>()

public static func ofType<T>(): TypedMatcher<T>

功能：根据类型过滤输入值。

返回值：

TypedMatcher<T> - 仅允许特定类型的类型匹配器。

static func same<T>(T) where T <: Object

public static func same<T>(target: T): TypedMatcher<T> where T <: Object

功能：根据与所提供对象的引用相等性来过滤输入值。

参数：

target: T - 匹配对象。

返回值：

TypedMatcher<T> - 仅允许与给定对象引用相等的参数的参数匹配器。

class OrderedVerifier

public class OrderedVerifier {}

功能：此类型用于收集 “验证语句”，可在 ordered 函数中动态传入验证行为。

func checkThat(VerifyStatement)

public func checkThat(statement: VerifyStatement): OrderedVerifier

功能：添加一条 “验证语句”。

参数：

statement: VerifyStatement - 待被添加的“验证语句”。

返回值：

OrderedVerifier - 返回对象自身。

class UnorderedVerifier

public class UnorderedVerifier{
    public func checkThat(statement: VerifyStatement):UnorderedVerifier
}

功能：此类型用于收集 “验证语句”，可在 unordered 函数中动态传入验证行为。

func checkThat(VerifyStatement)

public func checkThat(statement: VerifyStatement):UnorderedVerifier

功能：添加一条 “验证语句”。

参数：

statement: VerifyStatement - 待被添加的“验证语句”。

返回值：

UnorderedVerifier - 返回对象自身。

class Verify

public class Verify {}

功能：Verify 提供了一系列静态方法来支持定义所需验证的动作，如 that 、 ordered 以及 unorder 。

一个验证动作可以包含多个由 @Called 生成的验证语句，来描述需要验证的动作。通常验证的范围为所在测试用例的函数体，但 Verify 提供了 clearInvocationLog 函数来清除此前的执行记录，以缩小验证范围。行为验证是指，验证“桩签名”的操作是否按所定义的方式执行，当验证实际执行与定义不一致时，将抛出异常。

具体支持验证的行为如下：

所指定的“桩签名”是否被执行。
所指定的“桩签名”是否执行指定的次数。
所指定的“桩签名”在执行时，被传入的参数是否满足要求。
所指定的多个“桩签名”的调用顺序是否满足要求。

行为验证主要通过以下两个步骤完成：

通过调用 Verify 的静态方法定义一个验证动作。
通过 @Called 宏调用表达式定义所需验证的 “桩签名”的执行动作。为简化表达，后文将其称为“验证语句”。

举例来说：

let foo = mock<Foo>()
// 定义“桩签名”的“桩行为”
@On(foo.bar().returns(1))
// 实际“桩签名”在用例中的执行情况
foo.bar()
// 验证“桩签名”的执行情况：foo.bar() 至少执行了一次
Verify.that(@Called(foo.bar()))

值得注意的是， CardinalitySelector<R> 提供了一些 API ，其支持验证一些行为。因此，用户可自由选择不同的方式进行行为验证。

static func clearInvocationLog()

public static func clearInvocationLog(): Unit

功能：清除前序的执行记录，以缩小验证范围。

static func noInteractions(Array<Object>)

public static func noInteractions(mocks: Array<Object>): Unit

功能：在验证范围内，对象没有任何执行动作时，验证通过。

参数：

mocks: Array<Object> - 被验证的对象列表。

异常：

VerificationFailedException - 验证不通过时，抛出异常。

static func ordered((OrderedVerifier) -> Unit)

public static func ordered( collectStatements: (OrderedVerifier) -> Unit): Unit

功能：此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义，并且校验执行顺序。默认情况下，“验证语句”的执行次数为一次。传入列表中的“验证语句”必须是不相交的（即当单个调用行为，可以匹配多个“验证语句”时，将抛出异常）。 “验证语句”通过入参中的闭包动态增加。验证模式为 exhaustive (全量匹配，验证范围内的所有执行情况都应在验证动作中被指定)。

参数：

collectStatements: (OrderedVerifier) ->Unit - 支持可动态增加“验证语句”的闭包。

异常：

VerificationFailedException - 验证不通过时，抛出异常。

static func ordered(Array<VerifyStatement>)

public static func ordered(statements: Array<VerifyStatement>): Unit

功能：此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义，并且校验执行顺序。默认情况下，“验证语句”的执行次数为一次。传入列表中的“验证语句”必须是不相交的（即当单个调用行为，可以匹配多个“验证语句”时，将抛出异常）。验证模式为 exhaustive (全量匹配，验证范围内的所有执行情况都应在验证动作中被指定)。

举例来说:

for (i in 0..4) {
    foo.bar(i % 2)
}

Verify.ordered(
    @Called(foo.bar(0)),
    @Called(foo.bar(1)),
    @Called(foo.bar(0)),
    @Called(foo.bar(1)),
)

// 将抛出异常，验证范围内有 4 次 foo.bar() 表达式的执行动作，此处只验证了2次执行。
Verify.ordered(
    @Called(foo.bar(0)),
    @Called(foo.bar(_)),
)

static func that(VerifyStatement)

public static func that(statement: VerifyStatement): Unit

功能：验证是否正确执行了传入的单个“验证语句”。

参数：

statement: VerifyStatement - 所需验证的“验证语句”。

异常：

VerificationFailedException - 验证不通过时，将抛出异常。

static func unordered((UnorderedVerifier) -> Unit)

public static func unordered(collectStatements: (UnorderedVerifier) -> Unit): Unit

功能：此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义，并且不校验执行顺序。默认情况下，“验证语句”的执行次数为至少一次。传入列表中的“验证语句”必须是不相交的（即当单个调用行为，可以匹配多个“验证语句”时，将抛出异常）。验证模式为 exhaustive (全量匹配，验证范围内的所有执行情况都应在验证动作中被指定)。 “验证语句”通过入参中的闭包动态增加。举例来说：


let totalTimes = getTimes()
for (i in 0..totalTimes) {
    foo.bar(i % 2)
}
// 通过闭包使得“验证语句”可以通过 totalTimes 的值确定内容
Verify.unordered { v =>
    for (j in 0..totalTimes) {
        v.checkThat(@Called(foo.bar(eq(j % 2))))
    }
}

参数：

collectStatements: (UnorderedVerifier) ->Unit - 支持可动态增加“验证语句”的闭包。

异常：

VerificationFailedException - 验证不通过时，抛出异常。

static func unordered(Array<VerifyStatement>)

public static func unordered(statements: Array<VerifyStatement>): Unit

举例来说:

let foo = mock<Foo>()
for (i in 0..4) {
    foo.bar(i % 2)
}

// 验证 bar() 在传入参数为 0 或 1 的情况下均至少执行一次
Verify.unordered(
    @Called(foo.bar(0)),
    @Called(foo.bar(1))
)

// 此处的验证动作将抛出异常，因为 `foo.bar(_)` 包含了 `foo.bar(1)`
Verify.unordered(
    @Called(foo.bar(_)).times(2),
    @Called(foo.bar(1)).times(2)
)
// 可以通过如下方式进行验证
// 验证入参为 1 的调用表达式执行了2次
Verify.that(@Called(foo.bar(1)).times(2))
// 验证任意入参的调用表达式执行了2次
Verify.that(@Called(foo.bar(_)).times(2)) // called four times in total

参数：

statements: Array<VerifyStatement> - 待验证的多条“验证语句”，变长参数语法支持参数省略 [] 。

异常：

VerificationFailedException - 验证不通过时，抛出异常。

static func unordered(Exhaustiveness, (UnorderedVerifier) -> Unit)

public static func unordered(exhaustive: Exhaustiveness, collectStatements: (UnorderedVerifier) -> Unit): Unit

功能：此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义，并且不校验执行顺序。默认情况下，“验证语句”的执行次数为至少一次。传入列表中的“验证语句”必须是不相交的（即当单个调用行为，可以匹配多个“验证语句”时，将抛出异常）。 “验证语句”通过入参中的闭包动态增加。

参数：

collectStatements: (UnorderedVerifier) ->Unit - 支持可动态增加“验证语句”的闭包。
exhaustive: Exhaustiveness - 验证模式

异常：

VerificationFailedException - 验证不通过时，抛出异常

static func unordered(Exhaustiveness, Array<VerifyStatement>)

public static func unordered(exhaustive: Exhaustiveness, statements: Array<VerifyStatement>): Unit

功能：此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义，并且不校验执行顺序。默认情况下，“验证语句”的执行次数为至少一次。传入列表中的“验证语句”必须是不相交的（即当单个调用行为，可以匹配多个“验证语句”时，将抛出异常）。

参数：

statements: Array<VerifyStatement> - 待验证的多条“验证语句”，变长参数语法支持参数省略 [] 。
exhaustive: Exhaustiveness - 验证模式。

异常：

VerificationFailedException - 验证不通过时，抛出异常。

class VerifyStatement

public class VerifyStatement {}

功能：此类型表示对“桩签名”在验证范围内的单个验证验证语句（即上文中的“验证语句”），提供了成员函数指定“桩签名”的执行次数。该类型的对象仅可通过 @Called 宏调用表达式创建。对一个对象连续调用多个成员函数没有意义，并且会抛出异常。即，执行次数仅可被指定一次。当未调用成员函数指定执行次数时，将基于语句所在的验证动作类型定义默认的执行次数验证值。例如在 Verify.ordered() 中的“验证语句”默认为验证执行一次。

func atLeastOnce()

public func atLeastOnce(): VerifyStatement

功能：指定此“验证语句”验证在验证范围内“桩签名”最少被执行一次。

返回值：

VerifyStatement - 返回对象自身。

异常：

MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时，将抛出异常。

func atLeastTimes(Int64)

public func atLeastTimes(minTimesExpected: Int64): VerifyStatement

功能：指定此“验证语句”验证在验证范围内“桩签名”最少执行指定的次数。

参数：

minTimesExpected: Int64 - 预期验证的执行最少次数。

返回值：

VerifyStatement - 返回对象自身。

异常：

MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时，将抛出异常。

func once()

public func once(): VerifyStatement

功能：指定此“验证语句”验证在验证范围内“桩签名”仅被执行一次。

返回值：

VerifyStatement - 返回对象自身。

异常：

MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时，将抛出异常。

func times(Int64)

public func times(expectedTimes: Int64): VerifyStatement

功能：指定此“验证语句”验证在验证范围内“桩签名”被执行指定次数。

参数：

expectedTimes: Int64 - 预期验证的执行次数。

返回值：

VerifyStatement - 返回对象自身。

异常：

MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时，将抛出异常。

func times(Int64, Int64)

public func times(min!: Int64, max!: Int64): VerifyStatement

功能：指定此“验证语句”验证在验证范围内“桩签名”的执行次数在指定范围内。

参数：

min!: Int64 - 预期验证的最小执行次数。
max!: Int64 - 预期验证的最大执行次数。

返回值：

VerifyStatement - 返回对象自身。

异常：

MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时，将抛出异常。

仓颉语言库 API