add --other-app cli

jochen-testingbot · jochen-testingbot · commit db394201ccdc · 2026-05-19T10:28:40.000+02:00
diff --git a/README.md b/README.md
@@ -92,6 +92,13 @@ testingbot maestro <app> <flows...> [options]
 - `app` - Path to your app file (.apk, .ipa, .app, or .zip)
 - `flows` - One or more paths to flow files (.yaml/.yml), directories, .zip files, or glob patterns
 
+**App Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--app <path>` | Path to the application under test (alternative to the positional `app` argument) |
+| `--other-app <path>` | Additional companion app to install on the device alongside `--app`. Repeatable, **max 4** entries. |
+
 **Device Options:**
 
 | Option | Description |
@@ -179,6 +186,12 @@ testingbot maestro app.apk ./flows --groups "smoke,critical"
 # With environment variables
 testingbot maestro app.apk ./flows -e API_URL=https://staging.example.com -e API_KEY=secret
 
+# With companion apps installed alongside the main app (up to 4)
+testingbot maestro --app main.apk \
+  --other-app helper.apk \
+  --other-app mock-server.apk \
+  ./flows
+
 # Download JUnit report
 testingbot maestro app.apk ./flows --report junit --report-output-dir ./reports
 
diff --git a/src/cli.ts b/src/cli.ts
@@ -258,6 +258,15 @@ program
     '--app <path>',
     'Path to application under test (.apk, .ipa, .app, or .zip).',
   )
+  .option(
+    '--other-app <path>',
+    'Additional app to install alongside --app (.apk, .ipa, .app, or .zip). Repeatable, max 4.',
+    (val: string, acc: string[]) => {
+      acc.push(val);
+      return acc;
+    },
+    [] as string[],
+  )
   // Device configuration
   .option(
     '--device <device>',
@@ -292,7 +301,11 @@ program
   .option(
     '--groups <names>',
     'Tag the test session with one or more groups (comma-separated).',
-    (val) => val.split(',').map((g) => g.trim()).filter((g) => g.length > 0),
+    (val) =>
+      val
+        .split(',')
+        .map((g) => g.trim())
+        .filter((g) => g.length > 0),
   )
   // Network and geo
   .option(
@@ -423,6 +436,18 @@ program
         );
       }
 
+      const otherApps: string[] = Array.isArray(args.otherApp)
+        ? args.otherApp.slice()
+        : [];
+      // Commander stores the accumulator on a shared default array; reset it so
+      // values do not leak across repeated parses (e.g. in tests).
+      if (Array.isArray(args.otherApp)) args.otherApp.length = 0;
+      if (otherApps.length > 4) {
+        throw new TestingBotError(
+          `Too many --other-app entries (${otherApps.length}). Maximum is 4.`,
+        );
+      }
+
       const credentials = await Auth.getCredentials({
         apiKey: args.apiKey,
         apiSecret: args.apiSecret,
@@ -491,6 +516,7 @@ program
         configFile: args.config,
         groups: args.groups,
         metadata,
+        otherApps,
       });
       if (args.debug) {
         enableDebugLogging();
diff --git a/src/models/maestro_options.ts b/src/models/maestro_options.ts
@@ -42,13 +42,16 @@ export interface MaestroRunOptions {
   version?: string;
 }
 
+export const MAX_OTHER_APPS = 4;
+
 export default class MaestroOptions {
   private static isIpaFile(app?: string): boolean {
     return app?.toLowerCase().endsWith('.ipa') ?? false;
   }
 
   private _app: string;
   private _flows: string[];
+  private _otherApps: string[];
   private _device?: string;
   private _includeTags?: string[];
   private _excludeTags?: string[];
@@ -116,10 +119,17 @@ export default class MaestroOptions {
       groups?: string[];
       googlePlayStore?: boolean;
       metadata?: RunMetadata;
+      otherApps?: string[];
     },
   ) {
     this._app = app;
     this._flows = flows ? (Array.isArray(flows) ? flows : [flows]) : [];
+    this._otherApps = options?.otherApps ?? [];
+    if (this._otherApps.length > MAX_OTHER_APPS) {
+      throw new Error(
+        `Too many other apps (${this._otherApps.length}). Maximum is ${MAX_OTHER_APPS}.`,
+      );
+    }
     this._device = device;
     this._includeTags = options?.includeTags;
     this._excludeTags = options?.excludeTags;
@@ -166,6 +176,10 @@ export default class MaestroOptions {
     return this._flows;
   }
 
+  public get otherApps(): string[] {
+    return this._otherApps;
+  }
+
   public get device(): string | undefined {
     return this._device;
   }
diff --git a/src/providers/maestro.ts b/src/providers/maestro.ts
@@ -99,6 +99,7 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
   private updateServer: string | null = null;
   private updateKey: string | null = null;
   private socketFallbackWarned = false;
+  private otherAppUrls: string[] = [];
 
   private flowAnimationFrame = 0;
   private flowAnimationTimer: NodeJS.Timeout | null = null;
@@ -141,6 +142,23 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
       );
     }
 
+    // Validate other-apps count and extensions
+    const otherApps = this.options.otherApps;
+    if (otherApps.length > 4) {
+      throw new TestingBotError(
+        `Too many other apps (${otherApps.length}). Maximum is 4.`,
+      );
+    }
+    for (const otherAppPath of otherApps) {
+      const otherExt = path.extname(otherAppPath).toLowerCase();
+      if (!Maestro.SUPPORTED_APP_EXTENSIONS.includes(otherExt)) {
+        throw new TestingBotError(
+          `Unsupported other-app file format: ${otherExt || '(no extension)'} for ${otherAppPath}. ` +
+            `Supported formats: ${Maestro.SUPPORTED_APP_EXTENSIONS.join(', ')}`,
+        );
+      }
+    }
+
     // Build list of all file checks to run in parallel
     const fileChecks: Promise<void>[] = [
       fs.promises.access(this.options.app, fs.constants.R_OK).catch(() => {
@@ -150,6 +168,16 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
       }),
     ];
 
+    for (const otherAppPath of otherApps) {
+      fileChecks.push(
+        fs.promises.access(otherAppPath, fs.constants.R_OK).catch(() => {
+          throw new TestingBotError(
+            `Provided other-app path does not exist ${otherAppPath}`,
+          );
+        }),
+      );
+    }
+
     if (this.options.configFile) {
       fileChecks.push(
         fs.promises
@@ -221,6 +249,8 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
       // Process flows to show actual zip structure
       const flowResult = await this.collectFlows();
 
+      const otherApps = this.options.otherApps;
+
       this.printDryRunSummary({
         provider: 'Maestro',
         apiUrl: this.URL,
@@ -230,6 +260,11 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
             filePath: this.options.app,
             endpoint: `${this.URL}/app`,
           },
+          ...otherApps.map((p, i) => ({
+            label: `Other App ${i + 1}`,
+            filePath: p,
+            endpoint: `${this.URL}/other-apps`,
+          })),
           {
             label: 'Flows',
             filePath: this.options.flows.join(', '),
@@ -243,6 +278,11 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
             shardSplit: this.options.shardSplit,
           }),
           ...(metadata && { metadata }),
+          ...(otherApps.length > 0 && {
+            otherApps: otherApps.map(
+              (_, i) => `<tb://appkey-other-app-${i + 1}>`,
+            ),
+          }),
         },
       });
 
