browser-commander 0.2.0

package/README.md

@@ -0,0 +1,320 @@
+# Browser Commander
+
+A universal browser automation library that supports both Playwright and Puppeteer with a unified API. The key focus is on **stoppable page triggers** - ensuring automation logic is properly mounted/unmounted during page navigation.
+
+## Installation
+
+```bash
+npm install browser-commander
+```
+
+You'll also need either Playwright or Puppeteer:
+
+```bash
+# With Playwright
+npm install playwright
+
+# Or with Puppeteer
+npm install puppeteer
+```
+
+## Core Concept: Page State Machine
+
+Browser Commander manages the browser as a state machine with two states:
+
+```
++------------------+                      +------------------+
+|                  |   navigation start   |                  |
+|  WORKING STATE   | -------------------> |  LOADING STATE   |
+|  (action runs)   |                      |  (wait only)     |
+|                  |   <-----------------  |                  |
++------------------+     page ready       +------------------+
+```
+
+**LOADING STATE**: Page is loading. Only waiting/tracking operations are allowed. No automation logic runs.
+
+**WORKING STATE**: Page is fully loaded (30 seconds of network idle). Page triggers can safely interact with DOM.
+
+## Quick Start
+
+```javascript
+import {
+  launchBrowser,
+  makeBrowserCommander,
+  makeUrlCondition,
+} from 'browser-commander';
+
+// 1. Launch browser
+const { browser, page } = await launchBrowser({ engine: 'playwright' });
+
+// 2. Create commander
+const commander = makeBrowserCommander({ page, verbose: true });
+
+// 3. Register page trigger with condition and action
+commander.pageTrigger({
+  name: 'example-trigger',
+  condition: makeUrlCondition('*example.com*'), // matches URLs containing 'example.com'
+  action: async (ctx) => {
+    // ctx.commander has all methods, but they throw ActionStoppedError if navigation happens
+    // ctx.checkStopped() - call in loops to check if should stop
+    // ctx.abortSignal - use with fetch() for cancellation
+    // ctx.onCleanup(fn) - register cleanup when action stops
+
+    console.log(`Processing: ${ctx.url}`);
+
+    // Safe iteration - stops if navigation detected
+    await ctx.forEach(['item1', 'item2'], async (item) => {
+      await ctx.commander.clickButton({ selector: `[data-id="${item}"]` });
+    });
+  },
+});
+
+// 4. Navigate - action auto-starts when page is ready
+await commander.goto({ url: 'https://example.com' });
+
+// 5. Cleanup
+await commander.destroy();
+await browser.close();
+```
+
+## URL Condition Helpers
+
+The `makeUrlCondition` helper makes it easy to create URL matching conditions:
+
+```javascript
+import {
+  makeUrlCondition,
+  allConditions,
+  anyCondition,
+  notCondition,
+} from 'browser-commander';
+
+// Exact URL match
+makeUrlCondition('https://example.com/page');
+
+// Contains substring (use * wildcards)
+makeUrlCondition('*checkout*'); // URL contains 'checkout'
+makeUrlCondition('*example.com*'); // URL contains 'example.com'
+
+// Starts with / ends with
+makeUrlCondition('/api/*'); // starts with '/api/'
+makeUrlCondition('*.json'); // ends with '.json'
+
+// Express-style route patterns
+makeUrlCondition('/vacancy/:id'); // matches /vacancy/123
+makeUrlCondition('https://hh.ru/vacancy/:vacancyId'); // matches specific domain + path
+makeUrlCondition('/user/:userId/profile'); // multiple segments
+
+// RegExp
+makeUrlCondition(/\/product\/\d+/);
+
+// Custom function (receives full context)
+makeUrlCondition((url, ctx) => {
+  const parsed = new URL(url);
+  return (
+    parsed.pathname.startsWith('/admin') && parsed.searchParams.has('edit')
+  );
+});
+
+// Combine conditions
+allConditions(
+  makeUrlCondition('*example.com*'),
+  makeUrlCondition('*/checkout*')
+); // Both must match
+
+anyCondition(makeUrlCondition('*/cart*'), makeUrlCondition('*/checkout*')); // Either matches
+
+notCondition(makeUrlCondition('*/admin*')); // Negation
+```
+
+## Page Trigger Lifecycle
+
+### The Guarantee
+
+When navigation is detected:
+
+1. **Action is signaled to stop** (AbortController.abort())
+2. **Wait for action to finish** (up to 10 seconds for graceful cleanup)
+3. **Only then start waiting for page load**
+
+This ensures:
+
+- No DOM operations on stale/loading pages
+- Actions can do proper cleanup (clear intervals, save state)
+- No race conditions between action and navigation
+
+## Action Context API
+
+When your action is called, it receives a context object with these properties:
+
+```javascript
+commander.pageTrigger({
+  name: 'my-trigger',
+  condition: makeUrlCondition('*/checkout*'),
+  action: async (ctx) => {
+    // Current URL
+    ctx.url; // 'https://example.com/checkout'
+
+    // Trigger name (for debugging)
+    ctx.triggerName; // 'my-trigger'
+
+    // Check if action should stop
+    ctx.isStopped(); // Returns true if navigation detected
+
+    // Throw ActionStoppedError if stopped (use in manual loops)
+    ctx.checkStopped();
+
+    // AbortSignal - use with fetch() or other cancellable APIs
+    ctx.abortSignal;
+
+    // Safe wait (throws if stopped during wait)
+    await ctx.wait(1000);
+
+    // Safe iteration (checks stopped between items)
+    await ctx.forEach(items, async (item) => {
+      await ctx.commander.clickButton({ selector: item.selector });
+    });
+
+    // Register cleanup (runs when action stops)
+    ctx.onCleanup(() => {
+      console.log('Cleaning up...');
+    });
+
+    // Commander with all methods wrapped to throw on stop
+    await ctx.commander.fillTextArea({ selector: 'input', text: 'hello' });
+
+    // Raw commander (use carefully - does not auto-throw)
+    ctx.rawCommander;
+  },
+});
+```
+
+## API Reference
+
+### makeBrowserCommander(options)
+
+```javascript
+const commander = makeBrowserCommander({
+  page, // Required: Playwright/Puppeteer page
+  verbose: false, // Enable debug logging
+  enableNetworkTracking: true, // Track HTTP requests
+  enableNavigationManager: true, // Enable navigation events
+});
+```
+
+### commander.pageTrigger(config)
+
+```javascript
+const unregister = commander.pageTrigger({
+  name: 'trigger-name',                    // For debugging
+  condition: (ctx) => boolean,             // When to run (receives {url, commander})
+  action: async (ctx) => void,             // What to do
+  priority: 0,                             // Higher runs first
+});
+```
+
+### commander.goto(options)
+
+```javascript
+await commander.goto({
+  url: 'https://example.com',
+  waitUntil: 'domcontentloaded', // Playwright/Puppeteer option
+  timeout: 60000,
+});
+```
+
+### commander.clickButton(options)
+
+```javascript
+await commander.clickButton({
+  selector: 'button.submit',
+  scrollIntoView: true,
+  waitForNavigation: true,
+});
+```
+
+### commander.fillTextArea(options)
+
+```javascript
+await commander.fillTextArea({
+  selector: 'textarea.message',
+  text: 'Hello world',
+  checkEmpty: true,
+});
+```
+
+### commander.destroy()
+
+```javascript
+await commander.destroy(); // Stop actions, cleanup
+```
+
+## Best Practices
+
+### 1. Use ctx.forEach for Loops
+
+```javascript
+// BAD: Won't stop on navigation
+for (const item of items) {
+  await ctx.commander.click({ selector: item });
+}
+
+// GOOD: Stops immediately on navigation
+await ctx.forEach(items, async (item) => {
+  await ctx.commander.click({ selector: item });
+});
+```
+
+### 2. Use ctx.checkStopped for Complex Logic
+
+```javascript
+action: async (ctx) => {
+  while (hasMorePages) {
+    ctx.checkStopped(); // Throws if navigation detected
+
+    await processPage(ctx);
+    hasMorePages = await ctx.commander.isVisible({ selector: '.next' });
+  }
+};
+```
+
+### 3. Register Cleanup for Resources
+
+```javascript
+action: async (ctx) => {
+  const intervalId = setInterval(updateStatus, 1000);
+
+  ctx.onCleanup(() => {
+    clearInterval(intervalId);
+    console.log('Interval cleared');
+  });
+
+  // ... rest of action
+};
+```
+
+### 4. Use ctx.abortSignal with Fetch
+
+```javascript
+action: async (ctx) => {
+  const response = await fetch(url, {
+    signal: ctx.abortSignal, // Cancels on navigation
+  });
+};
+```
+
+## Debugging
+
+Enable verbose mode for detailed logs:
+
+```javascript
+const commander = makeBrowserCommander({ page, verbose: true });
+```
+
+## Architecture
+
+See [src/ARCHITECTURE.md](src/ARCHITECTURE.md) for detailed architecture documentation.
+
+## License
+
+[UNLICENSE](LICENSE)

