接口

interface ActionSelector<R>

public interface ActionSelector<R> {
    func returns(value: R): CardinalitySelector<R>
    func returns(valueFactory: () -> R): CardinalitySelector<R>
    func returnsConsecutively(values: Array<R>): Continuation<R>
    func returnsConsecutively(values: ArrayList<R>): Continuation<R>
    func throws(exception: Exception): CardinalitySelector<R>
    func throws(exceptionFactory: () -> Exception): CardinalitySelector<R>
    func fails(): Unit
    func callsOriginal(): CardinalitySelector<R>
}

功能：此接口提供了为成员函数指定一个操作 API ，并允许链式调用。入参为 mock object 或 spy object 的某个成员函数的调用表达式的 @On 宏调用表达式，将返回 ActionSelector<R> 的实例（其中 R 代表正在配置的函数成员的返回值类型）。即，此接口中的 API 可为成员函数插入桩代码。

func callsOriginal()

func callsOriginal(): CardinalitySelector<R>

功能：定义桩签名执行原始代码逻辑的行为。

返回值：

CardinalitySelector<R> - 定义了桩签名执行原始代码逻辑的 CardinalitySelector<R> 对象实例。

func fails()

func fails(): Unit

功能：定义桩签名抛出 AssertionException 异常的行为。

说明：

throws vs fails

throws 意味着测试桩签名抛出异常后的行为是测试的目的。例如，当某些服务不可用时，系统是否可以正确恢复等。 fails 意味着调用桩签名将导致测试失败。即，如果系统行为正确，则永远不应调用该桩签名。

func returns(() -> R)

func returns(valueFactory: () -> R): CardinalitySelector<R>

功能：定义桩签名返回指定的值的行为，该值由传入的闭包生成。

参数：

valueFactory: () ->R - 生成预期返回值的闭包函数（生成器）。

返回值：

CardinalitySelector<R> - 定义了桩签名返回指定值的行为的 CardinalitySelector<R> 对象实例。

func returns(R)

func returns(value: R): CardinalitySelector<R>

功能：定义桩签名返回指定值的行为。

参数：

value: R - 预期桩签名的返回值。

返回值：

CardinalitySelector<R> - 定义了桩签名返回行为的 CardinalitySelector<R> 对象实例。

func returnsConsecutively(Array<R>)

func returnsConsecutively(values: Array<R>): Continuation<R>

功能：定义桩签名按列表顺序返回指定的值的行为。桩签名将被调用多次，次数与数组内值的个数相同。

参数：

values: Array<R> - 桩签名的返回值列表。

返回值：

Continuation<R> - 定义了桩签名按序返回指定值的行为的 Continuation<R> 对象实例。

异常：

IllegalArgumentException - 当参数列表为空时，抛出异常。

func returnsConsecutively(ArrayList<R>)

func returnsConsecutively(values: ArrayList<R>): Continuation<R>

功能：定义桩签名按列表顺序返回指定的值的行为。桩签名将被连续调用多次，次数与数组列表内值的个数相同。

参数：

values: ArrayList<R> - 桩签名的返回值列表。

返回值：

Continuation<R> - 定义了桩签名按序返回指定值的 Continuation<R> 对象实例。

异常：

IllegalArgumentException - 当参数列表为空时，抛出异常。

func throws(() -> Exception)

func throws(exceptionFactory: () -> Exception): CardinalitySelector<R>

功能：定义桩签名抛出异常的行为，异常由参数闭包函数生成。

参数：

exceptionFactory: () ->Exception - 构造预期桩签名抛出的异常对象的闭包函数（生成器）。

返回值：

CardinalitySelector<R> - 定义了桩签名抛出异常行为的 CardinalitySelector<R> 对象实例。

func throws(Exception)

func throws(exception: Exception): CardinalitySelector<R>

功能：定义桩签名抛出异常的行为。

参数：

exception: Exception - 预期桩签名抛出的异常对象。

返回值：

CardinalitySelector<R> - 定义了桩签名抛出异常的行为的 CardinalitySelector<R> 对象实例。

interface CardinalitySelector<R>

public interface CardinalitySelector<R> {
    func anyTimes(): Unit
    func once(): Continuation<R>
    func atLeastOnce(): Unit
    func times(expectedTimes: Int64): Continuation<R>
    func times(min!: Int64, max!: Int64): Unit
    func atLeastTimes(minTimesExpected: Int64): Unit
}

功能：此接口提供了可定义桩签名的最近一次行为的执行次数的 API 。该实例仅可被 ActionSelector<R> 的 API 生成（其中 R 代表桩签名的返回类型）。例如：@On(foo.bar()).returns("Predefined value").atLeastOnce() 。为方便表达，后文将桩签名的最近一次行为称为“桩行为”。此接口提供的 API 提供的验证能力如下：

桩签名的调用次数超过指定次数将立即抛出 ExpectationFailedException 。
桩签名的调用次数不足时，框架将在测试用例执行完成后抛出 ExceptionFailedException 。

func atLeastOnce()

func atLeastOnce(): Unit

功能：定义“桩行为”最少被执行一次。验证不到一次时，抛出异常。

异常：

ExpectationFailedException - 验证“桩行为”执行次数不到一次时，抛出异常。

func atLeastTimes(Int64)

func atLeastTimes(minTimesExpected: Int64): Unit

