Testare il codice all'interno dei flag di lancio delle funzionalità

Con l'introduzione dei flag di lancio delle funzionalità, sono state introdotte nuove norme di test a cui devi attenerti:

• I test devono coprire sia i comportamenti abilitati sia quelli disabilitati del flag.
• Devi utilizzare i meccanismi ufficiali per impostare i valori dei flag durante i test.
• I test xTS non devono sostituire i valori dei flag nei test.

La sezione successiva fornisce i meccanismi ufficiali che devi utilizzare per rispettare queste norme.

Testare il codice con flag

Creare test end-to-end

AOSP fornisce una classe denominata FeatureFlagTargetPreparer, che consente di eseguire test end-to-end su un dispositivo. Questa classe accetta le sostituzioni dei valori dei flag come input, imposta questi flag nella configurazione dei dispositivi prima dell'esecuzione del test e li ripristina dopo l'esecuzione.

Puoi applicare la funzionalità della classe FeatureFlagTargetPreparer a livello di modulo di test e di configurazione del test.

Applicare FeatureFlagTargetPreparer in una configurazione del modulo di test

Per applicare FeatureFlagTargetPreparer in una configurazione del modulo di test, includi FeatureFlagTargetPreparer e le sostituzioni dei valori dei flag nel file di configurazione del modulo di test 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>

Dove:

• target.preparer class è sempre impostato su com.android.tradefed.targetprep.FeatureFlagTargetPreparer.
• option è la sostituzione del flag con name sempre impostato su flag-value e value impostato su namespace/aconfigPackage.flagName=true|false.

Creare moduli di test con parametri basati sugli stati dei flag

Per creare moduli di test con parametri basati sugli stati dei flag:

1. Includi FeatureFlagTargetPreparer nel file di configurazione del modulo di test AndroidTest.xml:

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

2. Specifica le opzioni dei valori dei flag nella sezione test_module_config di un file di build 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"},
       ],
   }
   

   Il campo options contiene le sostituzioni dei flag con name sempre impostato su flag-value e value impostato su namespace/aconfigPackage.flagName=true|false.

Creare test delle unità (Java e Kotlin)

Questa sezione descrive l'approccio alla sostituzione dei valori dei flag aconfig a livello di classe e di metodo (per test) nei test Java e Kotlin.

Per scrivere test delle unità automatizzati in una codebase di grandi dimensioni con un numero elevato di flag:

1. Utilizza la classe SetFlagsRule con le annotazioni @EnableFlags e @DisableFlags per testare tutti i rami di codice.
2. Utilizza il metodo SetFlagsRule.ClassRule per evitare bug di test comuni.
3. Utilizza FlagsParameterization per testare le classi in un'ampia gamma di configurazioni di flag.

Testare tutti i rami di codice

Per i progetti che utilizzano la classe statica per accedere ai flag, viene fornita la classe helper SetFlagsRule per sostituire i valori dei flag. Il seguente snippet di codice mostra come includere SetFlagsRule e abilitare più flag contemporaneamente:

  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() {
    ...
    }

Dove:

• @Rule è un'annotazione utilizzata per aggiungere la dipendenza flag-JUnit della classe SetFlagsRule.
• SetFlagsRule è una classe helper fornita per sostituire i valori dei flag. Per informazioni su come SetFlagsRule determina i valori predefiniti, consulta Valori predefiniti del dispositivo.
• @EnableFlags è un'annotazione che accetta un numero arbitrario di nomi di flag. Quando disabiliti i flag, utilizza @DisableFlags. Puoi applicare queste annotazioni a un metodo o a una classe.

Imposta i valori dei flag per l'intero processo di test, a partire da SetFlagsRule, che precede tutti i metodi di configurazione con annotazione @Before nel test. I valori dei flag tornano allo stato precedente al termine di SetFlagsRule, ovvero dopo tutti i metodi di configurazione con annotazione @After.

Assicurarsi che i flag siano impostati correttamente

Come accennato in precedenza, SetFlagsRule viene utilizzato con l'annotazione JUnit @Rule, il che significa che SetFlagsRule non può garantire che i flag siano impostati correttamente durante il costruttore della classe di test o in qualsiasi metodo con annotazione @BeforeClass o @AfterClass.

Per assicurarti che le fixture di test vengano create con il valore di classe corretto, utilizza il metodo SetFlagsRule.ClassRule in modo che le fixture non vengano create fino a un metodo di configurazione con annotazione @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() {
      ...
    }
  }

Se aggiungi la regola della classe SetFlagsRule.ClassRule, test_flag_foo_turned_on non viene eseguito prima dell'esecuzione quando FLAG_FLAG_FOO viene letto dal costruttore di DemoClass.

Se l'intera classe richiede l'abilitazione di un flag, sposta l'annotazione @EnableFlags a livello di classe (prima della dichiarazione della classe). Lo spostamento dell'annotazione a livello di classe consente a SetFlagsRule.ClassRule di garantire che il flag sia impostato correttamente durante il costruttore della classe di test o durante qualsiasi metodo con annotazione @BeforeClass o @AfterClass.

Eseguire test in più configurazioni di flag

Poiché puoi impostare i valori dei flag per ogni test, puoi anche utilizzare la parametrizzazione per eseguire test in più configurazioni di flag:

...
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() {...}
}