@@ -279,6 +319,11 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
       setTitle('maestro · uploading app');
       await this.uploadApp();
 
+      if (this.options.otherApps.length > 0) {
+        setTitle('maestro · uploading other apps');
+        await this.uploadOtherApps();
+      }
+
       if (!this.options.quiet) {
         logger.info('Uploading Maestro Flows');
       }
@@ -422,6 +467,48 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
     }
   }
 
+  private async uploadOtherApps(): Promise<void> {
+    const others = this.options.otherApps;
+    if (!others || others.length === 0) return;
+
+    if (!this.options.quiet) {
+      logger.info(`Uploading ${others.length} other app(s)`);
+    }
+
+    for (let i = 0; i < others.length; i++) {
+      const appPath = others[i];
+      const ext = path.extname(appPath).toLowerCase();
+      const contentType =
+        ext === '.apk'
+          ? 'application/vnd.android.package-archive'
+          : ext === '.ipa'
+            ? 'application/octet-stream'
+            : ext === '.zip' || ext === '.app'
+              ? 'application/zip'
+              : 'application/octet-stream';
+
+      if (!this.options.quiet) {
+        logger.info(`  [${i + 1}/${others.length}] ${path.basename(appPath)}`);
+      }
+
+      const result = await this.upload.upload({
+        filePath: appPath,
+        url: `${this.URL}/other-apps`,
+        credentials: this.credentials,
+        contentType,
+        showProgress: !this.options.quiet,
+        validateZipFormat: ext === '.zip' || ext === '.app',
+      });
+
+      if (!result.app_url) {
+        throw new TestingBotError(
+          `Other-app upload returned no app_url for ${appPath}`,
+        );
+      }
+      this.otherAppUrls.push(result.app_url);
+    }
+  }
+
   /**
    * Zip a .app bundle directory into a temporary zip file
    */
@@ -1583,6 +1670,9 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
             shardSplit: this.options.shardSplit,
           }),
           ...(metadata && { metadata }),
