在功能发布标记中测试代码

随着功能发布标记的引入，您必须遵守新的测试政策

  • 您的测试必须涵盖标记的启用和停用行为。
  • 您必须使用官方机制在测试期间设置标记值。
  • xTS 测试不应替换测试中的标记值。

下一部分介绍了您必须使用的官方机制，以遵守这些政策。

测试已标记的代码

测试场景 使用的机制
标记值经常更改时的本地测试 Android 调试桥，如在运行时更改标记的值中所述
标记值不经常更改时的本地测试 标记值文件，如设置功能发布标记值中所述
标记值更改的端到端测试 FeatureFlagTargetPreparer，如创建端到端测试中所述
标记值更改的单元测试 带有 @EnableFlags 和 @DisableFlags 的 SetFlagsRule，如创建单元测试（Java 和 Kotlin）或 创建单元测试（C 和 C++）中所述
标记值无法更改的端到端或单元测试 带有 CheckFlagsRule，如创建标记值不更改的端到端或单元测试中所述

创建端到端测试

AOSP 提供了一个名为 FeatureFlagTargetPreparer 的类，该类支持在设备上进行端到端测试。此类接受标记值替换作为输入，在测试执行前在设备配置中设置这些标记，并在执行后恢复标记。

您可以在测试模块和测试配置级别应用 FeatureFlagTargetPreparer 类的功能。

在测试模块配置中应用 FeatureFlagTargetPreparer

要在测试模块配置中应用 FeatureFlagTargetPreparer，请在 AndroidTest.xml 测试模块配置文件中包含 FeatureFlagTargetPreparer 和标记值替换

  <target_preparer class="com.android.tradefed.targetprep.FeatureFlagTargetPreparer">
        <option name="flag-value"
            value="permissions/com.android.permission.flags.device_aware_permission_grant=true"/>
        <option name="flag-value"
            value="virtual_devices/android.companion.virtual.flags.stream_permissions=true"/>
    </target_preparer>

其中

  • target.preparer class 始终设置为 com.android.tradefed.targetprep.FeatureFlagTargetPreparer。
  • option 是标记替换，其中 name 始终设置为 flag-value，value 设置为 namespace/aconfigPackage.flagName=true|false。

基于标记状态创建参数化测试模块

要基于标记状态创建参数化测试模块

  1. 请在 AndroidTest.xml 测试模块配置文件中包含 FeatureFlagTargetPreparer

    <target_preparer class="com.android.tradefed.targetprep.FeatureFlagTargetPreparer" >

  2. 在 Android.bp 构建文件的 test_module_config 部分中指定标记值选项

    android_test {
    name: "MyTest"
    ...
}

test_module_config {
    name: "MyTestWithMyFlagEnabled",
    base: "MyTest",
    ...
    options: [
        {name: "flag-value", value: "telephony/com.android.internal.telephony.flags.oem_enabled_satellite_flag=true"},
    ],
}

test_module_config {
    name: "MyTestWithMyFlagDisabled",
    base: "MyTest",
    ...
    options: [
        {name: "flag-value", value: "telephony/com.android.internal.telephony.flags.carrier_enabled_satellite_flag=true"},
    ],
}

    options 字段包含标记替换，其中 name 始终设置为 flag-value，value 设置为 namespace/aconfigPackage.flagName=true|false。

创建单元测试（Java 和 Kotlin）

本部分介绍了在 Java 和 Kotlin 测试中，在类和方法级别（按测试）替换 aconfig 标记值的方法。

要在具有大量标记的大型代码库中编写自动化单元测试，请按照以下步骤操作

  1. 使用带有 @EnableFlags 和 @DisableFlags 注解的 SetFlagsRule 类来测试所有代码分支。
  2. 使用 SetFlagsRule.ClassRule 方法以避免常见的测试错误。
  3. 使用 FlagsParameterization 在广泛的标记配置中测试您的类。

测试所有代码分支

