Premiers pas avec les tests de boucle de jeu pour iOS

Avec les tests de boucle de jeu, vous pouvez écrire des tests natifs de votre moteur de jeu, puis les exécuter dans Test Lab sur les appareils de votre choix. Vous n'avez donc pas à vous soucier d'écrire pour différents frameworks d'UI ou de test. Un test de boucle de jeu simule les actions d'un joueur réel. Lorsque vous l'exécutez sur Test Lab, il vous permet de vérifier rapidement et de manière évolutive que votre jeu fonctionne correctement pour vos utilisateurs.

Cette page explique comment exécuter un test de boucle de jeu, puis afficher et gérer les résultats de votre test sur la page Test Lab de la console Firebase. Vous pouvez également personnaliser davantage vos tests avec des fonctionnalités facultatives, telles que l'écriture de résultats de test personnalisés ou l'arrêt anticipé de votre test.

Remarque :Vous pouvez utiliser Test Lab sans frais avec le forfait Spark, qui est associé à un quota quotidien limité. Pour en savoir plus sur les autres formules et limites d'utilisation, consultez les formules Firebase.

Qu'est-ce qu'un test de boucle de jeu ?

Une boucle est une exécution complète ou partielle de votre test sur votre application de jeu. Vous pouvez exécuter un test de boucle de jeu en local sur un simulateur ou sur un ensemble d'appareils dans Test Lab. Les tests de boucle de jeu peuvent être utilisés pour:

• Parcourez votre jeu comme un utilisateur final le ferait. Vous pouvez écrire un script pour l'entrée de l'utilisateur, laisser l'utilisateur inactif ou le remplacer par une IA (par exemple, si vous avez implémenté une IA dans un jeu de course automobile, vous pouvez confier à un pilote IA la gestion de l'entrée de l'utilisateur).

• Exécutez votre jeu avec le paramètre de qualité le plus élevé pour savoir quels appareils peuvent le prendre en charge.

• Exécutez un test technique, par exemple en compilant plusieurs nuanceurs, en les exécutant et en vérifiant que la sortie est conforme à vos attentes.

Étape 1: Enregistrer le schéma d'URL personnalisée de Test Lab

Vous devez d'abord enregistrer le schéma d'URL personnalisé de Firebase Test Lab dans votre application:

1. Dans Xcode, sélectionnez une cible de projet.

2. Cliquez sur l'onglet Infos, puis ajoutez un type d'URL.

3. Dans le champ Schémas d'URL, saisissez firebase-game-loop. Vous pouvez également enregistrer le schéma d'URL personnalisé en l'ajoutant au fichier de configuration Info.plist de votre projet n'importe où dans la balise <dict>:

   <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleURLName</key>
            <string></string>
            <key>CFBundleTypeRole</key>
            <string>Editor</string>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>firebase-game-loop</string>
            </array>
        </dict>
    </array>
   

Votre application est maintenant configurée pour exécuter un test à l'aide de Test Lab.

Étape 2 (facultatif): Configurez votre application pour qu'elle exécute plusieurs boucles

Si votre application enregistre plusieurs schémas d'URL personnalisés et que vous prévoyez d'exécuter plusieurs boucles (ou scénarios) dans votre test, vous devez spécifier les boucles que vous souhaitez exécuter dans votre application au moment du lancement.

Dans le délégué de votre application, remplacez la méthode application(_:open:options:):

Swift

func application(_app: UIApplication,
                 open url: URL
                 options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    let components = URLComponents(url: url, resolvingAgainstBaseURL: true)!
    if components.scheme == "firebase-game-loop" {
        // ...Enter Game Loop Test logic to override application(_:open:options:).
    }
    return true
}

Objective-C

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary <UIApplicationOpenURLOptionsKey, id> *)options {
  if ([url.scheme isEqualToString:(@"firebase-game-loop")]) {
      // ...Enter Game Loop Test logic to override application(_:open:options:).
  }
}

