Get started with Game Loop tests for iOS

Generate an IPA for your app

1. In Xcode, select a provisioning profile for the target app.
2. From the drop-down menu that appears, click Product > Archive. Select the most recent archive, then click Distribute App.
3. In the window that appears, click Development > Next.
4. Optional: To get a faster build, deselect the Rebuild from Bitcode option, then click Next. Test Lab doesn’t require thinning or rebuilding your app to run a test so you can safely disable this option.
5. Click Export, then enter a directory in which you want to download your app’s IPA file.

Run a test in the Firebase console

1. In the Firebase console, go to DevOps & Engagement > Test Lab.

2. Click Run Your First Test > Run an iOS Game Loop.

3. In the Upload App section, click Browse, then select your app's IPA file (if you haven't already, generate an IPA file for your app).

4. (Optional) If you want to run multiple loops (aka scenarios) at a time or select specific loops to run, enter the loop numbers in the Scenarios field.

   For example, when you enter 1-3, 5, Test Lab runs loops 1, 2, 3, and 5. By default (if you don't enter anything in the Scenarios field), Test Lab only runs loop 1.

5. In the Devices section, select one or more physical devices you want to test your app on, then click Start Tests.

Run a test with the gcloud beta CLI

1. If you haven't already, configure your local gcloud SDK environment, then make sure to install the gcloud beta component.

2. Run the gcloud beta firebase test ios run command and use the following flags to configure the run:

For example, the following command runs a Game Loop test that executes loops 1, 4, 6, 7, and 8 on an 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

For more information on the gcloud CLI, see the reference documentation.

Run a test locally

To run your test locally, load your gaming app in a simulator and run:

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

• You can find your simulator's UDID by running the instruments -s devices command.

• If there is only one simulator running, enter the special string "booted" in place of SIMULATOR_UDID.

If your test contains multiple loops, you can specify which loop you want to run by passing the loop number to the scenario flag. Note that you can only run one loop at a time when running your test locally. For example, if you want to run loops 1, 2, and 5, you must run a separate command for each loop:

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

End a test early

By default, a Game Loop test continues running until it reaches a timeout of five minutes, even when all the loops have been executed. When the timeout is reached, the test ends and cancels any pending loops. You can speed up your test or end it early by calling Test Lab’s custom URL scheme firebase-game-loop-complete in your app’s AppDelegate. For example:

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

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

Your Game Loop test terminates the current loop and executes the next loop. When there are no more loops to run, the test ends.

Write custom test results

You can configure your Game Loop test to write custom test results to your device’s file system. This way, when the test starts running, Test Lab stores the result files in a GameLoopsResults directory on your testing device (which you must create yourself). When the test ends, Test Lab moves all files from the GameLoopResults directory to your project's bucket. Keep the following in mind when setting up your test:

• All result files are uploaded regardless of file type, size, or quantity.

• Test Lab doesn’t process your test results until all the loops in your test have finished running, so if your test includes multiple loops that write output, make sure you append them to a unique result file or create a result file for each loop. This way, you can avoid overwriting results from a previous loop.

To set up your test to write custom test results:

1. In your app's Documents directory, create a directory named GameLoopResults.

2. From anywhere in your app’s code (e.g., your app delegate), add the following:

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