Hilt 测试指南

使用 Hilt 之类的依赖项注入框架的一个好处是，它可以让您更轻松地测试代码。

单元测试

Hilt 对于单元测试来说是不必要的，因为对使用构造函数注入的类进行测试时，您无需使用 Hilt 实例化该类。相反，您可以直接调用类构造函数，传入虚假或模拟依赖项，就像构造函数没有注解时所做的一样：

Kotlin

@ActivityScoped
class AnalyticsAdapter @Inject constructor(
  private val service: AnalyticsService
) { ... }

class AnalyticsAdapterTest {

  @Test
  fun `Happy path`() {
    // You don't need Hilt to create an instance of AnalyticsAdapter.
    // You can pass a fake or mock AnalyticsService.
    val adapter = AnalyticsAdapter(fakeAnalyticsService)
    assertEquals(...)
  }
}

Java

@ActivityScope
public class AnalyticsAdapter {

  private final AnalyticsService analyticsService;

  @Inject
  AnalyticsAdapter(AnalyticsService analyticsService) {
    this.analyticsService = analyticsService;
  }
}

public final class AnalyticsAdapterTest {

  @Test
  public void happyPath() {
    // You don't need Hilt to create an instance of AnalyticsAdapter.
    // You can pass a fake or mock AnalyticsService.
    AnalyticsAdapter adapter = new AnalyticsAdapter(fakeAnalyticsService);
    assertEquals(...);
  }
}

端到端测试

对于集成测试，Hilt 会像在生产代码中一样注入依赖项。使用 Hilt 进行测试不需要维护，因为 Hilt 会自动为每个测试生成一组新的组件。

添加测试依赖项

如需在测试中使用 Hilt，请在项目中添加 hilt-android-testing 依赖项：

Groovy

dependencies {
    // For Robolectric tests.
    testImplementation 'com.google.dagger:hilt-android-testing:2.51.1'
    // ...with Kotlin.
    kaptTest 'com.google.dagger:hilt-android-compiler:2.51.1'
    // ...with Java.
    testAnnotationProcessor 'com.google.dagger:hilt-android-compiler:2.51.1'


    // For instrumented tests.
    androidTestImplementation 'com.google.dagger:hilt-android-testing:2.51.1'
    // ...with Kotlin.
    kaptAndroidTest 'com.google.dagger:hilt-android-compiler:2.51.1'
    // ...with Java.
    androidTestAnnotationProcessor 'com.google.dagger:hilt-android-compiler:2.51.1'
}

Kotlin

dependencies {
    // For Robolectric tests.
    testImplementation("com.google.dagger:hilt-android-testing:2.51.1")
    // ...with Kotlin.
    kaptTest("com.google.dagger:hilt-android-compiler:2.51.1")
    // ...with Java.
    testAnnotationProcessor("com.google.dagger:hilt-android-compiler:2.51.1")


    // For instrumented tests.
    androidTestImplementation("com.google.dagger:hilt-android-testing:2.51.1")
    // ...with Kotlin.
    kaptAndroidTest("com.google.dagger:hilt-android-compiler:2.51.1")
    // ...with Java.
    androidTestAnnotationProcessor("com.google.dagger:hilt-android-compiler:2.51.1")
}

注意：如果您使用 Jetpack 集成，还必须将集成的库的注解处理器随附于 kaptTest 或 kaptAndroidTest（对于 Kotlin），或者随附于 testAnnotationProcessor 或 androidTestAnnotationProcessor（对于 Java）。

界面测试设置

您必须用 @HiltAndroidTest 为任何使用 Hilt 的界面测试添加注释。此注释负责为每个测试生成 Hilt 组件。

此外，您还需要向测试类添加 HiltAndroidRule。它管理组件的状态，并用于对测试执行注入：

Kotlin

@HiltAndroidTest
class SettingsActivityTest {

  @get:Rule
  var hiltRule = HiltAndroidRule(this)

  // UI tests here.
}

Java

@HiltAndroidTest
public final class SettingsActivityTest {

  @Rule
  public HiltAndroidRule hiltRule = new HiltAndroidRule(this);

  // UI tests here.
}

注意：如果测试中有其他规则，请参阅插桩测试中的多个 TestRule 对象。

接下来，测试需要了解 Hilt 自动为您生成的 Application 类。

测试应用

您必须在支持 Hilt 的 Application 对象中执行使用 Hilt 的插桩测试。该库提供了 HiltTestApplication，以便在测试中使用。如果测试需要其他基础应用，请参阅用于测试的自定义应用。