Lorsque vous exécutez plusieurs boucles dans votre test, la boucle actuelle est transmise en tant que paramètre à l'URL utilisée pour lancer l'application. Vous pouvez également obtenir le numéro de boucle actuel en analysant l'objet URLComponents utilisé pour extraire le schéma d'URL personnalisé:

Swift

if components.scheme == "firebase-game-loop" {
    // Iterate over all parameters and find the one with the key "scenario".
    let scenarioNum = Int(components.queryItems!.first(where: { $0.name == "scenario" })!.value!)!
    // ...Write logic specific to the current loop (scenarioNum).
}

Objective-C

if ([url.scheme isEqualToString:(@"firebase-game-loop")]) {
    // Launch the app as part of a game loop.
    NSURLComponents *components = [NSURLComponents componentsWithURL:url
                                             resolvingAgainstBaseURL:YES];
    for (NSURLQueryItem *item in [components queryItems]) {
        if ([item.name isEqualToString:@"scenario"]) {
            NSInteger scenarioNum = [item.value integerValue];
            // ...Write logic specific to the current loop (scenarioNum).
        }
    }
}

Étape 3: Créer et exécuter un test

Une fois que vous avez enregistré le schéma d'URL personnalisé de Test Lab, vous pouvez exécuter votre test dans la console Firebase ou avec la CLI gcloud bêta. Si ce n'est pas déjà fait, générez un fichier IPA pour votre application (vous devrez le localiser plus tard).

Conseil:Avant d'utiliser Test Lab, vous pouvez d'abord vous assurer que vos boucles de jeu fonctionnent comme prévu en exécutant votre test localement sur un simulateur

.

Générer un fichier IPA pour votre application

1. Dans Xcode, sélectionnez un profil de provisionnement pour l'application cible.
   Remarque: Test Lab signe à nouveau votre application avec son propre profil de provisionnement et son propre certificat.
2. Dans le menu déroulant qui s'affiche, cliquez sur Product > Archive (Produit > Archiver). Sélectionnez l'archive la plus récente, puis cliquez sur Distribuer l'application.
3. Dans la fenêtre qui s'affiche, cliquez sur Développement > Suivant.
4. Facultatif:Pour obtenir une compilation plus rapide, désélectionnez l'option Rebuild from Bitcode (Recompiler à partir du bitcode), puis cliquez sur Next (Suivant). Test Lab ne nécessite pas d'amincir ni de recompiler votre application pour exécuter un test. Vous pouvez donc désactiver cette option en toute sécurité.
5. Cliquez sur Exporter, puis saisissez un répertoire dans lequel vous souhaitez télécharger le fichier IPA de votre application.

Exécuter un test dans la console Firebase

1. Si ce n'est pas déjà fait, ouvrez la console Firebase et créez un projet.

2. Sur la page Test Lab de la console Firebase, cliquez sur Exécuter votre premier test > Exécuter une boucle de jeu iOS.