对于使用静态类访问标记的项目，我们提供了 SetFlagsRule 帮助程序类来替换标记值。以下代码段展示了如何包含 SetFlagsRule 并一次启用多个标记

  import android.platform.test.annotations.EnableFlags;
  import android.platform.test.flag.junit.SetFlagsRule;
  import com.example.android.aconfig.demo.flags.Flags;
  ...
    @Rule public final SetFlagsRule mSetFlagsRule = new SetFlagsRule();

    @Test
    @EnableFlags({Flags.FLAG_FLAG_FOO, Flags.FLAG_FLAG_BAR})
    public void test_flag_foo_and_flag_bar_turned_on() {
    ...
    }

其中

  • @Rule 是一个注解，用于添加 SetFlagsRule 类的 flag-JUnit 依赖项。
  • SetFlagsRule 是提供的帮助程序类，用于替换标记值。有关 SetFlagsRule 如何确定默认值的信息，请参阅设备默认值。
  • @EnableFlags 是一个注解，它接受任意数量的标记名称。禁用标记时，请使用 @DisableFlags。您可以将这些注解应用于方法或类。

为整个测试过程设置标记值，从 SetFlagsRule 开始，它先于测试中的任何 @Before 注解设置方法。当 SetFlagsRule 完成时，标记值将返回到其先前状态，这发生在任何 @After 注解设置方法之后。

确保标记已正确设置

如前所述，SetFlagsRule 与 JUnit @Rule 注解一起使用，这意味着 SetFlagsRule 无法确保您的标记在测试类的构造函数或任何 @BeforeClass 或 @AfterClass 注解方法期间正确设置。

为了确保使用正确的类值构造测试装置，请使用 SetFlagsRule.ClassRule 方法，以便在 @Before 注解设置方法之前不会创建您的装置

  import android.platform.test.annotations.EnableFlags;
  import android.platform.test.flag.junit.SetFlagsRule;
  import com.example.android.aconfig.demo.flags.Flags;

  class ExampleTest {
    @ClassRule public static final SetFlagsRule.ClassRule mClassRule = new SetFlagsRule.ClassRule();
    @Rule public final SetFlagsRule mSetFlagsRule = mClassRule.createSetFlagsRule();

    private DemoClass underTest = new DemoClass();

    @Test
    @EnableFlags(Flags.FLAG_FLAG_FOO)
    public void test_flag_foo_turned_on() {
      ...
    }
  }

通过添加 SetFlagsRule.ClassRule 类规则，当 DemoClass 的构造函数读取 FLAG_FLAG_FOO 时，test_flag_foo_turned_on 会在运行之前失败。

如果您的整个类都需要启用标记，请将 @EnableFlags 注解移动到类级别（在类声明之前）。将注解移动到类级别可让 SetFlagsRule.ClassRule 确保在测试类的构造函数期间或任何 @BeforeClass 或 @AfterClass 注解方法期间正确设置标记。

跨多个标记配置运行测试

由于您可以按测试设置标记值，因此您还可以使用参数化跨多个标记配置运行测试

...
import com.example.android.aconfig.demo.flags.Flags;
...

@RunWith(ParameterizedAndroidJunit4::class)
class FooBarTest {
    @Parameters(name = "{0}")
    public static List<FlagsParameterization> getParams() {
        return FlagsParameterization.allCombinationsOf(Flags.FLAG_FOO, Flags.FLAG_BAR);
    }

    @Rule
    public SetFlagsRule mSetFlagsRule;

    public FooBarTest(FlagsParameterization flags) {
        mSetFlagsRule = new SetFlagsRule(flags);
    }

    @Test public void fooLogic() {...}

    @DisableFlags(Flags.FLAG_BAR)
    @Test public void legacyBarLogic() {...}

    @EnableFlags(Flags.FLAG_BAR)
    @Test public void newBarLogic() {...}
}

请注意，使用 SetFlagsRule，但在没有参数化的情况下，此类会运行三个测试（fooLogic、legacyBarLogic 和 newBarLogic）。fooLogic 方法使用设备上设置的 FLAG_FOO 和 FLAG_BAR 的值运行。

