ทดสอบโค้ดภายใน Flag การเปิดตัวฟีเจอร์

เมื่อมีการเปิดตัวแฟล็กการเปิดตัวฟีเจอร์ คุณต้องปฏิบัติตามนโยบายการทดสอบใหม่ดังนี้

  • การทดสอบต้องครอบคลุมทั้งลักษณะการทำงานที่เปิดใช้และปิดใช้ของแฟล็ก
  • คุณต้องใช้กลไกอย่างเป็นทางการเพื่อตั้งค่าแฟล็กระหว่างการทดสอบ
  • การทดสอบ xTS ไม่ควรลบล้างค่าแฟล็กในการทดสอบ

ส่วนถัดไปจะอธิบายกลไกอย่างเป็นทางการที่คุณต้องใช้เพื่อปฏิบัติตามนโยบายเหล่านี้

ทดสอบโค้ดที่มีแฟล็ก

สถานการณ์การทดสอบ กลไกที่ใช้
การทดสอบในเครื่องเมื่อค่าแฟล็กเปลี่ยนแปลงบ่อย Android Debug Bridge ตามที่อธิบายไว้ใน หัวข้อเปลี่ยนค่าแฟล็กขณะรันไทม์
การทดสอบในเครื่องเมื่อค่าแฟล็กไม่เปลี่ยนแปลงบ่อย ไฟล์ค่าแฟล็กตามที่อธิบายไว้ในหัวข้อตั้งค่าแฟล็กการเปิดตัวฟีเจอร์
การทดสอบแบบครบวงจรที่ค่าแฟล็กเปลี่ยนแปลง FeatureFlagTargetPreparer ตามที่อธิบายไว้ในหัวข้อสร้างการทดสอบแบบครบวงจร
การทำ Unit Test ที่ค่าแฟล็กเปลี่ยนแปลง SetFlagsRule ที่มี @EnableFlags และ @DisableFlags ตามที่อธิบายไว้ในหัวข้อสร้างการทดสอบ 1 หน่วย (Java และ Kotlin) หรือ สร้างการทดสอบ 1 หน่วย (C และ C++)
การทดสอบแบบครบวงจรหรือการทำ Unit Test ที่ค่าแฟล็กเปลี่ยนแปลงไม่ได้ CheckFlagsRule ตามที่อธิบายไว้ในหัวข้อสร้างการทดสอบแบบครบวงจรหรือการทดสอบ 1 หน่วยที่ค่าแฟล็กไม่เปลี่ยนแปลง

สร้างการทดสอบแบบครบวงจร

AOSP มีคลาสที่เรียกว่า FeatureFlagTargetPreparer ซึ่งช่วยให้ทำการทดสอบแบบครบวงจรในอุปกรณ์ได้ คลาสนี้รับการลบล้างค่าแฟล็กเป็นอินพุต ตั้งค่าแฟล็กเหล่านั้นในการกำหนดค่าอุปกรณ์ก่อนการดำเนินการทดสอบ และคืนค่าแฟล็กหลังการดำเนินการ

คุณสามารถใช้ฟังก์ชันการทำงานของคลาส FeatureFlagTargetPreparer ที่ระดับโมดูลทดสอบและการกำหนดค่าการทดสอบ

ใช้ FeatureFlagTargetPreparer ในการกำหนดค่าโมดูลทดสอบ

หากต้องการใช้ FeatureFlagTargetPreparer ในการกำหนดค่าโมดูลทดสอบ ให้ใส่ FeatureFlagTargetPreparer และการลบล้างค่าแฟล็กในไฟล์การกำหนดค่าโมดูลทดสอบ AndroidTest.xml ดังนี้

  <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. ใส่ FeatureFlagTargetPreparer ในไฟล์การกำหนดค่าโมดูลทดสอบ AndroidTest.xml ดังนี้

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

  2. ระบุตัวเลือกค่าแฟล็กในส่วน test_module_config ของไฟล์บิลด์ Android.bp ดังนี้

    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

สร้างการทดสอบ 1 หน่วย (Java และ Kotlin)

ส่วนนี้อธิบายแนวทางในการลบล้างค่าแฟล็ก aconfig ที่ระดับคลาสและเมธอด (ต่อการทดสอบ) ในการทดสอบ Java และ Kotlin

หากต้องการเขียนการทดสอบ 1 หน่วยแบบอัตโนมัติในฐานของโค้ดขนาดใหญ่ที่มีแฟล็กจำนวนมาก ให้ทำตามขั้นตอนต่อไปนี้

  1. ใช้คลาส SetFlagsRule ที่มีคำอธิบายประกอบ @EnableFlags และ @DisableFlags เพื่อทดสอบโค้ดทุกสาขา
  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 เป็นคำอธิบายประกอบที่ใช้เพื่อเพิ่มทรัพยากร Dependency ของแฟล็ก-JUnit ของคลาส SetFlagsRule
  • SetFlagsRule เป็นคลาสผู้ช่วยที่ให้ไว้เพื่อลบล้างค่าแฟล็ก ดูข้อมูลเกี่ยวกับวิธีที่ SetFlagsRule กำหนดค่าเริ่มต้นได้ที่ ค่าเริ่มต้นของอุปกรณ์
  • @EnableFlags เป็นคำอธิบายประกอบที่รับชื่อแฟล็กได้ตามต้องการ เมื่อปิดใช้แฟล็ก ให้ใช้ @DisableFlags คุณสามารถใช้คำอธิบายประกอบเหล่านี้กับเมธอดหรือคลาสก็ได้

