apex-mockery

<div align="center"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/e508f474-c842-4a36-852c-2796103fed91.png" width="256"> <h1>Apex轻量级模拟库</h1> </div>

本项目提供了一个简单、轻量、易读、经过充分测试的Apex模拟库，使用Apex Stub API构建。我们希望它使用简单、易于维护，并提供最佳的开发者体验。

<details> <summary>目录</summary>

原则
- 为什么要使用这个库
安装
- 命名空间组织注意事项 /!\
使用方法
库架构
如何迁移我的代码库？
作者
贡献
许可证

</details>

原则

API设计源于我们使用Mockito、chai.js、sinon.js和jest的经验。该库旨在为开发人员提供一种简单的方法来进行存根、模拟、监视和断言他们的实现。依赖注入和控制反转是被测系统应该实现的关键架构概念。

为什么要使用这个库

它可以帮助你在单元测试中将代码与其依赖项隔离。使用该库来模拟类的依赖项将有助于提高项目的代码质量和可维护性。

它通过驱动类依赖项的行为（而不是通过集成依赖它）来帮助你编写单元测试。使用该库来模拟测试中的DML和SOQL将帮助你在Apex测试执行中节省大量时间（测试将不再访问数据库）。

安装

通过部署按钮进行部署

或者将force-app/src/classes中的Apex类复制到你的sfdx项目中，使用你喜欢的部署方法进行部署

或者你可以使用我们的无命名空间的未锁定包从最新版本安装该库

命名空间组织注意事项 /!\

在带有命名空间的组织中无法安装无命名空间的未锁定包。

在这种情况下，你有以下选择：

从源代码安装（手动为类添加前缀或不添加）
创建包含源代码的带有你的命名空间的未锁定/2GP包

不建议2GP包依赖于未锁定包，无论是否有命名空间（ISV场景）。

使用方法

模拟

要模拟一个实例，使用Mock.forType方法它返回一个Mock实例，包含存根和所有用于监视/配置/断言的机制

Mock myMock = Mock.forType(MyType.class);

如何模拟带命名空间的类型？

由于Test.createStub()调用不能跨命名空间，我们提供了一个StubBuilder接口来模拟你的命名空间中的类型。在你的命名空间中创建一个StubBuilder实现（它必须与Mock.DefaultStubBuilder实现相同，但必须在你的命名空间中才能构建你的命名空间中的类型）。

Mock myMock = Mock.forType(MyType.class, new MyNamespace.MyStubBuilder());

存根

使用stub属性访问存根，

MyType myTypeStub = (MyType) myMock.stub;
MyService myServiceInstance = new MyServiceImpl(myTypeStub);

监视

使用mock的spyOn方法来监视一个方法，它返回一个MethodSpy实例，包含所有用于驱动其行为和监视它的工具

MethodSpy myMethodSpy = myMock.spyOn('myMethod');

如何配置spy

默认行为

默认情况下，无论接收到什么参数，spy在被调用时都会返回null。

// 执行
Object result = myTypeStub.myMethod();
// 断言
Assert.areEqual(null, result);

请查看NoConfiguration配方

全局返回

配置它返回一个特定值，无论接收到什么参数 stub将始终返回配置的值

// 准备
myMethodSpy.returns(new Account(Name='Test'));
// 执行
Object result = myTypeStub.myMethod();
// 断言
Assert.areEqual(new Account(Name='Test'), result);

请查看Returns配方

全局抛出

配置它抛出一个特定异常，无论接收到什么参数 stub将始终抛出配置的异常

// 准备
myMethodSpy.throwsException(new MyException());
try {
    // 执行
    Object result = myTypeStub.myMethod();

    // 断言
    Assert.fail('预期的异常未被抛出');
} catch (Exception ex) {
    Assert.isInstanceOfType(ex, MyException.class);
}

请查看Throws配方

参数化配置

配置它在使用特定参数调用时返回特定值配置它在使用特定参数调用时抛出特定值

// 准备
myMethodSpy
    .whenCalledWith(Argument.any(), 10)
    .thenReturn(new Account(Name='Test'));

// 准备
myMethodSpy
    .whenCalledWith(Argument.any(), -1)
    .thenThrow(new MyException);

// 执行
Object result = myTypeStub.myMethod('nothing', 10);

// 断言
Assert.areEqual(new Account(Name='Test'), result);

// 执行
try {
    Object result = myTypeStub.myMethod('value', -1);

    // 断言
    Assert.fail('预期的异常未被抛出');
} catch (Exception ex) {
    Assert.isInstanceOfType(ex, MyException.class);
}

请查看mocking配方以深入了解您可以使用mocking API做什么。

配置顺序很重要！

简而言之