添加参数化后，FlagsParameterization.allCombinationsOf 方法会创建 FLAG_FOO 和 FLAG_BAR 标记的所有可能组合

  • FLAG_FOO 为 true，FLAG_BAR 为 true
  • FLAG_FOO 为 true，FLAG_BAR 为 false
  • FLAG_FOO 为 false，FLAG_BAR 为 true
  • FLAG_FOO 为 false，FLAG_BAR 为 false

注释 @DisableFlags 和 @EnableFlags 不会直接更改标记值，而是根据参数条件修改标记值。例如，legacyBarLogic 仅在 FLAG_BAR 停用时运行，这在四个标记组合中的两个中发生。legacyBarLogic 会跳过其他两个组合。

有两种方法可以为您的标记创建参数化

  • FlagsParameterization.allCombinationsOf(String...) 执行每个测试的 2^n 次运行。例如，一个标记运行 2 倍测试，或者四个标记运行 16 倍测试。

  • FlagsParameterization.progressionOf(String...) 执行每个测试的 n+1 次运行。例如，一个标记运行 2 倍测试，四个标记运行 5 倍标记。

创建单元测试（C 和 C++）

AOSP 为在 GoogleTest 框架中编写的 C 和 C++ 测试提供了标记值宏。

  1. 在您的测试源中，包含宏定义和 aconfig 生成的库

    #include <flag_macros.h>
#include "android_cts_flags.h"

  2. 在您的测试源中，不要为您的测试用例使用 TEST 和 TESTF 宏，而是使用 TEST_WITH_FLAGS 和 TEST_F_WITH_FLAGS

    #define TEST_NS android::cts::flags::tests

...

TEST_F_WITH_FLAGS(
  TestFWithFlagsTest,
  requies_disabled_flag_enabled_skip,
  REQUIRES_FLAGS_DISABLED(ACONFIG_FLAG(TEST_NS, readwrite_enabled_flag))
) {
  TestFail();
}

...

TEST_F_WITH_FLAGS(
  TestFWithFlagsTest,
  multi_flags_for_same_state_skip,
  REQUIRES_FLAGS_ENABLED(
      ACONFIG_FLAG(TEST_NS, readwrite_enabled_flag),
      LEGACY_FLAG(aconfig_flags.cts, TEST_NS, readwrite_disabled_flag)
  )
) {
  TestFail();
}

...

TEST_WITH_FLAGS(
  TestWithFlagsTest,
  requies_disabled_flag_enabled_skip,
  REQUIRES_FLAGS_DISABLED(
      LEGACY_FLAG(aconfig_flags.cts, TEST_NS, readwrite_enabled_flag))
) {
  FAIL();
}

...

TEST_WITH_FLAGS(
  TestWithFlagsTest,
  requies_enabled_flag_enabled_executed,
  REQUIRES_FLAGS_ENABLED(ACONFIG_FLAG(TEST_NS, readwrite_enabled_flag))
) {
  TestWithFlagsTestHelper::executed_tests.insert(
      "requies_enabled_flag_enabled_executed");
}

    其中

    • TEST_WITH_FLAGS 和 TEST_F_WITH_FLAGS 宏用于代替 TEST 和 TEST_F 宏。
    • REQUIRES_FLAGS_ENABLED 定义一组必须满足启用条件的功能发布标记。您可以在 ACONFIG_FLAG 或 LEGACY_FLAG 宏中编写这些标记。
    • REQUIRES_FLAGS_DISABLED 定义一组必须满足停用条件的功能标记。您可以在 ACONFIG_FLAG 或 LEGACY_FLAG 宏中编写这些标记。
    • ACONFIG_FLAG (TEST_NS, readwrite_enabled_flag) 是一个宏，用于在 aconfig 文件中定义的标记。此宏接受命名空间 (TEST_NS) 和标记名称 (readwrite_enabled_flag)。
    • LEGACY_FLAG(aconfig_flags.cts, TEST_NS, readwrite_disabled_flag) 是一个宏，用于默认在设备配置中设置的标记。

  3. 在您的 Android.bp 构建文件中，添加 aconfig 生成的库和相关的宏库作为测试依赖项

    cc_test {
  name: "FlagMacrosTests",
  srcs: ["src/FlagMacrosTests.cpp"],
  static_libs: [
      "libgtest",
      "libflagtest",
      "my_aconfig_lib",
  ],
  shared_libs: [
      "libbase",
      "server_configurable_flags",
  ],
  test_suites: ["general-tests"],
  ...
}

  4. 使用此命令在本地运行测试

    atest FlagMacrosTests

    如果标记 my_namespace.android.myflag.tests.my_flag 已停用，则测试结果为

    [1/2] MyTest#test1: IGNORED (0ms)