+          ...(this.otherAppUrls.length > 0 && {
+            otherApps: this.otherAppUrls,
+          }),
         },
         {
           headers: {
@@ -2696,11 +2786,7 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
           if (flow.report) {
             const flowReportPath = path.join(flowDir, 'report.xml');
             try {
-              await fs.promises.writeFile(
-                flowReportPath,
-                flow.report,
-                'utf-8',
-              );
+              await fs.promises.writeFile(flowReportPath, flow.report, 'utf-8');
               if (!this.options.quiet) {
                 logger.info(`    Saved ${flowDirName}/report.xml`);
               }
diff --git a/src/upload.ts b/src/upload.ts
@@ -27,6 +27,7 @@ export interface UploadOptions {
 
 export interface UploadResult {
   id: number;
+  app_url?: string;
 }
 
 export default class Upload {
@@ -134,7 +135,12 @@ export default class Upload {
             );
           }
         }
-        return { id: result.id };
+        return {
+          id: result.id,
+          ...(typeof result.app_url === 'string'
+            ? { app_url: result.app_url }
+            : {}),
+        };
       } else {
         if (showProgress) {
           if (interactive) {
diff --git a/tests/cli.test.ts b/tests/cli.test.ts
@@ -401,6 +401,68 @@ describe('TestingBotCTL CLI', () => {
     expect(opts.device).toBeUndefined();
   });
 
+  test('maestro command should accept repeated --other-app flags', async () => {
+    mockGetCredentials.mockResolvedValue({ apiKey: 'test-api-key' });
+
+    await program.parseAsync([
+      'node',
+      'cli',
+      'maestro',
+      '--app',
+      'app.apk',
+      '--other-app',
+      'helper.apk',
+      '--other-app',
+      'mock.apk',
+      './flows',
+    ]);
+
+    expect(mockMaestroRun).toHaveBeenCalledTimes(1);
+    const opts = lastConstructorOptions<{ otherApps: string[] }>(Maestro);
+    expect(opts.otherApps).toEqual(['helper.apk', 'mock.apk']);
+  });
+
+  test('maestro command should default otherApps to an empty array', async () => {
+    mockGetCredentials.mockResolvedValue({ apiKey: 'test-api-key' });
+
+    await program.parseAsync(['node', 'cli', 'maestro', 'app.apk', './flows']);
+
+    expect(mockMaestroRun).toHaveBeenCalledTimes(1);
+    const opts = lastConstructorOptions<{ otherApps: string[] }>(Maestro);
+    expect(opts.otherApps).toEqual([]);
+  });
+
+  test('maestro command should reject more than 4 --other-app entries', async () => {
+    mockGetCredentials.mockResolvedValue({ apiKey: 'test-api-key' });
+
+    await program.parseAsync([
+      'node',
+      'cli',
+      'maestro',
+      'app.apk',
+      './flows',
+      '--other-app',
+      'a.apk',
+      '--other-app',
+      'b.apk',
+      '--other-app',
+      'c.apk',
+      '--other-app',
+      'd.apk',
+      '--other-app',
+      'e.apk',
+    ]);
+
+    expect(mockMaestroRun).not.toHaveBeenCalled();
+    expect(process.exitCode).toBe(1);
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'Too many --other-app entries (5). Maximum is 4.',
+      ),
+    );
+    process.exitCode = 0;
+  });
+
   test('maestro command should accept --real-device flag', async () => {
     mockGetCredentials.mockResolvedValue({ apiKey: 'test-api-key' });
 
diff --git a/tests/models/maestro_options.test.ts b/tests/models/maestro_options.test.ts
diff --git a/tests/providers/maestro.test.ts b/tests/providers/maestro.test.ts

Original file line number	Diff line number	Diff line change
`@@ -27,6 +27,7 @@ export interface UploadOptions {`
`27`	`27`
`28`	`28`	`export interface UploadResult {`
`29`	`29`	`id: number;`
	`30`	`+ app_url?: string;`
`30`	`31`	`}`
`31`	`32`
`32`	`33`	`export default class Upload {`
`@@ -134,7 +135,12 @@ export default class Upload {`
`134`	`135`	`);`
`135`	`136`	`}`
`136`	`137`	`}`
`137`		`- return { id: result.id };`
	`138`	`+ return {`
	`139`	`+ id: result.id,`
	`140`	`+ ...(typeof result.app_url === 'string'`
	`141`	`+ ? { app_url: result.app_url }`
	`142`	`+ : {}),`
	`143`	`+ };`
`138`	`144`	`} else {`
`139`	`145`	`if (showProgress) {`
`140`	`146`	`if (interactive) {`