browser-commander 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.4.0
+
+### Minor Changes
+
+- 5af2479: Add support for custom Chrome args in launchBrowser
+
+  Adds a new `args` option to the `launchBrowser` function that allows passing custom Chrome arguments to append to the default `CHROME_ARGS`. This is useful for headless server environments (Docker, CI/CD) that require additional flags like `--no-sandbox`, `--disable-setuid-sandbox`, or `--disable-dev-shm-usage`.
+
+  Usage example:
+
+  ```javascript
+  import { launchBrowser } from 'browser-commander';
+
+  const { browser, page } = await launchBrowser({
+    engine: 'puppeteer',
+    headless: true,
+    args: ['--no-sandbox', '--disable-setuid-sandbox'],
+  });
+  ```
+
+  Fixes #11
+
+## 0.3.0
+
+### Minor Changes
+
+- 03e9ccb: Add isTimeoutError function for detecting timeout errors
+
+  Adds a new `isTimeoutError` function exported from the library that helps detect timeout errors from selector waiting operations. This function is complementary to `isNavigationError` and allows automation loops to handle timeout errors gracefully without crashing.
+
+  Usage example:
+
+  ```javascript
+  import { isTimeoutError } from 'browser-commander';
+
+  try {
+    await page.waitForSelector('.button');
+  } catch (error) {
+    if (isTimeoutError(error)) {
+      console.log('Timeout occurred, continuing with next item...');
+    }
+  }
+  ```
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -191,6 +191,21 @@ commander.pageTrigger({
 
 ## API Reference
 
+### launchBrowser(options)
+
+```javascript
+const { browser, page } = await launchBrowser({
+  engine: 'playwright', // 'playwright' or 'puppeteer'
+  headless: false, // Run in headless mode
+  userDataDir: '~/.hh-apply/playwright-data', // Browser profile directory
+  slowMo: 150, // Slow down operations (ms)
+  verbose: false, // Enable debug logging
+  args: ['--no-sandbox', '--disable-setuid-sandbox'], // Custom Chrome args to append
+});
+```
+
+The `args` option allows passing custom Chrome arguments, which is useful for headless server environments (Docker, CI/CD) that require flags like `--no-sandbox`.
+
 ### makeBrowserCommander(options)
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",

package/src/browser/launcher.js

@@ -11,6 +11,7 @@ import { disableTranslateInPreferences } from '../core/preferences.js';
  * @param {boolean} options.headless - Run in headless mode (default: false)
  * @param {number} options.slowMo - Slow down operations by ms (default: 150 for Playwright, 0 for Puppeteer)
  * @param {boolean} options.verbose - Enable verbose logging (default: false)
+ * @param {string[]} options.args - Custom Chrome arguments to append to the default CHROME_ARGS
  * @returns {Promise<Object>} - Object with browser and page
  */
 export async function launchBrowser(options = {}) {
@@ -20,8 +21,12 @@ export async function launchBrowser(options = {}) {
     headless = false,
     slowMo = engine === 'playwright' ? 150 : 0,
     verbose = false,
+    args = [],
   } = options;
 
+  // Combine default CHROME_ARGS with custom args
+  const chromeArgs = [...CHROME_ARGS, ...args];
+
   if (!['playwright', 'puppeteer'].includes(engine)) {
     throw new Error(
       `Invalid engine: ${engine}. Expected 'playwright' or 'puppeteer'`
@@ -50,7 +55,7 @@ export async function launchBrowser(options = {}) {
       slowMo,
       chromiumSandbox: true,
       viewport: null,
-      args: CHROME_ARGS,
+      args: chromeArgs,
       ignoreDefaultArgs: ['--enable-automation'],
     });
     page = browser.pages()[0];
@@ -59,7 +64,7 @@ export async function launchBrowser(options = {}) {
     browser = await puppeteer.default.launch({
       headless,
       defaultViewport: null,
-      args: ['--start-maximized', ...CHROME_ARGS],
+      args: ['--start-maximized', ...chromeArgs],
       userDataDir,
     });
     const pages = await browser.pages();

package/src/core/navigation-safety.js

@@ -158,3 +158,32 @@ export function withNavigationSafety(fn, options = {}) {
     }
   };
 }
+
+/**
+ * Check if an error is a timeout error from selector waiting
+ * These errors should be treated as non-fatal in automation loops
+ * @param {Error} error - The error to check
+ * @returns {boolean} - True if this is a timeout error
+ */
+export function isTimeoutError(error) {
+  if (!error) {
+    return false;
+  }
+
+  // Check error name first (most reliable)
+  if (error.name === 'TimeoutError') {
+    return true;
+  }
+
+  // Check error message patterns (case-insensitive)
+  const message = (error.message || '').toLowerCase();
+  const timeoutErrorPatterns = [
+    'waiting for selector',
+    'timeout',
+    'timeouterror',
+    'timeout exceeded',
+    'timed out',
+  ];
+
+  return timeoutErrorPatterns.some((pattern) => message.includes(pattern));
+}

package/src/exports.js

@@ -10,6 +10,7 @@ export { disableTranslateInPreferences } from './core/preferences.js';
 export { detectEngine } from './core/engine-detection.js';
 export {
   isNavigationError,
+  isTimeoutError,
   safeOperation,
   makeNavigationSafe,
   withNavigationSafety,

package/tests/unit/browser/launcher.test.js

@@ -0,0 +1,126 @@
+import { describe, it, mock, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+
+describe('launcher', () => {
+  describe('launchBrowser args option', () => {
+    let originalEnv;
+    let mockChromium;
+    let mockPuppeteer;
+    let launchBrowser;
+    let capturedPlaywrightArgs;
+    let capturedPuppeteerArgs;
+
+    beforeEach(async () => {
+      // Save original environment
+      originalEnv = { ...process.env };
+
+      // Reset captured args
+      capturedPlaywrightArgs = null;
+      capturedPuppeteerArgs = null;
+
+      // Create mock browser context for Playwright
+      const mockBrowserContext = {
+        pages: () => [
+          {
+            bringToFront: async () => {},
+          },
+        ],
+        close: async () => {},
+      };
+
+      // Create mock browser for Puppeteer
+      const mockBrowser = {
+        pages: async () => [
+          {
+            bringToFront: async () => {},
+          },
+        ],
+        close: async () => {},
+      };
+
+      // Mock Playwright's chromium
+      mockChromium = {
+        launchPersistentContext: async (userDataDir, options) => {
+          capturedPlaywrightArgs = options.args;
+          return mockBrowserContext;
+        },
+      };
+
+      // Mock Puppeteer
+      mockPuppeteer = {
+        default: {
+          launch: async (options) => {
+            capturedPuppeteerArgs = options.args;
+            return mockBrowser;
+          },
+        },
+      };
+
+      // Use mock.module to mock the dynamic imports
+      // Since we can't easily mock dynamic imports in Node.js test runner,
+      // we'll test the CHROME_ARGS constant usage directly
+    });
+
+    afterEach(() => {
+      // Restore original environment
+      process.env = originalEnv;
+    });
+
+    it('should export CHROME_ARGS constant', async () => {
+      const { CHROME_ARGS } = await import('../../../src/core/constants.js');
+      assert.ok(Array.isArray(CHROME_ARGS));
+      assert.ok(CHROME_ARGS.length > 0);
+    });
+
+    it('should include expected default Chrome args', async () => {
+      const { CHROME_ARGS } = await import('../../../src/core/constants.js');
+      assert.ok(CHROME_ARGS.includes('--disable-session-crashed-bubble'));
+      assert.ok(CHROME_ARGS.includes('--no-first-run'));
+      assert.ok(CHROME_ARGS.includes('--no-default-browser-check'));
+    });
+
+    it('launchBrowser function should accept args option', async () => {
+      // We can verify the function signature by checking that it
+      // destructures args from options without throwing
+      const { launchBrowser } =
+        await import('../../../src/browser/launcher.js');
+      assert.ok(typeof launchBrowser === 'function');
+
+      // The function should accept options object with args array
+      // We can't fully test the launch without actual browsers,
+      // but we can verify the function exists and is callable
+    });
+
+    it('launchBrowser should throw for invalid engine', async () => {
+      const { launchBrowser } =
+        await import('../../../src/browser/launcher.js');
+
+      await assert.rejects(
+        () => launchBrowser({ engine: 'invalid-engine' }),
+        (error) => {
+          assert.ok(error.message.includes('Invalid engine'));
+          assert.ok(error.message.includes('invalid-engine'));
+          return true;
+        }
+      );
+    });
+
+    it('launchBrowser should accept args in options', async () => {
+      const { launchBrowser } =
+        await import('../../../src/browser/launcher.js');
+
+      // Verify the function signature accepts args
+      // This test validates that the args parameter is correctly destructured
+      // by attempting to call with an invalid engine (which fails before browser launch)
+      // but proves args is accepted without error during options parsing
+      const customArgs = ['--no-sandbox', '--disable-setuid-sandbox'];
+
+      await assert.rejects(
+        () => launchBrowser({ engine: 'invalid', args: customArgs }),
+        /Invalid engine/
+      );
+
+      // If we got here, the args option was accepted without error
+    });
+  });
+});

package/tests/unit/core/navigation-safety.test.js

@@ -2,6 +2,7 @@ import { describe, it } from 'node:test';
 import assert from 'node:assert';
 import {
   isNavigationError,
+  isTimeoutError,
   safeOperation,
   makeNavigationSafe,
   withNavigationSafety,
@@ -67,6 +68,80 @@ describe('navigation-safety', () => {
     });
   });
 
+  describe('isTimeoutError', () => {
+    it('should return false for null', () => {
+      assert.strictEqual(isTimeoutError(null), false);
+    });
+
+    it('should return false for undefined', () => {
+      assert.strictEqual(isTimeoutError(undefined), false);
+    });
+
+    it('should return false for error without message or name', () => {
+      assert.strictEqual(isTimeoutError({}), false);
+    });
+
+    it('should return false for regular error', () => {
+      const error = new Error('Some regular error');
+      assert.strictEqual(isTimeoutError(error), false);
+    });
+
+    it('should return true for error with name "TimeoutError"', () => {
+      const error = new Error('Something failed');
+      error.name = 'TimeoutError';
+      assert.strictEqual(isTimeoutError(error), true);
+    });
+
+    it('should return true for "waiting for selector" error', () => {
+      const error = new Error('Waiting for selector ".button" timed out');
+      assert.strictEqual(isTimeoutError(error), true);
+    });
+
+    it('should return true for "timeout" error (case-insensitive)', () => {
+      const error = new Error('Timeout while waiting for element');
+      assert.strictEqual(isTimeoutError(error), true);
+    });
+
+    it('should return true for "timeout exceeded" error', () => {
+      const error = new Error('timeout exceeded');
+      assert.strictEqual(isTimeoutError(error), true);
+    });
+
+    it('should return true for "timed out" error', () => {
+      const error = new Error('Operation timed out after 30000ms');
+      assert.strictEqual(isTimeoutError(error), true);
+    });
+
+    it('should return true for Playwright locator timeout error', () => {
+      const error = new Error(
+        'locator.click: Timeout 30000ms exceeded. Waiting for selector "button.submit"'
+      );
+      assert.strictEqual(isTimeoutError(error), true);
+    });
+
+    it('should return true for Puppeteer waitForSelector timeout', () => {
+      const error = new Error(
+        'waiting for selector `#myElement` failed: timeout 30000ms exceeded'
+      );
+      assert.strictEqual(isTimeoutError(error), true);
+    });
+
+    it('should handle uppercase TIMEOUT in message', () => {
+      const error = new Error('TIMEOUT ERROR occurred');
+      assert.strictEqual(isTimeoutError(error), true);
+    });
+
+    it('should not match navigation errors as timeout errors', () => {
+      const error = new Error('Execution context was destroyed');
+      assert.strictEqual(isTimeoutError(error), false);
+    });
+
+    it('should not match frame detached errors as timeout errors', () => {
+      const error = new Error('frame was detached');
+      assert.strictEqual(isTimeoutError(error), false);
+    });
+  });
+
   describe('safeOperation', () => {
     it('should return success result on successful operation', async () => {
       const result = await safeOperation(async () => 'success');