isoAutomate Ruby SDK

The Sovereign Browser Infrastructure & Orchestration Platform

Add this line to your application's Gemfile:

gem 'isoautomate'

And then execute:

bundle install

Or install it yourself as:

gem install isoautomate

The SDK requires a connection to a Redis instance to communicate with the browser engine. You can configure this either via an environment file (.env) or directly in your Ruby code.

Method A: Environment Variables (.env) Create a .env file in your project root. This is the recommended way to keep credentials out of your source code.

# Individual Fields
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=yourpassword
REDIS_DB=0
REDIS_SSL=false

# OR Single Redis URL (overrides individual fields if present)
# REDIS_URL=rediss://:password@host:port/0

Method B: Direct Initialization

You can pass connection details directly when creating the Client instance.

require 'isoautomate'

client = Isoautomate::Client.new(
  redis_host: "localhost",
  redis_port: 6379,
  redis_password: "yourpassword",
  redis_db: 0,
  redis_ssl: true
)

# Or using a URL string
# client = Isoautomate::Client.new(redis_url: "rediss://:password@host:port/0")

Browser sessions are managed through the Isoautomate::Client. To ensure that browser resources are cleaned up properly on the server, we highly recommend using a begin...ensure block.

Using ensure guarantees that the browser is released back to the fleet, even if your script crashes or an error occurs.

require 'isoautomate'

client = Isoautomate::Client.new

begin
  # 1. Acquire the browser instance
  # Returns a hash with session details
  session = client.acquire(browser_type: "chrome_profiled", video: true)
  puts "Connected to Worker: #{session['worker']}"
  
  # 2. Perform Actions
  client.open_url("[https://example.com](https://example.com)")
  client.assert_text("Example Domain")

  # Video URL is available via accessor or session hash
  puts "Session video: #{client.video_url}"

ensure
  # 3. CRITICAL: Always release resources
  client.release
end

The acquire method is used to claim a browser from your remote fleet. It supports several parameters to customize your environment.

Persistence allows you to resume sessions so you don't have to log in to websites repeatedly.

• Managed Profile (profile: true): The SDK manages a persistent ID for you locally in a .iso_profiles folder.
• Custom Profile (profile: "user_123"): You provide a specific string. Useful for managing specific accounts.

# Example: Using a named profile for a specific social media account
client.acquire(profile: "twitter_marketing_account")

Once you have acquired a browser, you can control it using the following methods.

Note: These require a _profiled browser engine (e.g., chrome_profiled).

All assertions take an optional screenshot: true (default). If the assertion fails, a screenshot is saved locally to screenshots/failures/.

This project is licensed under the MIT License.