Browser Action Library

A JavaScript library for automating browser interactions for testing and simulation purposes. This library provides a simple API for performing actions like clicking, typing, scrolling, and more in a web browser or Chrome extension context.

Features

• 🚀 Action API: Simple API for browser actions like clicking, typing, scrolling, etc.
• 🧩 Chrome Extension Support: Built-in support for Chrome extension development
• 💪 TypeScript Support: Full TypeScript definitions for improved development experience
• 🔄 Action Composition: Combine simple actions into complex sequences
• 🐛 Error Handling: Robust error handling with descriptive error messages
• ⏱️ Configurable Timeouts: Control how long to wait for actions to complete

Installation

npm install simulator-action
# or
yarn add simulator-action

Quick Start

Chrome Extension Usage

Content Script Setup

// In content.ts
import { initContentScriptApi } from 'simulator-action';

// Initialize content script API to handle actions from background/popup
initContentScriptApi();

Background or Popup Script

// In background.ts or popup.tsx
import { initBackgroundApi, ActionType } from 'simulator-action';

// Initialize the background API
const browserActions = initBackgroundApi();

// Execute an action with content script check
try {
  const result = await browserActions.executeActionWithContentScriptCheck({
    actionType: ActionType.Click,
    elementId: 'button-id',
    instruction: 'Click the button',
  });

  console.log('Action successful:', result);
} catch (error) {
  console.error('Action failed:', error);
}

Direct API Usage

import { sendAction, ActionType } from 'simulator-action';

// Click on an element
try {
  const result = await sendAction({
    actionType: ActionType.Click,
    elementId: 'submit-button',
    elementBBox: { x: 100, y: 100, width: 200, height: 50 }, // optional
    instruction: 'Click the submit button',
  });

  console.log('Click successful:', result);
} catch (error) {
  console.error('Click failed:', error);
}

// Type text into an input
try {
  const result = await sendAction({
    actionType: ActionType.Type,
    elementId: 'search-input',
    argument: 'search query',
    instruction: 'Enter search terms',
  });

  console.log('Text input successful:', result);
} catch (error) {
  console.error('Text input failed:', error);
}

Multi-Step Workflows

import { initBackgroundApi, ActionType } from 'simulator-action';

// Initialize the API
const browserActions = initBackgroundApi();

// Login example
async function loginToWebsite() {
  try {
    // Type username
    await browserActions.executeAction({
      actionType: ActionType.Type,
      elementId: 'username-field',
      argument: 'testuser',
      instruction: 'Enter username',
    });

    // Type password
    await browserActions.executeAction({
      actionType: ActionType.Type,
      elementId: 'password-field',
      argument: 'password123',
      instruction: 'Enter password',
    });

    // Click login button
    await browserActions.executeAction({
      actionType: ActionType.Click,
      elementId: 'login-button',
      instruction: 'Click the login button',
    });

    console.log('Login sequence completed');
  } catch (error) {
    console.error('Login sequence failed:', error);
  }
}

Examples

The repository includes several examples:

1. TestPage: A simple web application used for testing browser actions
2. TestPlugin: A Chrome extension that demonstrates how to use the library in an extension context

To run the examples:

# Start the test page
cd example/TestPage
npm install
npm run dev

# Build and load the test plugin in Chrome
cd example/TestPlugin
npm install
npm run dev

Documentation

• Getting Started: Learn the basics of using the library
• API Reference: Detailed information about all functions and types
• Usage Guide: Common usage patterns and examples

Action Parameters

The SendActionParams interface accepts the following parameters:

| Parameter | Type | Required | Description | | ----------- | ---------------- | -------- | ------------------------------------------------------- | | actionType | ActionType | Yes | The type of action to perform | | elementId | string | number | No | The identifier of the element to act upon | | elementBBox | ElementBBox | No | The bounding box of the element (x, y, width, height) | | argument | string | No | Additional argument for the action (e.g., text to type) | | instruction | string | No | Description of the action being performed | | tabId | number | No | ID of the target tab (defaults to active tab) | | timeout | number | No | Timeout in milliseconds (default: 30000) |

Supported Actions

The library supports various action types through the ActionType enum:

• Click: Click on elements
• Type: Type text into input fields
• Hover: Hover over elements
• RightClick: Right-click on elements
• PressEnter: Press the Enter key
• ScrollDown/ScrollUp: Scroll the page
• SelectDropdownOption: Select options from dropdown menus
• Wait: Wait for specified time periods
• And more...

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.