您必须设置要在插桩测试或 Robolectric 测试中运行的测试应用。以下说明并不是专门针对 Hilt，而是有关如何指定要在测试中运行的自定义应用的一般准则。

在插桩测试中设置测试应用

如需在插桩测试中使用 Hilt 测试应用，您需要配置一个新的测试运行程序。这使得 Hilt 可适用于项目中的所有插桩测试。请执行以下步骤：

1. 在 androidTest 文件夹中创建一个扩展 AndroidJUnitRunner 的自定义类。
2. 替换 newApplication 函数并传入生成的 Hilt 测试应用的名称。

Kotlin

// A custom runner to set up the instrumented application class for tests.
class CustomTestRunner : AndroidJUnitRunner() {

    override fun newApplication(cl: ClassLoader?, name: String?, context: Context?): Application {
        return super.newApplication(cl, HiltTestApplication::class.java.name, context)
    }
}

Java

// A custom runner to set up the instrumented application class for tests.
public final class CustomTestRunner extends AndroidJUnitRunner {

  @Override
  public Application newApplication(ClassLoader cl, String className, Context context)
      throws ClassNotFoundException, IllegalAccessException, InstantiationException {
    return super.newApplication(cl, HiltTestApplication.class.getName(), context);
  }
}

接下来，在 Gradle 文件中配置此测试运行程序，如插桩单元测试指南中所述。请务必使用完整的类路径：

Groovy

android {
    defaultConfig {
        // Replace com.example.android.dagger with your class path.
        testInstrumentationRunner "com.example.android.dagger.CustomTestRunner"
    }
}

Kotlin

android {
    defaultConfig {
        // Replace com.example.android.dagger with your class path.
        testInstrumentationRunner = "com.example.android.dagger.CustomTestRunner"
    }
}

在 Robolectric 测试中设置测试应用

如果您使用 Robolectric 测试界面层，可以在 robolectric.properties 文件中指定要使用的应用：

application = dagger.hilt.android.testing.HiltTestApplication

或者，您也可以使用 Roolectric 的 @Config 注释在每个测试上单独配置应用：

Kotlin

@HiltAndroidTest
@Config(application = HiltTestApplication::class)
class SettingsActivityTest {

  @get:Rule
  var hiltRule = HiltAndroidRule(this)

  // Robolectric tests here.
}

Java

@HiltAndroidTest
@Config(application = HiltTestApplication.class)
class SettingsActivityTest {

  @Rule public HiltAndroidRule hiltRule = new HiltAndroidRule(this);

  // Robolectric tests here.
}

如果您使用的 Android Gradle 插件版本低于 4.2，请在模块的 build.gradle 文件中应用以下配置，以在本地单元测试中启用 @AndroidEntryPoint 类的转换：

Groovy

hilt {
    enableTransformForLocalTests = true
}

Kotlin

hilt {
    enableTransformForLocalTests = true
}

如需详细了解 enableTransformForLocalTests，请参阅 Hilt 文档。

测试功能

一旦 Hilt 可供在测试中使用，您就可以使用几项功能来自定义测试流程。

在测试中注入类型

如需将类型注入测试，请使用 @Inject 执行字段注入。如需告知 Hilt 填充 @Inject 字段，请调用 hiltRule.inject()。

请查看以下插桩测试示例：

Kotlin

@HiltAndroidTest
class SettingsActivityTest {

  @get:Rule
  var hiltRule = HiltAndroidRule(this)

  @Inject
  lateinit var analyticsAdapter: AnalyticsAdapter

  @Before
  fun init() {
    hiltRule.inject()
  }

  @Test
  fun `happy path`() {
    // Can already use analyticsAdapter here.
  }
}

Java

@HiltAndroidTest
public final class SettingsActivityTest {

  @Rule public HiltAndroidRule hiltRule = new HiltAndroidRule(this);

  @Inject AnalyticsAdapter analyticsAdapter;

  @Before
  public void init() {
    hiltRule.inject();
  }

  @Test
  public void happyPath() {
    // Can already use analyticsAdapter here.
  }
}

替换绑定

如果您需要注入依赖项的虚假或模拟实例，则需要告知 Hilt 不要使用它在生产代码中使用的绑定，而应改用其他绑定。如需替换绑定，您需要将包含该绑定的模块替换为包含您要在测试中使用的绑定的测试模块。