ตั้งค่าแฟล็กสำหรับกระบวนการทดสอบทั้งหมด โดยเริ่มจาก SetFlagsRule ซึ่งจะดำเนินการก่อนเมธอดการตั้งค่าที่มีคำอธิบายประกอบ @Before ในการทดสอบ ค่าแฟล็กจะเปลี่ยนกลับไปเป็นสถานะก่อนหน้าเมื่อ SetFlagsRule เสร็จสิ้น ซึ่งจะเกิดขึ้นหลังเมธอดการตั้งค่าที่มีคำอธิบายประกอบ @After

ตรวจสอบว่าตั้งค่าแฟล็กอย่างถูกต้อง

ดังที่กล่าวไว้ก่อนหน้านี้ SetFlagsRule ใช้กับคำอธิบายประกอบ @Rule ของ JUnit ซึ่งหมายความว่า 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 แล้ว test_flag_foo_turned_on จะล้มเหลวก่อนที่จะทำงานเมื่อตัวสร้างของ DemoClass อ่าน FLAG_FLAG_FOO

หากทั้งคลาสต้องเปิดใช้แฟล็ก ให้ย้ายคำอธิบายประกอบ @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 แต่ไม่มีการกำหนดพารามิเตอร์ คลาสนี้จะเรียกใช้การทดสอบ 3 รายการ (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 ซึ่งเกิดขึ้นในชุดค่าผสมแฟล็ก 2 จาก 4 ชุด ระบบจะข้าม legacyBarLogic สำหรับชุดค่าผสมอื่นๆ 2 ชุด

การสร้างพารามิเตอร์สำหรับแฟล็กทำได้ 2 วิธีดังนี้

  • FlagsParameterization.allCombinationsOf(String...) จะดำเนินการทดสอบแต่ละรายการ 2^n ครั้ง เช่น แฟล็ก 1 รายการจะดำเนินการทดสอบ 2 ครั้ง หรือแฟล็ก 4 รายการจะดำเนินการทดสอบ 16 ครั้ง

  • FlagsParameterization.progressionOf(String...) จะดำเนินการทดสอบแต่ละรายการ n+1 ครั้ง เช่น แฟล็ก 1 รายการจะดำเนินการทดสอบ 2 ครั้ง และแฟล็ก 4 รายการจะดำเนินการทดสอบ 5 ครั้ง

สร้างการทดสอบ 1 หน่วย (C และ C++)

AOSP มีมาโครค่าแฟล็กสำหรับการทดสอบ C และ C++ ที่เขียนในเฟรมเวิร์ก GoogleTest

  1. ในแหล่งที่มาของการทดสอบ ให้ใส่คำจำกัดความของมาโครและไลบรารีที่ aconfig สร้างขึ้น

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

  2. ในแหล่งที่มาของการทดสอบ ให้ใช้มาโคร TEST_WITH_FLAGS และ TEST_F_WITH_FLAGS แทนมาโคร TEST และ TESTF สำหรับกรณีทดสอบ 

    #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 สร้างขึ้นและไลบรารีมาโครที่เกี่ยวข้องเป็นทรัพยากร Dependency ของการทดสอบ

    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)

สร้างการทดสอบแบบครบวงจรหรือการทดสอบ 1 หน่วยที่ค่าแฟล็กไม่เปลี่ยนแปลง

สำหรับกรณีทดสอบที่คุณลบล้างแฟล็กไม่ได้และกรองการทดสอบได้เฉพาะในกรณีที่การทดสอบอิงตามสถานะแฟล็กปัจจุบัน ให้ใช้กฎ CheckFlagsRule ที่มีคำอธิบายประกอบ RequiresFlagsEnabled และ RequiresFlagsDisabled

ขั้นตอนต่อไปนี้แสดงวิธีสร้างและเรียกใช้การทดสอบแบบครบวงจรหรือการทดสอบ 1 หน่วยที่ลบล้างค่าแฟล็กไม่ได้

  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 ค่าเริ่มต้นจะเหมือนกับการกำหนดค่าการเปิดตัวของบิลด์ หากมีการลบล้างค่าในอุปกรณ์ SetFlagsRule จะใช้ค่าที่ลบล้างเป็นค่าเริ่มต้น

หากมีการดำเนินการทดสอบเดียวกันภายใต้การกำหนดค่าการเปิดตัวที่แตกต่างกัน ค่าของแฟล็กที่ไม่ได้ตั้งค่าอย่างชัดเจนด้วย SetFlagsRule อาจแตกต่างกัน

หลังจากการทดสอบแต่ละครั้ง SetFlagsRule จะคืนค่าอินสแตนซ์ FeatureFlags ใน Flags เป็น FeatureFlagsImpl เดิม เพื่อไม่ให้ส่งผลข้างเคียงต่อ เมธอดและคลาสทดสอบอื่นๆ