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é
Scénario de test | Mécanisme utilisé |
---|---|
Tests locaux lorsque les valeurs des indicateurs changent souvent | Android Debug Bridge, comme indiqué dans Modifier la valeur d'un indicateur au moment de l'exécution |
Tests en local lorsque les valeurs des indicateurs ne changent pas souvent | Fichier de valeurs d'indicateurs, comme indiqué dans Définir les valeurs des indicateurs de lancement de fonctionnalités |
Tests de bout en bout où les valeurs des indicateurs changent | FeatureFlagTargetPreparer , comme indiqué dans Créer des tests de bout en bout |
Tests unitaires lorsque les valeurs des indicateurs changent | SetFlagsRule avec @EnableFlags et @DisableFlags , comme indiqué dans Créer des tests unitaires (Java et Kotlin) ou Créer des tests unitaires (C et C++) |
Tests de bout en bout ou unitaires où les valeurs des indicateurs ne peuvent pas changer | CheckFlagsRule , comme indiqué dans Créer des tests de bout en bout ou unitaires lorsque les valeurs des indicateurs ne changent pas |
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 surcom.android.tradefed.targetprep.FeatureFlagTargetPreparer
.option
est la substitution d'option avecname
toujours défini surflag-value
etvalue
défini surnamespace/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 :
Incluez
FeatureFlagTargetPreparer
dans le fichier de configuration du module de testAndroidTest.xml
:<target_preparer class="com.android.tradefed.targetprep.FeatureFlagTargetPreparer" >
Spécifiez les options de valeur du flag dans la section
test_module_config
d'un fichier de compilationAndroid.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, avecname
toujours défini surflag-value
etvalue
défini surnamespace/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 :
- Utilisez la classe
SetFlagsRule
avec les annotations@EnableFlags
et@DisableFlags
pour tester toutes les branches de code. - Utilisez la méthode
SetFlagsRule.ClassRule
pour éviter les bugs de test courants. - 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 classeSetFlagsRule
.SetFlagsRule
est une classe d'assistance fournie pour remplacer les valeurs des indicateurs. Pour savoir commentSetFlagsRule
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
etFLAG_BAR
correspond àtrue
FLAG_FOO
esttrue
etFLAG_BAR
estfalse
FLAG_FOO
estfalse
etFLAG_BAR
esttrue
FLAG_FOO
est défini sur "false" etFLAG_BAR
est défini surfalse
.
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.
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"
Dans votre source de test, au lieu d'utiliser les macros
TEST
etTESTF
pour vos cas de test, utilisezTEST_WITH_FLAGS
etTEST_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
etTEST_F_WITH_FLAGS
sont utilisées à la place des macrosTEST
etTEST_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 macrosACONFIG_FLAG
ouLEGACY_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 macrosACONFIG_FLAG
ouLEGACY_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.
- Les macros
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"], ... }
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 :
Dans votre code de test, utilisez
CheckFlagsRule
pour appliquer le filtrage des tests. Utilisez également les annotations JavaRequiresFlagsEnabled
etRequiredFlagsDisabled
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() {} }
Ajoutez
jflag-unit
et les bibliothèques générées par aconfig à la sectionstatic_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"], }
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.