package/bunfig.toml

@@ -0,0 +1,3 @@
+# Bun configuration
+# Note: Bun doesn't support excluding test files directly in config
+# Use CLI flags or file naming patterns instead

package/deno.json

@@ -0,0 +1,7 @@
+{
+  "nodeModulesDir": "auto",
+  "test": {
+    "include": ["tests/"],
+    "exclude": ["examples/", "node_modules/"]
+  }
+}

package/eslint.config.js

@@ -0,0 +1,125 @@
+import js from '@eslint/js';
+import prettierConfig from 'eslint-config-prettier';
+import prettierPlugin from 'eslint-plugin-prettier';
+
+export default [
+  js.configs.recommended,
+  prettierConfig,
+  {
+    files: ['**/*.js', '**/*.mjs'],
+    plugins: {
+      prettier: prettierPlugin,
+    },
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: {
+        // Node.js globals
+        console: 'readonly',
+        process: 'readonly',
+        Buffer: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        // Node.js 18+ globals
+        fetch: 'readonly',
+        // Web/Node.js shared globals
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearInterval: 'readonly',
+        AbortController: 'readonly',
+        AbortSignal: 'readonly',
+        Event: 'readonly',
+        URL: 'readonly',
+        URLSearchParams: 'readonly',
+        // Testing globals
+        describe: 'readonly',
+        it: 'readonly',
+        test: 'readonly',
+        expect: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        beforeAll: 'readonly',
+        afterAll: 'readonly',
+        // Runtime-specific globals
+        Bun: 'readonly',
+        Deno: 'readonly',
+        globalThis: 'readonly',
+        // Browser globals (used in evaluate functions)
+        document: 'readonly',
+        window: 'readonly',
+      },
+    },
+    rules: {
+      // Prettier integration
+      'prettier/prettier': 'error',
+
+      // Code quality rules
+      // Note: Using 'warn' instead of 'error' for unused-vars since this codebase
+      // has intentionally unused parameters in abstract base classes and mocks
+      'no-unused-vars': [
+        'warn',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          destructuredArrayIgnorePattern: '^_',
+        },
+      ],
+      'no-console': 'off', // Allow console in this project
+      'no-debugger': 'error',
+
+      // Best practices
+      eqeqeq: ['error', 'always'],
+      curly: ['error', 'all'],
+      'no-var': 'error',
+      'prefer-const': 'error',
+      'prefer-arrow-callback': 'error',
+      'no-duplicate-imports': 'error',
+
+      // ES6+ features
+      'arrow-body-style': ['error', 'as-needed'],
+      'object-shorthand': ['error', 'always'],
+      'prefer-template': 'error',
+
+      // Async/await
+      'no-async-promise-executor': 'error',
+      'require-await': 'warn',
+
+      // Comments and documentation
+      'spaced-comment': ['error', 'always', { markers: ['/'] }],
+
+      // Complexity rules - reasonable thresholds for maintainability
+      complexity: ['warn', 15], // Cyclomatic complexity - allow more complex logic than strict 8
+      'max-depth': ['warn', 5], // Maximum nesting depth - slightly more lenient than strict 4
+      'max-lines-per-function': [
+        'warn',
+        {
+          max: 150, // More reasonable than strict 50 lines per function
+          skipBlankLines: true,
+          skipComments: true,
+        },
+      ],
+      'max-params': ['warn', 6], // Maximum function parameters - slightly more lenient than strict 5
+      'max-statements': ['warn', 60], // Maximum statements per function - reasonable limit for orchestration functions
+      'max-lines': ['error', 1500], // Maximum lines per file - counts all lines including blank lines and comments
+    },
+  },
+  {
+    // Test files have different requirements
+    files: ['tests/**/*.js', '**/*.test.js'],
+    rules: {
+      'require-await': 'off', // Async functions without await are common in tests
+      'no-unused-vars': 'off', // Mock functions often have unused parameters for API compatibility
+      'max-lines-per-function': 'off', // Tests can be long
+    },
+  },
+  {
+    ignores: [
+      'node_modules/**',
+      'coverage/**',
+      'dist/**',
+      '*.min.js',
+      '.eslintcache',
+    ],
+  },
+];

package/examples/react-test-app/index.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>React Test App - Browser Commander E2E Tests</title>
+    <style>
+      * {
+        box-sizing: border-box;
+      }
+      body {
+        font-family:
+          -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu,
+          sans-serif;
+        margin: 0;
+        padding: 20px;
+        background: #f5f5f5;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/examples/react-test-app/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "react-test-app",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.2.0",
+    "vite": "^5.0.0"
+  }
+}