Tester le code dans les flags de lancement de fonctionnalités

Avec l'introduction des flags de lancement de fonctionnalités, de nouvelles règles de test doivent être respectées :

• Vos tests doivent couvrir les comportements activés et désactivés du flag.
• Vous devez utiliser les mécanismes officiels pour définir les valeurs des options lors des tests.
• Les tests xTS ne doivent pas remplacer les valeurs des indicateurs dans les tests.

La section suivante présente les mécanismes officiels que vous devez utiliser pour respecter ces règles.

Tester votre code signalé

Créer des tests de bout en bout

AOSP fournit une classe appelée FeatureFlagTargetPreparer, qui permet d'effectuer des tests de bout en bout sur un appareil. Cette classe accepte les remplacements de valeurs d'indicateurs en entrée, définit ces indicateurs dans la configuration des appareils avant l'exécution du test et restaure les indicateurs après l'exécution.

Vous pouvez appliquer la fonctionnalité de la classe FeatureFlagTargetPreparer aux niveaux du module de test et de la configuration du test.

Appliquer FeatureFlagTargetPreparer dans une configuration de module de test

Pour appliquer FeatureFlagTargetPreparer dans une configuration de module de test, incluez FeatureFlagTargetPreparer et les remplacements de valeurs d'indicateurs dans le fichier de configuration du module de 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>

Où :

• target.preparer class est toujours défini sur com.android.tradefed.targetprep.FeatureFlagTargetPreparer.
• option est la substitution d'option avec name toujours défini sur flag-value et value défini sur namespace/aconfigPackage.flagName=true|false.

Créer des modules de test paramétrés en fonction des états des indicateurs

Pour créer des modules de test paramétrés en fonction des états des indicateurs :

1. Incluez FeatureFlagTargetPreparer dans le fichier de configuration du module de test AndroidTest.xml :

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

2. Spécifiez les options de valeur du flag dans la section test_module_config d'un fichier de compilation 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"},
       ],
   }
   

   Le champ options contient les remplacements de l'indicateur, avec name toujours défini sur flag-value et value défini sur namespace/aconfigPackage.flagName=true|false.

Créer des tests unitaires (Java et Kotlin)

Cette section décrit l'approche à suivre pour remplacer les valeurs des indicateurs aconfig au niveau de la classe et de la méthode (par test) dans les tests Java et Kotlin.

Pour écrire des tests unitaires automatisés dans une grande base de code avec un grand nombre de flags, procédez comme suit :

1. Utilisez la classe SetFlagsRule avec les annotations @EnableFlags et @DisableFlags pour tester toutes les branches de code.
2. Utilisez la méthode SetFlagsRule.ClassRule pour éviter les bugs de test courants.
3. Utilisez FlagsParameterization pour tester vos classes avec un large éventail de configurations de flags.

Tester toutes les branches de code

Pour les projets qui utilisent la classe statique pour accéder aux indicateurs, la classe d'assistance SetFlagsRule est fournie pour remplacer les valeurs des indicateurs. L'extrait de code suivant montre comment inclure SetFlagsRule et activer plusieurs indicateurs à la fois :

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

Où :

• @Rule est une annotation utilisée pour ajouter la dépendance flag-JUnit de la classe SetFlagsRule.
• SetFlagsRule est une classe d'assistance fournie pour remplacer les valeurs des indicateurs. Pour savoir comment SetFlagsRule détermine les valeurs par défaut, consultez Valeurs par défaut des appareils.
• @EnableFlags est une annotation qui accepte un nombre arbitraire de noms de flags. Lorsque vous désactivez des options, utilisez @DisableFlags. Vous pouvez appliquer ces annotations à une méthode ou à une classe.

Définissez les valeurs des indicateurs pour l'ensemble du processus de test, en commençant par SetFlagsRule, qui précède toutes les méthodes de configuration annotées @Before dans le test. Les valeurs des indicateurs reviennent à leur état précédent lorsque SetFlagsRule se termine, c'est-à-dire après toute méthode de configuration annotée avec @After.

Vérifier que les indicateurs sont correctement définis

Comme mentionné précédemment, SetFlagsRule est utilisé avec l'annotation JUnit @Rule, ce qui signifie que SetFlagsRule ne peut pas garantir que vos indicateurs sont correctement définis lors du constructeur de la classe de test, ni dans les méthodes annotées @BeforeClass ou @AfterClass.

Pour vous assurer que les fixtures de test sont construites avec la valeur de classe appropriée, utilisez la méthode SetFlagsRule.ClassRule afin que vos fixtures ne soient pas créées tant qu'une méthode de configuration annotée @Before n'est pas utilisée :

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

En ajoutant la règle de classe SetFlagsRule.ClassRule, test_flag_foo_turned_on échoue avant l'exécution lorsque FLAG_FLAG_FOO est lu par le constructeur de DemoClass.

Si l'ensemble de votre classe a besoin d'un indicateur activé, déplacez l'annotation @EnableFlags au niveau de la classe (avant la déclaration de la classe). Le déplacement de l'annotation au niveau de la classe permet à SetFlagsRule.ClassRule de s'assurer que l'indicateur est correctement défini lors du constructeur de la classe de test ou lors de toute méthode annotée avec @BeforeClass ou @AfterClass.

Exécuter des tests sur plusieurs configurations de flag

Étant donné que vous pouvez définir des valeurs d'indicateur pour chaque test, vous pouvez également utiliser la paramétrisation pour exécuter des tests sur plusieurs configurations d'indicateurs :

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

Notez qu'avec SetFlagsRule, mais sans paramétrisation, cette classe exécute trois tests (fooLogic, legacyBarLogic et newBarLogic). La méthode fooLogic s'exécute avec les valeurs de FLAG_FOO et FLAG_BAR définies sur l'appareil.

