Premiers pas avec les tests de boucle de jeu pour iOS

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

Cette page vous explique comment exécuter un test de boucle de jeu, puis comment afficher et gérer les résultats de vos tests sur la page Test Lab de la console Firebase. Vous pouvez également personnaliser davantage vos tests à l'aide de fonctionnalités facultatives, comme 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 la formule Spark, qui est fournie avec 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 localement sur un simulateur ou sur un ensemble d'appareils dans Test Lab. Les tests de boucles de jeu peuvent être utilisés pour :

• exécuter votre jeu comme le ferait un utilisateur final ; vous pouvez scripter l'entrée de l'utilisateur, le laisser 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 la saisie de l'utilisateur à un pilote IA) ;

• exécuter votre jeu avec le paramètre de qualité le plus élevé pour déterminer quels appareils peuvent le prendre en charge ;

• exécuter un test technique, par exemple en compilant plusieurs shaders, en les exécutant et en vérifiant que le résultat est celui attendu.

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

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

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

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

3. Dans le champ URL Schemes (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 (facultative) : Configurer votre application pour exécuter plusieurs boucles

Si plusieurs schémas d'URL personnalisés sont enregistrés dans votre application et que vous prévoyez d'exécuter plusieurs boucles (également appelées 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 récupérer 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 gcloud beta CLI. Si ce n'est pas déjà fait, générez un fichier IPA pour votre application (vous devrez le localiser ultérieurement).

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 Distribute App (Distribuer l'application).
3. Dans la fenêtre qui s'affiche, cliquez sur Development > Next (Développement > Suivant).
4. Facultatif : Pour accélérer la compilation, désélectionnez l'option Rebuild from Bitcode (Recompiler à partir de Bitcode), puis cliquez sur Next (Suivant). Test Lab n'a pas besoin de réduire ou de reconstruire votre application pour exécuter un test. Vous pouvez donc désactiver cette option en toute sécurité.
5. Cliquez sur Export (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. Dans la console Firebase, accédez à DevOps & Engagement > Test Lab.

2. Cliquez sur Run Your First Test > Run an iOS Game Loop (Exécuter votre premier test > Exécuter une boucle de jeu iOS).

3. Dans la section Upload App (Importer l'application), cliquez sur Browse (Parcourir), puis sélectionnez le fichier IPA de votre application (si ce n'est pas déjà fait, générez un fichier IPA pour votre application).

4. (Facultatif) Si vous souhaitez exécuter plusieurs boucles (également appelées 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 Scenarios), 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 gcloud beta CLI

Remarque : La commande de la gcloud beta CLI pour les tests de boucles de jeu iOS est une version bêta. Cela signifie que les fonctionnalités peuvent 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 relatif aux abandons, et peut bénéficier d'une assistance limitée, voire inexistante.

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

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 boucles 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. Cette option n'est valide que lors de l'exécution de tests de boucles de jeu.
--scenario-numbers	Les boucles (également appelées 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	La durée maximale pendant laquelle vous souhaitez exécuter votre 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 l'arrêt de votre test lorsqu'il atteint 200 secondes. --timeout=1h force l'arrêt de votre test lorsqu'il atteint 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 localement

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 la boucle que vous souhaitez exécuter en transmettant le numéro de boucle à l'option 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 plus tôt que prévu

Par défaut, un test de boucle de jeu continue de s'exécuter jusqu'à ce qu'il atteigne un délai d'inactivité de cinq minutes, même lorsque toutes les boucles ont été exécutées. Lorsque le délai d'inactivité est atteint, le test se termine et annule toutes les boucles en attente. Vous pouvez accélérer votre test ou l'arrêter plus tôt que prévu en appelant Test Lab’s custom URL scheme firebase-game-loop-complete 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 actuelle et exécute la boucle suivante. Lorsqu'il n'y a plus de boucles à 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. Ainsi, 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). Une fois le test terminé, 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, quels que soient leur type, leur taille ou leur quantité.

• Test Lab ne traite pas les résultats de vos tests tant que toutes les boucles de votre test ne sont pas terminées. Par conséquent, si votre test inclut plusieurs boucles qui écrivent des résultats, assurez-vous de les ajouter à un fichier de résultats unique ou de créer un fichier de résultats pour chaque boucle. Vous éviterez ainsi d'écraser les résultats d'une boucle précédente.

Pour configurer votre test afin qu'il écrive des résultats de test personnalisés :

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

2. N'importe où dans le code de votre application (par exemple, dans le délégué de votre application), ajoutez les éléments suivants :

   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];
       }
   }