New MCP tool for running mobile tests (via app distribution). (#9250)

* Scaffolding for new appdistribution MCP tool.

* Refactor business logic out of the appdistribution CLI so that it can be used by an MCP tool.

* Wire new appdistribution tool up to the business logic.

* Fix linting errors.

* Update src/appdistribution/distribution.ts

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

---------

Co-authored-by: Jamie Rothfeder <[email protected]>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: 3 people

src/appdistribution/client.ts

@@ -66,7 +66,7 @@ export class AppDistributionClient {
     });
   }
 
-  async updateReleaseNotes(releaseName: string, releaseNotes: string): Promise<void> {
+  async updateReleaseNotes(releaseName: string, releaseNotes?: string): Promise<void> {
     if (!releaseNotes) {
       utils.logWarning("no release notes specified, skipping");
       return;

src/appdistribution/distribution.ts

@@ -1,14 +1,186 @@
 import * as fs from "fs-extra";
-import { FirebaseError, getErrMsg } from "../error";
 import { logger } from "../logger";
 import * as pathUtil from "path";
+import * as utils from "../utils";
+import {
+  AabInfo,
+  IntegrationState,
+  UploadReleaseResult,
+  TestDevice,
+  ReleaseTest,
+  LoginCredential,
+} from "../appdistribution/types";
+import { AppDistributionClient } from "./client";
+import { FirebaseError, getErrMsg, getErrStatus } from "../error";
 
 export enum DistributionFileType {
   IPA = "ipa",
   APK = "apk",
   AAB = "aab",
 }
 
+const TEST_MAX_POLLING_RETRIES = 40;
+const TEST_POLLING_INTERVAL_MILLIS = 30_000;
+
+/**
+ * Execute an app distribution action
+ */
+export async function distribute(
+  appName: string,
+  distribution: Distribution,
+  testCases: string[],
+  testDevices: TestDevice[],
+  releaseNotes?: string,
+  testers?: string[],
+  groups?: string[],
+  testNonBlocking?: boolean,
+  loginCredential?: LoginCredential,
+) {
+  const requests = new AppDistributionClient();
+  let aabInfo: AabInfo | undefined;
+  if (distribution.distributionFileType() === DistributionFileType.AAB) {
+    try {
+      aabInfo = await requests.getAabInfo(appName);
+    } catch (err: unknown) {
+      if (getErrStatus(err) === 404) {
+        throw new FirebaseError(
+          `App Distribution could not find your app ${appName}. ` +
+            `Make sure to onboard your app by pressing the "Get started" ` +
+            "button on the App Distribution page in the Firebase console: " +
+            "https://console.firebase.google.com/project/_/appdistribution",
+          { exit: 1 },
+        );
+      }
+      throw new FirebaseError(`failed to determine AAB info. ${getErrMsg(err)}`, { exit: 1 });
+    }
+
+    if (
+      aabInfo.integrationState !== IntegrationState.INTEGRATED &&
+      aabInfo.integrationState !== IntegrationState.AAB_STATE_UNAVAILABLE
+    ) {
+      switch (aabInfo.integrationState) {
+        case IntegrationState.PLAY_ACCOUNT_NOT_LINKED: {
+          throw new FirebaseError("This project is not linked to a Google Play account.");
+        }
+        case IntegrationState.APP_NOT_PUBLISHED: {
+          throw new FirebaseError('"This app is not published in the Google Play console.');
+        }
+        case IntegrationState.NO_APP_WITH_GIVEN_BUNDLE_ID_IN_PLAY_ACCOUNT: {
+          throw new FirebaseError("App with matching package name does not exist in Google Play.");
+        }
+        case IntegrationState.PLAY_IAS_TERMS_NOT_ACCEPTED: {
+          throw new FirebaseError(
+            "You must accept the Play Internal App Sharing (IAS) terms to upload AABs.",
+          );
+        }
+        default: {
+          throw new FirebaseError(
+            "App Distribution failed to process the AAB: " + aabInfo.integrationState,
+          );
+        }
+      }
+    }
+  }
+
+  utils.logBullet("uploading binary...");
+  let releaseName;
+  try {
+    const operationName = await requests.uploadRelease(appName, distribution);
+
+    // The upload process is asynchronous, so poll to figure out when the upload has finished successfully
+    const uploadResponse = await requests.pollUploadStatus(operationName);
+
+    const release = uploadResponse.release;
+    switch (uploadResponse.result) {
+      case UploadReleaseResult.RELEASE_CREATED:
+        utils.logSuccess(
+          `uploaded new release ${release.displayVersion} (${release.buildVersion}) successfully!`,
+        );
+        break;
+      case UploadReleaseResult.RELEASE_UPDATED:
+        utils.logSuccess(
+          `uploaded update to existing release ${release.displayVersion} (${release.buildVersion}) successfully!`,
+        );
+        break;
+      case UploadReleaseResult.RELEASE_UNMODIFIED:
+        utils.logSuccess(
+          `re-uploaded already existing release ${release.displayVersion} (${release.buildVersion}) successfully!`,
+        );
+        break;
+      default:
+        utils.logSuccess(
+          `uploaded release ${release.displayVersion} (${release.buildVersion}) successfully!`,
+        );
+    }
+    utils.logSuccess(`View this release in the Firebase console: ${release.firebaseConsoleUri}`);
+    utils.logSuccess(`Share this release with testers who have access: ${release.testingUri}`);
+    utils.logSuccess(
+      `Download the release binary (link expires in 1 hour): ${release.binaryDownloadUri}`,
+    );
+    releaseName = uploadResponse.release.name;
+  } catch (err: unknown) {
+    if (getErrStatus(err) === 404) {
+      throw new FirebaseError(
+        `App Distribution could not find your app ${appName}. ` +
+          `Make sure to onboard your app by pressing the "Get started" ` +
+          "button on the App Distribution page in the Firebase console: " +
+          "https://console.firebase.google.com/project/_/appdistribution",
+        { exit: 1 },
+      );
+    }
+    throw new FirebaseError(`Failed to upload release. ${getErrMsg(err)}`, { exit: 1 });
+  }
+
+  // If this is an app bundle and the certificate was originally blank fetch the updated
+  // certificate and print
+  if (aabInfo && !aabInfo.testCertificate) {
+    aabInfo = await requests.getAabInfo(appName);
+    if (aabInfo.testCertificate) {
+      utils.logBullet(
+        "After you upload an AAB for the first time, App Distribution " +
+          "generates a new test certificate. All AAB uploads are re-signed with this test " +
+          "certificate. Use the certificate fingerprints below to register your app " +
+          "signing key with API providers, such as Google Sign-In and Google Maps.\n" +
+          `MD-1 certificate fingerprint: ${aabInfo.testCertificate.hashMd5}\n` +
+          `SHA-1 certificate fingerprint: ${aabInfo.testCertificate.hashSha1}\n` +
+          `SHA-256 certificate fingerprint: ${aabInfo.testCertificate.hashSha256}`,
+      );
+    }
+  }
+
+  // Add release notes and distribute to testers/groups
+  await requests.updateReleaseNotes(releaseName, releaseNotes);
+  await requests.distribute(releaseName, testers, groups);
+
+  // Run automated tests
+  if (testDevices.length) {
+    utils.logBullet("starting automated test (note: this feature is in beta)");
+    const releaseTestPromises: Promise<ReleaseTest>[] = [];
+    if (!testCases.length) {
+      // fallback to basic automated test
+      releaseTestPromises.push(
+        requests.createReleaseTest(releaseName, testDevices, loginCredential),
+      );
+    } else {
+      for (const testCaseId of testCases) {
+        releaseTestPromises.push(
+          requests.createReleaseTest(
+            releaseName,
+            testDevices,
+            loginCredential,
+            `${appName}/testCases/${testCaseId}`,
+          ),
+        );
+      }
+    }
+    const releaseTests = await Promise.all(releaseTestPromises);
+    utils.logSuccess(`${releaseTests.length} release test(s) started successfully`);
+    if (!testNonBlocking) {
+      await awaitTestResults(releaseTests, requests);
+    }
+  }
+}
+
 /**
  * Object representing an APK, AAB or IPA file. Used for uploading app distributions.
  */
@@ -58,3 +230,59 @@ export class Distribution {
     return this.fileName;
   }
 }
+
+async function awaitTestResults(
+  releaseTests: ReleaseTest[],
+  requests: AppDistributionClient,
+): Promise<void> {
+  const releaseTestNames = new Set(releaseTests.map((rt) => rt.name).filter((n): n is string => !!n));
+  for (let i = 0; i < TEST_MAX_POLLING_RETRIES; i++) {
+    utils.logBullet(`${releaseTestNames.size} automated test results are pending...`);
+    await delay(TEST_POLLING_INTERVAL_MILLIS);
+    for (const releaseTestName of releaseTestNames) {
+      const releaseTest = await requests.getReleaseTest(releaseTestName);
+      if (releaseTest.deviceExecutions.every((e) => e.state === "PASSED")) {
+        releaseTestNames.delete(releaseTestName);
+        if (releaseTestNames.size === 0) {
+          utils.logSuccess("Automated test(s) passed!");
+          return;
+        } else {
+          continue;
+        }
+      }
+      for (const execution of releaseTest.deviceExecutions) {
+        switch (execution.state) {
+          case "PASSED":
+          case "IN_PROGRESS":
+            continue;
+          case "FAILED":
+            throw new FirebaseError(
+              `Automated test failed for ${deviceToString(execution.device)}: ${execution.failedReason}`,
+              { exit: 1 },
+            );
+          case "INCONCLUSIVE":
+            throw new FirebaseError(
+              `Automated test inconclusive for ${deviceToString(execution.device)}: ${execution.inconclusiveReason}`,
+              { exit: 1 },
+            );
+          default:
+            throw new FirebaseError(
+              `Unsupported automated test state for ${deviceToString(execution.device)}: ${execution.state}`,
+              { exit: 1 },
+            );
+        }
+      }
+    }
+  }
+  throw new FirebaseError("It took longer than expected to run your test(s), please try again.", {
+    exit: 1,
+  });
+}
+
+function delay(ms: number): Promise<number> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function deviceToString(device: TestDevice): string {
+  return `${device.model} (${device.version}/${device.orientation}/${device.locale})`;
+}

src/appdistribution/options-parser-util.ts

@@ -8,7 +8,7 @@ import { FieldHints, LoginCredential, TestDevice } from "./types";
  * file and converts the input into an string[].
  * Value takes precedent over file.
  */
-export function parseIntoStringArray(value: string, file: string): string[] {
+export function parseIntoStringArray(value: string, file = ""): string[] {
   // If there is no value then the file gets parsed into a string to be split
   if (!value && file) {
     ensureFileExists(file);
@@ -61,7 +61,10 @@ export function getAppName(options: any): string {
   if (!options.app) {
     throw new FirebaseError("set the --app option to a valid Firebase app id and try again");
   }
-  const appId = options.app;
+  return toAppName(options.app);
+}
+
+export function toAppName(appId: string) {
   return `projects/${appId.split(":")[1]}/apps/${appId}`;
 }
 
@@ -70,7 +73,7 @@ export function getAppName(options: any): string {
  * and converts the input into a string[] of test device strings.
  * Value takes precedent over file.
  */
-export function parseTestDevices(value: string, file: string): TestDevice[] {
+export function parseTestDevices(value: string, file = ""): TestDevice[] {
   // If there is no value then the file gets parsed into a string to be split
   if (!value && file) {
     ensureFileExists(file);