Lorsque la paramétrisation est ajoutée, la méthode FlagsParameterization.allCombinationsOf crée toutes les combinaisons possibles des indicateurs FLAG_FOO et FLAG_BAR :

• FLAG_FOO correspond à true et FLAG_BAR correspond à true
• FLAG_FOO est true et FLAG_BAR est false
• FLAG_FOO est false et FLAG_BAR est true
• FLAG_FOO est défini sur "false" et FLAG_BAR est défini sur false.

Au lieu de modifier directement les valeurs des indicateurs, les annotations @DisableFlags et @EnableFlags modifient les valeurs des indicateurs en fonction des conditions des paramètres. Par exemple, legacyBarLogic ne s'exécute que lorsque FLAG_BAR est désactivé, ce qui se produit dans deux des quatre combinaisons d'indicateurs. Le legacyBarLogic est ignoré pour les deux autres combinaisons.

Il existe deux méthodes pour créer les paramétrisations de vos indicateurs :

• FlagsParameterization.allCombinationsOf(String...) exécute 2^n exécutions de chaque test. Par exemple, un indicateur exécute des tests 2x ou quatre indicateurs exécutent des tests 16x.

• FlagsParameterization.progressionOf(String...) exécute n+1 exécutions de chaque test. Par exemple, un indicateur exécute des tests 2x et quatre indicateurs exécutent des indicateurs 5x.

Créer des tests unitaires (C et C++)

AOSP inclut des macros de valeur d'indicateur pour les tests C et C++ écrits dans le framework GoogleTest.

1. Dans votre source de test, incluez les définitions de macros et les bibliothèques générées par aconfig :

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

2. Dans votre source de test, au lieu d'utiliser les macros TEST et TESTF pour vos cas de test, utilisez TEST_WITH_FLAGS et 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");
   }
   

   Où :

   • Les macros TEST_WITH_FLAGS et TEST_F_WITH_FLAGS sont utilisées à la place des macros TEST et TEST_F.
   • REQUIRES_FLAGS_ENABLED définit un ensemble d'indicateurs de version de fonctionnalité qui doivent remplir la condition d'activation. Vous pouvez écrire ces indicateurs dans des macros ACONFIG_FLAG ou LEGACY_FLAG.
   • REQUIRES_FLAGS_DISABLED définit un ensemble d'indicateurs de fonctionnalité qui doivent remplir la condition "désactivé". Vous pouvez écrire ces indicateurs dans des macros ACONFIG_FLAG ou LEGACY_FLAG.
   • ACONFIG_FLAG (TEST_NS, readwrite_enabled_flag) est une macro utilisée pour les indicateurs définis dans les fichiers aconfig. Cette macro accepte un espace de noms (TEST_NS) et un nom de flag (readwrite_enabled_flag).
   • LEGACY_FLAG(aconfig_flags.cts, TEST_NS, readwrite_disabled_flag) est une macro utilisée pour les indicateurs définis par défaut dans la configuration de l'appareil.

3. Dans votre fichier de compilation Android.bp, ajoutez les bibliothèques générées par aconfig et les bibliothèques de macros pertinentes en tant que dépendance de 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. Exécutez les tests en local à l'aide de la commande suivante :

   atest FlagMacrosTests
   

   Si l'indicateur my_namespace.android.myflag.tests.my_flag est désactivé, le résultat du test est le suivant :

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

   Si l'indicateur my_namespace.android.myflag.tests.my_flag est activé, le résultat du test est le suivant :

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

Créez des tests de bout en bout ou unitaires dans lesquels les valeurs des indicateurs ne changent pas.

Pour les cas de test dans lesquels vous ne pouvez pas remplacer les indicateurs et où vous ne pouvez filtrer les tests que s'ils sont basés sur l'état actuel des indicateurs, utilisez la règle CheckFlagsRule avec les annotations RequiresFlagsEnabled et RequiresFlagsDisabled.

Les étapes suivantes vous montrent comment créer et exécuter un test de bout en bout ou un test unitaire dans lequel les valeurs des indicateurs ne peuvent pas être remplacées :

1. Dans votre code de test, utilisez CheckFlagsRule pour appliquer le filtrage des tests. Utilisez également les annotations Java RequiresFlagsEnabled et RequiredFlagsDisabled pour spécifier les exigences concernant les indicateurs pour votre test.

   Le test côté appareil utilise 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() {}
   }
   

   Le test côté hôte utilise 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. Ajoutez jflag-unit et les bibliothèques générées par aconfig à la section static_libs du fichier de compilation de votre 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. Pour exécuter le test en local, utilisez la commande suivante :

   atest FlagAnnotationTests
   

   Si le flag Flags.FLAG_FLAG_NAME_1 est désactivé, le résultat du test est le suivant :

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

   Sinon, le résultat du test est le suivant :

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

Valeurs par défaut de l'appareil

L'SetFlagsRule initialisé utilise les valeurs des options de l'appareil. Si la valeur du flag sur l'appareil n'est pas remplacée, par exemple avec adb, la valeur par défaut est la même que celle de la configuration de version de la compilation. Si la valeur sur l'appareil a été remplacée, SetFlagsRule utilise la valeur de remplacement comme valeur par défaut.

Si le même test est exécuté avec différentes configurations de version, la valeur des indicateurs qui ne sont pas explicitement définis avec SetFlagsRule peut varier.

Après chaque test, SetFlagsRule restaure l'instance FeatureFlags dans Flags à son FeatureFlagsImpl d'origine, afin qu'elle n'ait pas d'effets secondaires sur les autres méthodes et classes de test.