fix: Add support for external BrowserStack Local tunnel handling and dynamic connection configurations

Author: Winify

src/providers/cloud/browserstack.provider.ts

@@ -1,14 +1,18 @@
 import { promisify } from 'node:util';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { Local as BrowserstackTunnel } from 'browserstack-local';
 import type { ConnectionConfig, SessionProvider, SessionResult } from '../types';
 
 export class BrowserStackProvider implements SessionProvider {
   name = 'browserstack';
 
-  getConnectionConfig(_options: Record<string, unknown>): ConnectionConfig {
+  getConnectionConfig(options: Record<string, unknown>): ConnectionConfig {
+    const platform = options.platform as string;
+    const hostname = platform === 'browser' ? 'hub.browserstack.com' : 'hub-cloud.browserstack.com';
     return {
       protocol: 'https',
-      hostname: 'hub.browserstack.com',
+      hostname,
       port: 443,
       path: '/wd/hub',
       user: process.env.BROWSERSTACK_USERNAME,
@@ -87,9 +91,10 @@ export class BrowserStackProvider implements SessionProvider {
     const tunnel = new BrowserstackTunnel();
     const start = promisify(tunnel.start.bind(tunnel));
     try {
-      await start({ key });
+      const logFile = join(tmpdir(), 'browserstack-local.log');
+      await start({ key, forceLocal: true, logFile });
     } catch (e: unknown) {
-      const msg = e instanceof Error ? e.message : String(e);
+      const msg = (e !== null && typeof e === 'object' ? (e as { message?: string }).message : undefined) ?? String(e);
       if (msg.includes('another browserstack local client is running') || msg.includes('server is listening on port')) {
         console.error('[BrowserStack] Tunnel already running — reusing existing tunnel');
         return null;

src/tools/session.tool.ts

@@ -54,7 +54,7 @@ export const startSessionToolDefinition: ToolDefinition = {
       port: z.number().optional(),
       path: z.string().optional(),
     }).optional().describe('Appium server connection (local provider only)'),
-    browserstackLocal: coerceBoolean.optional().default(false).describe('Enable BrowserStack Local tunnel for testing against local/internal URLs (BrowserStack only, default: false). When true, the tunnel is started automatically before the session and stopped when the session is closed.'),
+    browserstackLocal: z.union([coerceBoolean, z.literal('external')]).optional().default(false).describe('Enable BrowserStack Local tunnel routing (BrowserStack only, default: false). true = auto-start tunnel before session and stop on close. "external" = tunnel already running externally, set local: true in capabilities only.'),
     navigationUrl: z.string().optional().describe('URL to navigate to after starting'),
     capabilities: z.record(z.string(), z.unknown()).optional().describe('Additional capabilities to merge'),
   },
@@ -87,7 +87,7 @@ type StartSessionArgs = {
   attach?: boolean;
   attachConfig?: { port?: number; host?: string };
   appiumConfig?: { host?: string; port?: number; path?: string };
-  browserstackLocal?: boolean;
+  browserstackLocal?: boolean | 'external';
   navigationUrl?: string;
   capabilities?: Record<string, unknown>;
 };
@@ -186,7 +186,7 @@ async function startBrowserSession(args: StartSessionArgs): Promise<CallToolResu
     capabilities: userCapabilities,
   });
 
-  const tunnelHandle = args.browserstackLocal
+  const tunnelHandle = args.browserstackLocal === true
     ? await provider.startTunnel?.(args as Record<string, unknown>)
     : undefined;
 
@@ -250,7 +250,7 @@ async function startMobileSession(args: StartSessionArgs): Promise<CallToolResul
   const serverConfig = provider.getConnectionConfig(args as Record<string, unknown>);
   const mergedCapabilities = provider.buildCapabilities(args as Record<string, unknown>);
 
-  const tunnelHandle = args.browserstackLocal
+  const tunnelHandle = args.browserstackLocal === true
     ? await provider.startTunnel?.(args as Record<string, unknown>)
     : undefined;
 

tests/providers/browserstack.provider.test.ts

@@ -1,4 +1,16 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+const { mockTunnel } = vi.hoisted(() => ({
+  mockTunnel: { start: vi.fn(), stop: vi.fn() },
+}));
+
+vi.mock('browserstack-local', () => ({
+  Local: class {
+    start = mockTunnel.start;
+    stop = mockTunnel.stop;
+  },
+}));
+
 import { BrowserStackProvider } from '../../src/providers/cloud/browserstack.provider';
 
 describe('BrowserStackProvider', () => {
@@ -9,14 +21,24 @@ describe('BrowserStackProvider', () => {
   });
 
   describe('getConnectionConfig', () => {
-    it('returns BrowserStack hub connection details', () => {
-      const config = provider.getConnectionConfig({});
+    it('returns hub.browserstack.com for browser platform', () => {
+      const config = provider.getConnectionConfig({ platform: 'browser' });
       expect(config.hostname).toBe('hub.browserstack.com');
       expect(config.protocol).toBe('https');
       expect(config.port).toBe(443);
       expect(config.path).toBe('/wd/hub');
     });
 
+    it('returns hub-cloud.browserstack.com for android platform', () => {
+      const config = provider.getConnectionConfig({ platform: 'android' });
+      expect(config.hostname).toBe('hub-cloud.browserstack.com');
+    });
+
+    it('returns hub-cloud.browserstack.com for ios platform', () => {
+      const config = provider.getConnectionConfig({ platform: 'ios' });
+      expect(config.hostname).toBe('hub-cloud.browserstack.com');
+    });
+
     it('reads credentials from environment variables', () => {
       vi.stubEnv('BROWSERSTACK_USERNAME', 'myuser');
       vi.stubEnv('BROWSERSTACK_ACCESS_KEY', 'mykey');
@@ -164,6 +186,17 @@ describe('BrowserStackProvider', () => {
       const bstack = caps['bstack:options'] as Record<string, unknown>;
       expect(bstack.local).toBe(true);
     });
+
+    it('sets local: true in bstack:options when browserstackLocal is "external"', () => {
+      const caps = provider.buildCapabilities({
+        platform: 'android',
+        deviceName: 'Pixel 7',
+        app: 'bs://abc',
+        browserstackLocal: 'external',
+      });
+      const bstack = caps['bstack:options'] as Record<string, unknown>;
+      expect(bstack.local).toBe(true);
+    });
   });
 
   describe('getSessionType', () => {
@@ -185,4 +218,69 @@ describe('BrowserStackProvider', () => {
       expect(provider.shouldAutoDetach({})).toBe(false);
     });
   });
+
+  describe('startTunnel', () => {
+    beforeEach(() => {
+      vi.stubEnv('BROWSERSTACK_ACCESS_KEY', 'testkey');
+      mockTunnel.start.mockReset();
+      mockTunnel.stop.mockReset();
+    });
+
+    it('returns the tunnel instance on successful start', async () => {
+      mockTunnel.start.mockImplementation((opts: unknown, cb: (err: unknown) => void) => cb(null));
+
+      const handle = await provider.startTunnel({});
+      expect(handle).toBeDefined();
+    });
+
+    it('passes logFile pointing to os.tmpdir() to avoid polluting cwd', async () => {
+      let capturedOpts: unknown;
+      mockTunnel.start.mockImplementation((opts: unknown, cb: (err: unknown) => void) => {
+        capturedOpts = opts;
+        cb(null);
+      });
+
+      await provider.startTunnel({});
+      const logFile = (capturedOpts as Record<string, unknown>).logFile as string;
+      expect(logFile).toBeDefined();
+      expect(logFile).toContain('browserstack-local');
+    });
+
+    it('passes forceLocal: true to tunnel start', async () => {
+      let capturedOpts: unknown;
+      mockTunnel.start.mockImplementation((opts: unknown, cb: (err: unknown) => void) => {
+        capturedOpts = opts;
+        cb(null);
+      });
+
+      await provider.startTunnel({});
+      expect((capturedOpts as Record<string, unknown>).forceLocal).toBe(true);
+    });
+
+    it('returns null when tunnel is already running (plain object error with message)', async () => {
+      mockTunnel.start.mockImplementation((opts: unknown, cb: (err: unknown) => void) =>
+        cb({ message: 'another browserstack local client is running' }),
+      );
+
+      const handle = await provider.startTunnel({});
+      expect(handle).toBeNull();
+    });
+
+    it('returns null when server is already listening (plain object error with message)', async () => {
+      mockTunnel.start.mockImplementation((opts: unknown, cb: (err: unknown) => void) =>
+        cb({ message: 'server is listening on port 45691' }),
+      );
+
+      const handle = await provider.startTunnel({});
+      expect(handle).toBeNull();
+    });
+
+    it('rethrows unrecognised errors', async () => {
+      mockTunnel.start.mockImplementation((opts: unknown, cb: (err: unknown) => void) =>
+        cb({ message: 'some other fatal error' }),
+      );
+
+      await expect(provider.startTunnel({})).rejects.toEqual({ message: 'some other fatal error' });
+    });
+  });
 });

tests/tools/start-session-browserstack.test.ts

@@ -88,7 +88,7 @@ describe('start_session with provider: browserstack', () => {
     });
 
     expect(mockRemote).toHaveBeenCalledWith(expect.objectContaining({
-      hostname: 'hub.browserstack.com',
+      hostname: 'hub-cloud.browserstack.com',
       user: 'testuser',
       key: 'testkey',
       capabilities: expect.objectContaining({
@@ -142,6 +142,20 @@ describe('start_session with browserstackLocal: true', () => {
     expect(mockRemote).not.toHaveBeenCalled();
   });
 
+  it('does NOT call BrowserstackTunnel when browserstackLocal is "external"', async () => {
+    await callTool({ provider: 'browserstack', platform: 'browser', browser: 'chrome', browserstackLocal: 'external' });
+
+    expect(BrowserstackTunnel).not.toHaveBeenCalled();
+  });
+
+  it('sets local: true in bstack:options when browserstackLocal is "external"', async () => {
+    await callTool({ provider: 'browserstack', platform: 'browser', browser: 'chrome', browserstackLocal: 'external' });
+
+    const [call] = mockRemote.mock.calls;
+    const bstackOpts = call[0].capabilities['bstack:options'];
+    expect(bstackOpts.local).toBe(true);
+  });
+
   it('creates a BrowserstackTunnel instance for mobile platform', async () => {
     await callTool({
       provider: 'browserstack',