Tieni presente che con SetFlagsRule, ma senza parametrizzazione, questa classe esegue tre test (fooLogic, legacyBarLogic e newBarLogic). Il metodo fooLogic viene eseguito con i valori di FLAG_FOO e FLAG_BAR impostati sul dispositivo.

Quando viene aggiunta la parametrizzazione, il metodo FlagsParameterization.allCombinationsOf crea tutte le combinazioni possibili dei flag FLAG_FOO e FLAG_BAR:

• FLAG_FOO è true e FLAG_BAR è true
• FLAG_FOO è true e FLAG_BAR è false
• FLAG_FOO è false e FLAG_BAR è true
• FLAG_FOO è false e FLAG_BAR è false

Anziché modificare direttamente i valori dei flag, le annotazioni @DisableFlags e @EnableFlags modificano i valori dei flag in base alle condizioni dei parametri. Ad esempio, legacyBarLogic viene eseguito solo quando FLAG_BAR è disabilitato, il che si verifica in due delle quattro combinazioni di flag. legacyBarLogic viene ignorato per le altre due combinazioni.

Esistono due metodi per creare le parametrizzazioni per i flag:

• FlagsParameterization.allCombinationsOf(String...) esegue 2^n esecuzioni di ogni test. Ad esempio, un flag esegue 2 test o quattro flag eseguono 16 test.

• FlagsParameterization.progressionOf(String...) esegue n+1 esecuzioni di ogni test. Ad esempio, un flag esegue 2 test e quattro flag eseguono 5 flag.

Creare test delle unità (C e C++)

AOSP include macro di valori dei flag per i test C e C++ scritti nel framework GoogleTest.

1. Nell'origine del test, includi le definizioni delle macro e le librerie generate da aconfig:

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

2. Nell'origine del test, anziché utilizzare le macro TEST e TESTF per i casi di test, utilizza TEST_WITH_FLAGS e 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");
   }
   

   Dove:

   • Le macro TEST_WITH_FLAGS e TEST_F_WITH_FLAGS vengono utilizzate al posto delle macro TEST e TEST_F.
   • REQUIRES_FLAGS_ENABLED definisce un insieme di flag di rilascio delle funzionalità che devono soddisfare la condizione di abilitazione. Puoi scrivere questi flag nelle macro ACONFIG_FLAG o LEGACY_FLAG.
   • REQUIRES_FLAGS_DISABLED definisce un insieme di flag delle funzionalità che devono soddisfare la condizione di disabilitazione. Puoi scrivere questi flag nelle macro ACONFIG_FLAG o LEGACY_FLAG.
   • ACONFIG_FLAG (TEST_NS, readwrite_enabled_flag) è una macro utilizzata per i flag definiti nei file aconfig. Questa macro accetta uno spazio dei nomi (TEST_NS) e un nome di flag (readwrite_enabled_flag).
   • LEGACY_FLAG(aconfig_flags.cts, TEST_NS, readwrite_disabled_flag) è una macro utilizzata per i flag impostati per impostazione predefinita nella configurazione del dispositivo.

3. Nel file di build Android.bp, aggiungi le librerie generate da aconfig e le librerie di macro pertinenti come dipendenza di test:

   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. Esegui i test in locale con questo comando:

   atest FlagMacrosTests
   

   Se il flag my_namespace.android.myflag.tests.my_flag è disabilitato, il risultato del test è:

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

   Se il flag my_namespace.android.myflag.tests.my_flag è abilitato, il risultato del test è:

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

Creare test end-to-end o delle unità in cui i valori dei flag non cambiano

Per i casi di test in cui non puoi sostituire i flag e puoi filtrare i test solo se sono basati sullo stato corrente dei flag, utilizza la regola CheckFlagsRule con le annotazioni RequiresFlagsEnabled e RequiresFlagsDisabled.

I seguenti passaggi mostrano come creare ed eseguire un test end-to-end o delle unità in cui i valori dei flag non possono essere sostituiti:

1. Nel codice di test, utilizza CheckFlagsRule per applicare il filtro dei test. Inoltre, utilizza le annotazioni Java RequiresFlagsEnabled e RequiredFlagsDisabled per specificare i requisiti dei flag per il test.

   Il test lato dispositivo utilizza la classe 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() {}
   }
   

   Il test lato host utilizza la classe 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. Aggiungi jflag-unit e le librerie generate da aconfig alla sezione static_libs del file di build per il test:

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

3. Utilizza il seguente comando per eseguire il test in locale:

   atest FlagAnnotationTests
   

   Se il flag Flags.FLAG_FLAG_NAME_1 è disabilitato, il risultato del test è:

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

   In caso contrario, il risultato del test è:

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

Valori predefiniti del dispositivo

SetFlagsRule inizializzato utilizza i valori dei flag del dispositivo. Se il valore del flag sul dispositivo non viene sostituito, ad esempio con adb, il valore predefinito è lo stesso della configurazione di rilascio della build. Se il valore sul dispositivo è stato sostituito, SetFlagsRule utilizza il valore di sostituzione come valore predefinito.

Se lo stesso test viene eseguito con configurazioni di rilascio diverse, il valore dei flag non impostati in modo esplicito con SetFlagsRule può variare.

Dopo ogni test, SetFlagsRule ripristina l'istanza FeatureFlags in Flags al relativo FeatureFlagsImpl originale, in modo che non abbia effetti collaterali su altri metodi e classi di test.