例如，假设生产代码声明了 AnalyticsService 的绑定，如下所示：

Kotlin

@Module
@InstallIn(SingletonComponent::class)
abstract class AnalyticsModule {

  @Singleton
  @Binds
  abstract fun bindAnalyticsService(
    analyticsServiceImpl: AnalyticsServiceImpl
  ): AnalyticsService
}

Java

@Module
@InstallIn(SingletonComponent.class)
public abstract class AnalyticsModule {

  @Singleton
  @Binds
  public abstract AnalyticsService bindAnalyticsService(
    AnalyticsServiceImpl analyticsServiceImpl
  );
}

如需替换测试中的 AnalyticsService 绑定，请在 test 或 androidTest 文件夹中使用虚假依赖项创建新的 Hilt 模块，并为其添加 @TestInstallIn 注解。该文件夹中的所有测试都会改为注入虚假依赖项。

Kotlin

@Module
@TestInstallIn(
    components = [SingletonComponent::class],
    replaces = [AnalyticsModule::class]
)
abstract class FakeAnalyticsModule {

  @Singleton
  @Binds
  abstract fun bindAnalyticsService(
    fakeAnalyticsService: FakeAnalyticsService
  ): AnalyticsService
}

Java

@Module
@TestInstallIn(
    components = SingletonComponent.class,
    replaces = AnalyticsModule.class
)
public abstract class FakeAnalyticsModule {

  @Singleton
  @Binds
  public abstract AnalyticsService bindAnalyticsService(
    FakeAnalyticsService fakeAnalyticsService
  );
}

替换单个测试中的绑定

如需替换单个测试（而不是所有测试）中的绑定，请使用 @UninstallModules 注解从测试中卸载 Hilt 模块，然后在测试中创建新的测试模块。

按照上一版本中的 AnalyticsService 示例进行操作，首先在测试类中使用 @UninstallModules 注解，以告知 Hilt 忽略正式版模块：

Kotlin

@UninstallModules(AnalyticsModule::class)
@HiltAndroidTest
class SettingsActivityTest { ... }

Java

@UninstallModules(AnalyticsModule.class)
@HiltAndroidTest
public final class SettingsActivityTest { ... }

接下来，您必须替换该绑定。在测试类中创建一个用于定义测试绑定的新模块：

Kotlin

@UninstallModules(AnalyticsModule::class)
@HiltAndroidTest
class SettingsActivityTest {

  @Module
  @InstallIn(SingletonComponent::class)
  abstract class TestModule {

    @Singleton
    @Binds
    abstract fun bindAnalyticsService(
      fakeAnalyticsService: FakeAnalyticsService
    ): AnalyticsService
  }

  ...
}

Java

@UninstallModules(AnalyticsModule.class)
@HiltAndroidTest
public final class SettingsActivityTest {

  @Module
  @InstallIn(SingletonComponent.class)
  public abstract class TestModule {

    @Singleton
    @Binds
    public abstract AnalyticsService bindAnalyticsService(
      FakeAnalyticsService fakeAnalyticsService
    );
  }
  ...
}

这样只会替换单个测试类的绑定。如果要替换所有测试类的绑定，请使用上一部分中的 @TestInstallIn 注解。或者，您可以将测试绑定放在 test 模块中（对于 Robolectric 测试），或放在 androidTest 模块中（对于插桩测试）。建议尽可能使用 @TestInstallIn。

警告：您不能卸载不带 @InstallIn 注解的模块。尝试这样做会导致编译错误。

警告：@UninstallModules 只能卸载 @InstallIn 模块，而无法卸载 @TestInstallIn 模块。尝试这样做会导致编译错误。

注意：由于 Hilt 会为使用 @UninstallModules 的测试创建新组件，因此这可能会对单元测试的构建时间产生极大影响。如有必要，请使用该方法；如果需要替换所有测试类中的绑定，请使用 @TestInstallIn。

绑定新值

使用 @BindValue 注释可轻松地将测试中的字段绑定到 Hilt 依赖关系图。使用 @BindValue 为字段添加注解后，该字段将在声明的字段类型下与该字段存在的任何限定符进行绑定。

在 AnalyticsService 示例中，您可以使用 @BindValue 将 AnalyticsService 替换为虚假对象：

Kotlin

@UninstallModules(AnalyticsModule::class)
@HiltAndroidTest
class SettingsActivityTest {