3. Dans la section Importer une application, cliquez sur Parcourir, puis sélectionnez le fichier IPA de votre application (si vous ne l'avez pas déjà fait, générez un fichier IPA pour votre application).

4. Facultatif: Si vous souhaitez exécuter plusieurs boucles (ou scénarios) à la fois ou sélectionner des boucles spécifiques à exécuter, saisissez les numéros de boucle dans le champ Scenarios (Scénarios).

   Par exemple, lorsque vous saisissez "1-3, 5", Test Lab exécute les boucles 1, 2, 3 et 5. Par défaut (si vous ne saisissez rien dans le champ Scénarios), Test Lab n'exécute que la boucle 1.

5. Dans la section Devices (Appareils), sélectionnez un ou plusieurs appareils physiques sur lesquels vous souhaitez tester votre application, puis cliquez sur Start Tests (Démarrer les tests).

Exécuter un test avec la CLI bêta de gcloud

Remarque:La commande de la CLI gcloud bêta pour les tests Game Loop sur iOS est une version bêta. Cela signifie que la fonctionnalité peut faire l'objet de modifications susceptibles d'affecter la compatibilité ascendante. Une version bêta n'est soumise à aucun contrat de niveau de service ni à aucun règlement d'obsolescence. Elle peut bénéficier d'une assistance limitée ou aucune.

1. Si ce n'est pas déjà fait, configurez votre environnement de SDK gcloud local, puis assurez-vous d'installer le composant bêta gcloud.

2. Exécutez la commande gcloud beta firebase test ios run et utilisez les options suivantes pour configurer l'exécution:

Options pour les tests de boucle de jeu
--type	Obligatoire: spécifie le type de test iOS que vous souhaitez exécuter. Vous pouvez saisir les types de test xctest (par défaut) ou game-loop.
--app	Obligatoire: chemin d'accès absolu (Google Cloud Storage ou système de fichiers) au fichier IPA de votre application. Cet indicateur n'est valide que lors de l'exécution de tests de boucle de jeu.
--scenario-numbers	Les boucles (ou scénarios) que vous souhaitez exécuter dans votre application. Vous pouvez saisir une boucle, une liste de boucles ou une plage de boucles. La boucle par défaut est 1. Par exemple, --scenario-numbers=1-3,5 exécute les boucles 1, 2, 3 et 5.
--device-model	L'appareil physique sur lequel vous souhaitez exécuter votre test (découvrez les appareils disponibles que vous pouvez utiliser).
--timeout	Durée maximale d'exécution du test. Vous pouvez saisir un entier pour représenter la durée en secondes, ou un entier et une énumération pour représenter la durée en tant qu'unité de temps plus longue. Exemple : --timeout=200 force la fin de votre test lorsqu'il s'exécute pendant 200 secondes. --timeout=1h force l'arrêt de votre test lorsqu'il s'exécute pendant une heure.

Par exemple, la commande suivante exécute un test de boucle de jeu qui exécute les boucles 1, 4, 6, 7 et 8 sur un iPhone 8 Plus:

gcloud beta firebase test ios run
 --type game-loop --app path/to/my/App.ipa --scenario-numbers 1,4,6-8
 --device-model=iphone8plus

Pour en savoir plus sur la gcloud CLI, consultez la documentation de référence.

Exécuter un test en local

Pour exécuter votre test localement, chargez votre application de jeu dans un simulateur et exécutez:

xcrun simctl openurl SIMULATOR_UDID firebase-game-loop://

• Vous pouvez trouver l'UDID de votre simulateur en exécutant la commande instruments -s devices.

• Si un seul simulateur est en cours d'exécution, saisissez la chaîne spéciale "booted" à la place de SIMULATOR_UDID.

Si votre test contient plusieurs boucles, vous pouvez spécifier celle que vous souhaitez exécuter en transmettant le numéro de boucle à l'indicateur scenario. Notez que vous ne pouvez exécuter qu'une seule boucle à la fois lorsque vous exécutez votre test localement. Par exemple, si vous souhaitez exécuter les boucles 1, 2 et 5, vous devez exécuter une commande distincte pour chaque boucle:

xcrun simctl openurl SIMULATOR_UDID firebase-game-loop://?scenario=1
xcrun simctl openurl SIMULATOR_UDID firebase-game-loop://?scenario=2
xcrun simctl openurl SIMULATOR_UDID firebase-game-loop://?scenario=5

Arrêter un test prématurément

Par défaut, un test de boucle de jeu continue de s'exécuter jusqu'à ce qu'il atteigne un délai avant expiration de cinq minutes, même lorsque toutes les boucles ont été exécutées. Lorsque le délai avant expiration est atteint, le test se termine et annule toutes les boucles en attente. Vous pouvez accélérer votre test ou le terminer prématurément en appelant le schéma d'URL personnalisé firebase-game-loop-complete de Test Lab dans l'AppDelegate de votre application. Exemple :

Swift

/// End the loop by calling our custom url scheme.
func finishLoop() {
    let url = URL(string: "firebase-game-loop-complete://")!
    UIApplication.shared.open(url)
}

Objective-C

- (void)finishLoop {
  UIApplication *app = [UIApplication sharedApplication];
  [app openURL:[NSURL URLWithString:@"firebase-game-loop-complete://"]
      options:@{}
completionHandler:^(BOOL success) {}];
}

Votre test de boucle de jeu met fin à la boucle en cours et exécute la suivante. Lorsque plus aucune boucle n'est à exécuter, le test se termine.

Écrire des résultats de test personnalisés

Vous pouvez configurer votre test de boucle de jeu pour écrire des résultats de test personnalisés dans le système de fichiers de votre appareil. De cette façon, lorsque le test commence à s'exécuter, Test Lab stocke les fichiers de résultats dans un répertoire GameLoopsResults sur votre appareil de test (que vous devez créer vous-même). À la fin du test, Test Lab déplace tous les fichiers du répertoire GameLoopResults vers le bucket de votre projet. Tenez compte des points suivants lorsque vous configurez votre test:

• Tous les fichiers de résultats sont importés, quel que soit leur type, leur taille ou leur quantité.

• Test Lab ne traite pas les résultats de votre test tant que toutes les boucles de votre test n'ont pas terminé leur exécution. Par conséquent, si votre test inclut plusieurs boucles qui écrivent une sortie, assurez-vous de les ajouter à un fichier de résultats unique ou de créer un fichier de résultats pour chaque boucle. Vous évitez ainsi d'écraser les résultats d'une boucle précédente.

Pour configurer votre test afin d'écrire des résultats de test personnalisés:

1. Dans le répertoire Documents de votre application, créez un répertoire nommé GameLoopResults.

2. Dans n'importe quelle partie du code de votre application (par exemple, votre délégué d'application), ajoutez ce qui suit:

   Swift

   /// Write to a results file.
   func writeResults() {
     let text = "Greetings from game loops!"
     let fileName = "results.txt"
     let fileManager = FileManager.default
     do {
   
     let docs = try fileManager.url(for: .documentDirectory,
                                    in: .userDomainMask,
                                    appropriateFor: nil,
                                    create: true)
     let resultsDir = docs.appendingPathComponent("GameLoopResults")
     try fileManager.createDirectory(
         at: resultsDir,
         withIntermediateDirectories: true,
         attributes: nil)
     let fileURL = resultsDir.appendingPathComponent(fileName)
     try text.write(to: fileURL, atomically: false, encoding: .utf8)
     } catch {
       // ...Handle error writing to file.
     }
   }
   

   Objective-C

   /// Write to a results file.
   - (void)writeResults:(NSString *)message {
       // Locate and create the results directory (if it doesn't exist already).
       NSFileManager *manager = [NSFileManager defaultManager];
       NSURL* url = [[manager URLsForDirectory:NSDocumentDirectory
                                     inDomains:NSUserDomainMask] lastObject];
       NSURL* resultsDir = [url URLByAppendingPathComponent:@"GameLoopResults"
                                                isDirectory:YES];
       [manager createDirectoryAtURL:resultsDir
         withIntermediateDirectories:NO
                          attributes:nil
                               error:nil];
   
       // Write the result message to a text file.
       NSURL* resultFile = [resultsDir URLByAppendingPathComponent:@"result.txt"];
       if ([manager fileExistsAtPath:[resultFile path]]) {
           // Append to the existing file
           NSFileHandle *handle = [NSFileHandle fileHandleForWritingToURL:resultFile
                                                                    error:nil];
           [handle seekToEndOfFile];
           [handle writeData:[message dataUsingEncoding:NSUTF8StringEncoding]];
           [handle closeFile];
       } else {
           // Create and write to the file.
           [message writeToURL:resultFile
                    atomically:NO
                      encoding:NSUTF8StringEncoding error:nil];
       }
   }