[2/2] MyTestF#test2: PASSED (0ms)

    如果标记 my_namespace.android.myflag.tests.my_flag 已启用，则测试结果为

    [1/2] MyTest#test1: PASSED (0ms)
[2/2] MyTestF#test2: IGNORED (0ms)

创建标记值不更改的端到端或单元测试

对于无法替换标记并且只能在测试基于当前标记状态时才筛选测试用例，请将规则 CheckFlagsRule 与 RequiresFlagsEnabled 和 RequiresFlagsDisabled 注解一起使用。

以下步骤向您展示了如何创建和运行标记值无法替换的端到端或单元测试

  1. 在您的测试代码中，使用 CheckFlagsRule 应用测试筛选。此外，使用 Java 注解 RequiresFlagsEnabled 和 RequiredFlagsDisabled 来指定您的测试的标记要求。

    设备端测试使用 DeviceFlagsValueProvider 类

    @RunWith(JUnit4.class)
public final class FlagAnnotationTest {
  @Rule
  public final CheckFlagsRule mCheckFlagsRule =
          DeviceFlagsValueProvider.createCheckFlagsRule();

  @Test
  @RequiresFlagsEnabled(Flags.FLAG_FLAG_NAME_1)
  public void test1() {}

  @Test
  @RequiresFlagsDisabled(Flags.FLAG_FLAG_NAME_1)
  public void test2() {}
}

    主机端测试使用 HostFlagsValueProvider 类

    @RunWith(DeviceJUnit4ClassRunner.class)
public final class FlagAnnotationTest extends BaseHostJUnit4Test {
  @Rule
  public final CheckFlagsRule mCheckFlagsRule =
          HostFlagsValueProvider.createCheckFlagsRule(this::getDevice);

  @Test
  @RequiresFlagsEnabled(Flags.FLAG_FLAG_NAME_1)
  public void test1() {}

  @Test
  @RequiresFlagsDisabled(Flags.FLAG_FLAG_NAME_1)
  public void test2() {}
}

  2. 将 jflag-unit 和 aconfig 生成的库添加到您的测试的构建文件的 static_libs 部分

    android_test {
    name: "FlagAnnotationTests",
    srcs: ["*.java"],
    static_libs: [
        "androidx.test.rules",
        "my_aconfig_lib",
        "flag-junit",
        "platform-test-annotations",
    ],
    test_suites: ["general-tests"],
}

  3. 使用以下命令在本地运行测试

    atest FlagAnnotationTests

    如果标记 Flags.FLAG_FLAG_NAME_1 已停用，则测试结果为

    [1/2] com.cts.flags.FlagAnnotationTest#test1: ASSUMPTION_FAILED (10ms)
[2/2] com.cts.flags.FlagAnnotationTest#test2: PASSED (2ms)

    否则，测试结果为

    [1/2] com.cts.flags.FlagAnnotationTest#test1: PASSED (2ms)
[2/2] com.cts.flags.FlagAnnotationTest#test2: ASSUMPTION_FAILED (10ms)

设备默认值

初始化的 SetFlagsRule 使用来自设备的标记值。如果设备上的标记值未被替换（例如，使用 adb），则默认值与 build 的发布配置相同。如果设备上的值已被替换，则 SetFlagsRule 将替换值用作默认值。

如果在不同的发布配置下执行相同的测试，则未通过 SetFlagsRule 显式设置的标记的值可能会有所不同。

在每次测试之后，SetFlagsRule 都会将 Flags 中的 FeatureFlags 实例恢复为其原始 FeatureFlagsImpl，以便它不会对其他测试方法和类产生副作用。