  @BindValue @JvmField
  val analyticsService: AnalyticsService = FakeAnalyticsService()

  ...
}

Java

@UninstallModules(AnalyticsModule.class)
@HiltAndroidTest
class SettingsActivityTest {

  @BindValue AnalyticsService analyticsService = FakeAnalyticsService();

  ...
}

这样一来，您可以同时在测试中替换绑定和引用绑定，从而简化了这两项操作。

@BindValue 可与限定符以及其他测试注解搭配使用。例如，如果您使用 Mockito 等测试库，可以在 Robolectric 测试中使用该注释，如下所示：

Kotlin

...
class SettingsActivityTest {
  ...

  @BindValue @ExampleQualifier @Mock
  lateinit var qualifiedVariable: ExampleCustomType

  // Robolectric tests here
}

Java

...
class SettingsActivityTest {
  ...
  @BindValue @ExampleQualifier @Mock ExampleCustomType qualifiedVariable;

  // Robolectric tests here
}

如果您需要添加多绑定，可以使用 @BindValueIntoSet 和 @BindValueIntoMap 注解来代替 @BindValue。@BindValueIntoMap 要求您还要使用映射键注释为字段添加注释。

特殊情况

Hilt 还提供了一些功能来支持非标准用例。

用于测试的自定义应用

如果由于测试应用需要扩展其他应用，因而您无法使用 HiltTestApplication，请使用 @CustomTestApplication 为一个新类或接口添加注解，并传入您希望生成的 Hilt 应用所要扩展的基类的值。

@CustomTestApplication 将生成一个 Application 类，该类可供使用 Hilt 进行测试，扩展了您以参数形式传递的应用。

Kotlin

@CustomTestApplication(BaseApplication::class)
interface HiltTestApplication

Java

@CustomTestApplication(BaseApplication.class)
interface HiltTestApplication { }

在本例中，Hilt 生成了一个名为 HiltTestApplication_Application 的 Application，该类扩展了 BaseApplication 类。一般来说，生成的应用的名称是带有注解的类的名称后面加上 _Application。您必须设置要在插桩测试或 Robolectric 测试中运行的生成的 Hilt 测试应用，如测试应用中所述。

注意：由于 HiltTestApplication_Application 是 Hilt 在运行时生成的代码，因此在您运行测试之前，IDE 可能会以红色将其突出显示。

插桩测试中的多个 TestRule 对象

如果测试中有其他 TestRule 对象，您可以通过多种方式来确保所有规则协同工作。

您可以将规则封装在一起，如下所示：

Kotlin

@HiltAndroidTest
class SettingsActivityTest {

  @get:Rule
  var rule = RuleChain.outerRule(HiltAndroidRule(this)).
        around(SettingsActivityTestRule(...))

  // UI tests here.
}

Java

@HiltAndroidTest
public final class SettingsActivityTest {

  @Rule public RuleChain rule = RuleChain.outerRule(new HiltAndroidRule(this))
        .around(new SettingsActivityTestRule(...));

  // UI tests here.
}

或者，您也可以在同一级别使用这两个规则，只要 HiltAndroidRule 先执行即可。您可以使用 @Rule 注解中的 order 属性指定执行顺序。这仅适用于 JUnit 版本 4.13 或更高版本：

Kotlin

@HiltAndroidTest
class SettingsActivityTest {

  @get:Rule(order = 0)
  var hiltRule = HiltAndroidRule(this)

  @get:Rule(order = 1)
  var settingsActivityTestRule = SettingsActivityTestRule(...)

  // UI tests here.
}

Java

@HiltAndroidTest
public final class SettingsActivityTest {

  @Rule(order = 0)
  public HiltAndroidRule hiltRule = new HiltAndroidRule(this);

  @Rule(order = 1)
  public SettingsActivityTestRule settingsActivityTestRule = new SettingsActivityTestRule(...);

  // UI tests here.
}

launchFragmentInContainer

您无法将 androidx.fragment:fragment-testing 库中的 launchFragmentInContainer 与 Hilt 一起使用，因为它依赖于一个不带 @AndroidEntryPoint 注解的 activity。

请改用 architecture-samples GitHub 代码库中的 launchFragmentInHiltContainer 代码。

在单例组件可用之前使用入口点

如果在 Hilt 测试中的单例组件可用之前就需要创建 Hilt 入口点，@EarlyEntryPoint 注解可作为应急方法使用。

如需详细了解 @EarlyEntryPoint，请参阅 Hilt 文档。