browser-commander 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.6.0
+
+### Minor Changes
+
+- 7d83530: Document extensibility escape hatch: `commander.page` and `launchBrowser()` return values expose the raw underlying Playwright/Puppeteer page object as an official mechanism for accessing engine-specific APIs not yet supported by browser-commander (e.g. `page.pdf()`, `page.emulateMedia()`, `page.keyboard`, `page.on('dialog', ...)`). Adds tests verifying `commander.page` is the exact raw page object.
+
+## 0.5.4
+
+### Patch Changes
+
+- e9043cc: Fix normalizeSelector to validate input type and reject arrays
+
+  When `normalizeSelector` receives an invalid type (array, number, or non-text-selector object), it now returns `null` with a warning instead of returning the invalid value unchanged.
+
+  This prevents downstream `querySelectorAll` errors with invalid selector syntax (like trailing commas when arrays are accidentally passed).
+
+  Fixes #23
+
 ## 0.5.3
 
 ### Patch Changes

package/README.md

@@ -318,6 +318,67 @@ action: async (ctx) => {
 };
 ```
 
+## Extensibility / Escape Hatch
+
+`browser-commander` cannot anticipate every browser API. When you need an API that is not yet supported, you can access the raw underlying engine objects directly as an **official extensibility escape hatch**.
+
+### Using `commander.page` for engine-specific APIs
+
+`makeBrowserCommander` exposes `commander.page` — this is the **raw Playwright or Puppeteer page object**, not a wrapper. Use it directly for APIs browser-commander doesn't yet support:
+
+```javascript
+const { browser, page } = await launchBrowser({ engine: 'playwright' });
+const commander = makeBrowserCommander({ page });
+
+// Access engine-specific API via commander.page
+// Example: PDF generation (issue #35)
+const pdfBuffer = await commander.page.pdf({
+  format: 'A4',
+  printBackground: true,
+  margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' },
+});
+
+// Example: Color scheme emulation (issue #36)
+await commander.page.emulateMedia({ colorScheme: 'dark' });
+
+// Example: Keyboard interactions (issue #37)
+await commander.page.keyboard.press('Escape');
+
+// Example: Dialog handling (issue #38)
+commander.page.on('dialog', async (dialog) => {
+  await dialog.dismiss();
+});
+```
+
+### Using `launchBrowser` raw return values
+
+`launchBrowser()` returns the raw `{ browser, page }` objects from the underlying engine. You can use these directly:
+
+```javascript
+const { browser, page } = await launchBrowser({ engine: 'playwright' });
+
+// Use raw page directly for engine-specific APIs
+await page.pdf({ format: 'A4' });
+
+// Or create a commander for the unified API
+const commander = makeBrowserCommander({ page });
+```
+
+### No more `_page` hacks
+
+If you previously used `page._page || page` to access the raw page, replace it with `commander.page`:
+
+```javascript
+// BEFORE (fragile hack):
+const rawPage = page._page || page;
+await rawPage.pdf({ format: 'A4' });
+
+// AFTER (official API):
+await commander.page.pdf({ format: 'A4' });
+```
+
+This is the **official extensibility mechanism** while awaiting browser-commander to add first-class support for these APIs. Please [report missing APIs](https://github.com/link-foundation/browser-commander/issues) so they can be added.
+
 ## Debugging
 
 Enable verbose mode for detailed logs:

package/package.json

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

package/src/elements/selectors.js

@@ -162,6 +162,25 @@ export async function normalizeSelector(options = {}) {
     throw new Error('selector is required in options');
   }
 
+  // DEFENSIVE: Validate selector type - must be string or Puppeteer text selector object
+  // Arrays and other invalid types should be rejected to prevent downstream querySelectorAll errors
+  if (Array.isArray(selector)) {
+    console.warn(
+      `normalizeSelector received invalid selector type: array. Expected string or text selector object.`
+    );
+    return null;
+  }
+
+  if (
+    typeof selector !== 'string' &&
+    (typeof selector !== 'object' || !selector._isPuppeteerTextSelector)
+  ) {
+    console.warn(
+      `normalizeSelector received invalid selector type: ${typeof selector}. Expected string or text selector object.`
+    );
+    return null;
+  }
+
   // Handle Playwright text selectors (strings containing :has-text or :text-is)
   // These are valid for Playwright's locator API but NOT for document.querySelectorAll
   if (
@@ -267,6 +286,8 @@ export async function normalizeSelector(options = {}) {
     }
   }
 
+  // This line should be unreachable after validation, but kept as a safeguard
+  // istanbul ignore next
   return selector;
 }
 

package/tests/unit/elements/selectors.test.js

@@ -207,11 +207,41 @@ describe('selectors', () => {
       assert.strictEqual(result, 'button');
     });
 
-    it('should return non-text-selector object unchanged', async () => {
+    it('should return null for invalid object selector', async () => {
       const page = createMockPlaywrightPage();
       const obj = { someKey: 'value' };
       const result = await normalizeSelector({ page, selector: obj });
-      assert.strictEqual(result, obj);
+      assert.strictEqual(result, null);
+    });
+
+    it('should return null for array selector', async () => {
+      const page = createMockPlaywrightPage();
+      const arr = ['[data-qa="test"]', []];
+      const result = await normalizeSelector({ page, selector: arr });
+      assert.strictEqual(result, null);
+    });
+
+    it('should return null for number selector', async () => {
+      const page = createMockPlaywrightPage();
+      const result = await normalizeSelector({ page, selector: 123 });
+      assert.strictEqual(result, null);
+    });
+
+    it('should accept valid Puppeteer text selector object', async () => {
+      const page = createMockPuppeteerPage();
+      page.evaluate = async () => '[data-qa="test"]';
+      const textSelector = {
+        _isPuppeteerTextSelector: true,
+        baseSelector: 'button',
+        text: 'Click me',
+        exact: false,
+      };
+      const result = await normalizeSelector({
+        page,
+        engine: 'puppeteer',
+        selector: textSelector,
+      });
+      assert.strictEqual(result, '[data-qa="test"]');
     });
   });
 

package/tests/unit/factory.test.js

@@ -170,5 +170,62 @@ describe('factory', () => {
       // Should not throw
       await commander.destroy();
     });
+
+    // Extensibility escape hatch tests (issue #39)
+    it('should expose the raw page object as commander.page (extensibility escape hatch)', () => {
+      const page = createMockPlaywrightPage();
+      page.locator = (sel) => ({
+        count: async () => 1,
+        waitFor: async () => {},
+      });
+      page.context = () => ({});
+
+      const commander = makeBrowserCommander({ page });
+
+      // commander.page must be the exact same object as the raw page passed in
+      // This is the official extensibility escape hatch for APIs not yet in browser-commander
+      assert.strictEqual(
+        commander.page,
+        page,
+        'commander.page must be the raw engine page (not a wrapper)'
+      );
+    });
+
+    it('should allow using commander.page to call engine-specific APIs not in browser-commander', () => {
+      const page = createMockPlaywrightPage();
+      page.locator = (sel) => ({
+        count: async () => 1,
+        waitFor: async () => {},
+      });
+      page.context = () => ({});
+
+      // Add a custom method to simulate engine-specific API (e.g. page.pdf(), page.emulateMedia())
+      page.customEngineMethod = () => 'engine-specific-result';
+
+      const commander = makeBrowserCommander({ page });
+
+      // Users can call engine-specific APIs via commander.page without needing _page hacks
+      const result = commander.page.customEngineMethod();
+      assert.strictEqual(
+        result,
+        'engine-specific-result',
+        'commander.page should allow calling engine-specific APIs'
+      );
+    });
+
+    it('should expose raw page with Puppeteer page too (extensibility escape hatch)', () => {
+      const page = createMockPuppeteerPage();
+      delete page.locator;
+      delete page.context;
+      page.$eval = async () => {};
+
+      const commander = makeBrowserCommander({ page });
+
+      assert.strictEqual(
+        commander.page,
+        page,
+        'commander.page must be the raw Puppeteer page (not a wrapper)'
+      );
+    });
   });
 });