功能：定义“桩行为”最少被执行指定次数的行为。验证实际执行次数低于最少指定次数时，抛出异常。

参数：

minTimesExpected: Int64 - 预期“桩行为”最少被执行的次数。

异常：

ExpectationFailedException - 验证“桩行为”执行少于指定次数时，抛出异常。

func once()

func once(): Continuation<R>

功能：定义“桩行为”仅被执行一次。此函数将在验证桩签名执行次数超出一次时，抛出异常。

返回值：

Continuation<R> - 定义了验证“桩行为”仅被执行一次的行为的 Continuation<R> 对象实例。

异常：

ExpectationFailedException - 验证“桩行为”执行次数超过一次时，立即抛出异常。

func times(Int64)

func times(expectedTimes: Int64): Continuation<R>

功能：定义“桩行为”被执行指定次数。验证不是指定次数时，抛出异常。

参数：

expectedTimes: Int64 - 预期“桩行为”被执行的次数。

返回值：

Continuation<R> - 定义了验证“桩行为”被执行指定次数的行为的 Continuation<R> 对象实例。

异常：

ExpectationFailedException - 验证“桩行为”执行次数不是指定次数时，抛出异常。

func times(Int64, Int64)

func times(min!: Int64, max!: Int64): Unit

功能：定义“桩行为”执行指定次数范围。验证超出指定次数范围时，抛出异常。

参数：

min!: Int64 - 预期“桩行为”被执行的最小次数。
max!: Int64 - 预期“桩行为”被执行的最大次数。

异常：

ExpectationFailedException - 验证“桩行为”执行次数不是指定次数范围时，抛出异常。

interface ContinuationSelector<R>

public interface Continuation<R> {
    func then(): ActionSelector<R>
}

功能：此接口提供了可继续定义桩签名的行为的 API 。该实例可由ActionSelector<R> 或 CardinalitySelector<R> 的 API 调用后生成。此接口提供的接口能力如下：

允许当先前的操作得到满足时，桩签名将执行额外的操作。仅当后面跟着一个行为定义时，Continuation 实例才有意义。
当先前的操作未得到满足时，将抛出 MockFrameworkException 异常。并不保证抛出此异常的确切位置。

func then()

func then(): ActionSelector<R>

功能：当链中的先前操作完成时，返回 ActionSelector<R> 对象。

返回值：

ActionSelector<R> - ActionSelector<R> 对象实例。

异常：

MockFrameworkException - 当先前的操作未得到满足时，将抛出异常。

interface ValueListener<T>

public interface ValueListener<T> {
    func lastValue(): Option<T>
    func allValues(): Array<T>
    func addCallback(callback: (T) -> Unit): Unit
    static func new(): ValueListener<T>
    static func onEach(callback: (T) -> Unit): ValueListener<T>
}

功能：此接口提供了多个成员函数以支持“监听”传入给桩签名的参数。即对每次调用中传入桩签名的参数进行指定的操作（ addCallback() 或 onEach 中的闭包函数即为对参数进行的操作内容）。一般与参数匹配器生成函数 argThat 或者 capture 配合使用。值侦听器与参数捕获器一同作为参数匹配器的一种被传入到桩签名中，作为入参。在定义桩签名的参数值范围的同时检查参数值。

举例来说：

struct Animal {
    Animal(
        let name: String,
        let info: String
    ) {}
}

abstract class AnimalUi {
    func showAnimal(animal: Animal): Unit
}

let animals = [Animal("Smokey", "Cat, age: 5"), Animal("Daisy", "Dog, age: 9")]

@Test func testAnimal(): Unit {
    let ui = mock<AnimalUi>()
    // 定义了一个值监听器：检查每个值，当值不满足条件时抛出异常
    let listener = ValueListener<Animal>.onEach { animal =>
        if (animal.name == "Smokey") {
            @Assert(animal.info.contains("Cat"))
        }
    }
    // 定义一个桩签名的“桩行为”，参数匹配器为可执行上述值监听器的参数捕获器
    @On(ui.showAnimal(capture(listener))).returns(())

    for (animal in animals) {
        // 此处将捕获传入的 animal 对象，并对其执行值监听器中的检查行为。
        ui.showAnimal(animal)
    }
}

func addCallback((T) -> Unit)

func addCallback(callback: (T) -> Unit): Unit

功能：为当前“值监听器”对象增加闭包函数，该函数将处理传入的参数值。

参数：

callback: (T) ->Unit - 处理参数值的闭包函数

func allValues()

func allValues(): Array<T>

功能：返回当前“值监听器”对象已所处理的所有值。

返回值：

Array<T> - 返回“值监听器”对象所处理的所有值列表

func lastValue()

func lastValue(): Option<T>

功能：返回当前“值监听器”对象所处理的最后一个值。

返回值：

Option<T> - 返回“值监听器”对象所处理的最后一个值，不存在时，返回 None 。

func new()

static func new(): ValueListener<T>

功能：创建一个新的“值监听器”对象，不包含任何处理参数的闭包方法。

返回值：

ValueListener<T> - “值监听器”对象

func onEach((T) -> Unit)

static func onEach(callback: (T) -> Unit): ValueListener<T>

功能：创建一个新的“值监听器”对象，带有一个处理参数的闭包方法。

参数：

callback: (T) ->Unit - 处理参数值的闭包函数。

返回值：

ValueListener<T> - “值监听器”对象。

仓颉语言库 API