spy配置的顺序决定了它的行为。

如果没有任何配置，则返回null（默认行为）。
然后，它检查whenCalledWith配置。
然后，它检查全局returns配置。
然后，它检查全局throwsException配置。

如果有配置但不匹配，则会抛出ConfigurationException。错误消息将包含参数和配置。使用它来帮助您理解问题的根本原因（配置/回归/您能想到的）。

全局配置的顺序很重要。如果全局抛出在全局返回之后设置，则会应用throwException。

myMethodSpy.returns(new Account(Name='Test'));
myMethodSpy.throwsException(new MyException());
Object result = myTypeStub.myMethod(); // 抛出异常

如果全局返回在全局抛出之后设置，则会应用returns

myMethodSpy.throwsException(new MyException());
myMethodSpy.returns(new Account(Name='Test'));
Object result = myTypeStub.myMethod(); // 返回配置的值

对于全局配置，最后配置的将被应用。就像如果您多次配置spy以返回（或抛出）一样，最后的全局配置将是保留的配置。

断言spy

使用Expect类来断言spy 它公开了that方法并返回一个MethodSpyExpectable类型。按以下方式使用便捷的断言方法：

// hasNotBeenCalled
Expect.that(myMethodSpy).hasNotBeenCalled();

// hasBeenCalled
Expect.that(myMethodSpy).hasBeenCalled();

// hasBeenCalledTimes
Expect.that(myMethodSpy).hasBeenCalledTimes(2);

// hasBeenCalledWith
Expect.that(myMethodSpy).hasBeenCalledWith('stringValue', Argument.any(), true, ...); // 最多5个参数
Expect.that(myMethodSpy).hasBeenCalledWith(Argument.ofList(new List<Object>{Argument.any(), Argument.any(), ... })); // 超过5个参数

// hasBeenLastCalledWith
Expect.that(myMethodSpy).hasBeenLastCalledWith('stringValue', Argument.any(), true, ...); // 最多5个参数
Expect.that(myMethodSpy).hasBeenLastCalledWith(Argument.ofList(new List<Object>{Argument.any(), Argument.any(), ... })); // 超过5个参数

请查看assertions配方以深入了解您可以使用断言API做什么

参数

配置stub（spy.whenCalledWith(...)）和断言（Expect.that(myMethodSpy).hasBeenCalledWith和Expect.that(myMethodSpy).hasBeenLastCalledWith）stub使用Argument.Matchable接口。

您可以使用原始值，如spy.whenCallWith('value1', false, ...)或hasBeenCalledWith(param1, param2, ...)，最多支持5个参数。

当使用任何类型的参数调用时，它会用Argument.equals包装值。

当使用Argument.Matchable类型调用时，它会将其视为参数，直接使用而不用Argument.equals包装。

如果您的方法调用需要更多参数，Argument提供了ofList API来为此创建参数，因此您可以执行spy.whenCallWith(Argument.ofList(new List<Object>{...}))或hasBeenCalledWith(Argument.ofList(new List<Object>{...}))

List<Argument.Matchable> emptyParameters = Argument.empty();

List<Argument.Matchable> myMethodParameters = Argument.of(10, 'string'); // 最多五个

List<Argument.Matchable> myMethodWithLongParameters = Argument.ofList(new List<Object>{10, 'string', true, 20, false, 'Sure'});

参数匹配器

该库提供现成的（OOTB）可匹配项，随时可用且经过全面测试。该库接受您自己的匹配器，用于特定用例和可重用性。

Any

Argument.any()匹配任何内容

Argument.any();

Equal

Argument.equals()（默认）使用原生深度相等进行匹配

Argument.equals(10);

jsonEqual

Argument.jsonEquals(new WithoutEqualsType())使用json字符串相等进行匹配。适用于匹配没有equals类型

Argument.jsonEquals(new WithoutEqualsType(10, true, '...'));

使用未锁定包版本时，命名空间自定义类型必须添加@JsonAccess注解，并设置serializable='always'。

ofType

Argument.ofType()根据参数类型进行匹配

// 匹配任何Integer
Argument.ofType('Integer');
// 匹配任何Account SObject
Argument.ofType(Account.getSObjectType());
// 匹配任何CustomType类实例
Argument.ofType(CustomType.class);

BYOM（构建自己的匹配器）

使用Argument.Matchable接口，然后在Argument API中使用它

@isTest
public class MyMatchable implements Argument.Matchable {
  public Boolean matches(Object callArgument) {
    boolean matches = false;

    // 在此处添加自定义逻辑以确定是否匹配
    ...

    return matches;
  }
}

List<Argument.Matchable> args = Argument.of(new MyMatchable(), ...otherArguments);