Use localhost hostname for local browsers in proxy mode

When running tests in local browsers with native automation disabled, TestCafe previously attempted to resolve a network-accessible hostname. This process can be slow and may fail in environments with restricted or no network access.

This change optimizes this behavior by defaulting the hostname to 'localhost' when all browsers are local and a specific hostname has not been configured. This improves test startup time and enhances reliability for local-only test runs.

Author: Christopher Robinson

src/configuration/testcafe-configuration.ts

@@ -330,10 +330,12 @@ export default class TestCafeConfiguration extends Configuration {
         this.mergeOptions({ hostname });
     }
 
-    public async calculateHostname ({ nativeAutomation } = { nativeAutomation: false }): Promise<void> {
+    public async calculateHostname ({ nativeAutomation, allBrowsersLocal } = { nativeAutomation: false, allBrowsersLocal: false }): Promise<void> {
         await this.ensureHostname(async hostname => {
             if (nativeAutomation)
                 hostname = LOCALHOST_NAMES.LOCALHOST;
+            else if (!hostname && allBrowsersLocal)
+                hostname = LOCALHOST_NAMES.LOCALHOST;
             else
                 hostname = await getValidHostname(hostname);
 

src/runner/bootstrapper.ts

@@ -171,11 +171,16 @@ export default class Bootstrapper {
         };
     }
 
-    private async _setupProxy (): Promise<void> {
+    private async _setupProxy (browserInfo: BrowserInfoSource[]): Promise<void> {
         if (this.browserConnectionGateway.status === BrowserConnectionGatewayStatus.initialized)
             return;
 
-        await this.configuration.calculateHostname({ nativeAutomation: !this.configuration.getOption(OPTION_NAMES.disableNativeAutomation) });
+        const allBrowsersLocal = await this._isAllBrowsersLocal(browserInfo);
+
+        await this.configuration.calculateHostname({
+            nativeAutomation: !this.configuration.getOption(OPTION_NAMES.disableNativeAutomation),
+            allBrowsersLocal,
+        });
 
         this.browserConnectionGateway.initialize(this.configuration.startOptions);
     }
@@ -209,7 +214,7 @@ export default class Bootstrapper {
 
         this._validateUserProfileOptionInNativeAutomation(automated);
 
-        await this._setupProxy();
+        await this._setupProxy(browserInfo);
 
         let browserConnections = this._createAutomatedConnections(automated);
 
@@ -349,13 +354,17 @@ export default class Bootstrapper {
         return testedApp;
     }
 
-    private async _canUseParallelBootstrapping (browserInfo: BrowserInfoSource[]): Promise<boolean> {
+    private async _isAllBrowsersLocal (browserInfo: BrowserInfoSource[]): Promise<boolean> {
         const isLocalPromises = browserInfo.map(browser => browser.provider.isLocalBrowser(void 0, Bootstrapper._getBrowserName(browser)));
         const isLocalBrowsers = await Promise.all(isLocalPromises);
 
         return isLocalBrowsers.every(result => result);
     }
 
+    private async _canUseParallelBootstrapping (browserInfo: BrowserInfoSource[]): Promise<boolean> {
+        return this._isAllBrowsersLocal(browserInfo);
+    }
+
     private async _bootstrapSequence (browserInfo: BrowserInfoSource[], id: string): Promise<BasicRuntimeResources> {
         const tests      = await this._getTests(id);
         const testedApp  = await this._startTestedApp();

test/server/bootstrapper-test.js

@@ -189,5 +189,39 @@ describe('Bootstrapper', () => {
                                         'the "userProfile" suffix from the following browser aliases: "chrome, edge".');
             }
         });
+
+        it('Should use localhost hostname strategy for local browsers in proxy mode', async () => {
+            let calculateHostnameOptions = null;
+
+            const originalGetOption         = bootstrapper.configuration.getOption;
+            const originalCalculateHostname = bootstrapper.configuration.calculateHostname;
+
+            try {
+                bootstrapper.configuration.getOption = optionName => {
+                    if (optionName === 'disableNativeAutomation')
+                        return true;
+
+                    return originalGetOption(optionName);
+                };
+
+                bootstrapper.configuration.calculateHostname = options => {
+                    calculateHostnameOptions = options;
+                };
+
+                await bootstrapper._setupProxy([{
+                    browserName: 'firefox',
+                    provider:    createBrowserProviderMock({ local: true }),
+                }]);
+
+                expect(calculateHostnameOptions).eql({
+                    nativeAutomation: false,
+                    allBrowsersLocal: true,
+                });
+            }
+            finally {
+                bootstrapper.configuration.getOption         = originalGetOption;
+                bootstrapper.configuration.calculateHostname = originalCalculateHostname;
+            }
+        });
     });
 });

test/server/configuration-test.js

@@ -505,6 +505,20 @@ describe('TestCafeConfiguration', function () {
 
                     expect(configuration.getOption('hostname')).eql('123.456.789');
                 });
+
+                it('Native automation is disabled/all browsers are local/hostname is unset', async () => {
+                    await configuration.init();
+                    await configuration.calculateHostname({ nativeAutomation: false, allBrowsersLocal: true });
+
+                    expect(configuration.getOption('hostname')).eql('localhost');
+                });
+
+                it('Native automation is disabled/all browsers are local/hostname is set', async () => {
+                    await configuration.init({ hostname: '123.456.789' });
+                    await configuration.calculateHostname({ nativeAutomation: false, allBrowsersLocal: true });
+
+                    expect(configuration.getOption('hostname')).eql('123.456.789');
+                });
             });
         });