chromate-rb 0.0.1.pre → 0.0.3.pre

data/docs/element.md

@@ -0,0 +1,365 @@
+# Element
+
+The `Chromate::Element` class represents a DOM element in a browser controlled via the Chrome DevTools Protocol (CDP). It provides methods to interact with the element, including manipulating its attributes, getting its text content, and simulating user actions.
+
+### Initialization
+
+```ruby
+element = Chromate::Element.new(selector, client, node_id: nil, object_id: nil, root_id: nil)
+```
+
+- **Parameters:**
+  - `selector` (String): The CSS selector used to locate the element.
+  - `client` (Chromate::Client): An instance of the CDP client.
+  - `node_id` (Integer, optional): The node ID of the element.
+  - `object_id` (String, optional): The object ID of the element.
+  - `root_id` (Integer, optional): The root node ID of the document.
+
+### Attributes
+
+#### `#selector`
+
+Returns the CSS selector used to locate the element.
+
+- **Returns:**
+  - `String`: The CSS selector.
+
+#### `#client`
+
+Returns the CDP client instance used to communicate with the browser.
+
+- **Returns:**
+  - `Chromate::Client`: The CDP client instance.
+
+#### `#root_id`
+
+Returns the root node ID of the document.
+
+- **Returns:**
+  - `Integer`: The root node ID.
+
+#### `#object_id`
+
+Returns the object ID of the element.
+
+- **Returns:**
+  - `String`: The object ID.
+
+#### `#node_id`
+
+Returns the node ID of the element.
+
+- **Returns:**
+  - `Integer`: The node ID.
+
+### Public Methods
+
+#### `#mouse`
+
+Returns the mouse controller for interacting with the element.
+
+- **Example:**
+  ```ruby
+  element.mouse.click
+  ```
+
+#### `#keyboard`
+
+Returns the keyboard controller for interacting with the element.
+
+- **Example:**
+  ```ruby
+  element.keyboard.type('Hello World')
+  ```
+
+#### `#inspect`
+
+Returns a string representation of the element.
+
+- **Example:**
+  ```ruby
+  puts element.inspect
+  ```
+
+#### `#text`
+
+Retrieves the inner text of the element.
+
+- **Example:**
+  ```ruby
+  text = element.text
+  puts "Element text: #{text}"
+  ```
+
+#### `#html`
+
+Retrieves the outer HTML of the element.
+
+- **Example:**
+  ```ruby
+  html = element.html
+  puts "Element HTML: #{html}"
+  ```
+
+#### `#attributes`
+
+Returns a hash of the element's attributes.
+
+- **Example:**
+  ```ruby
+  attributes = element.attributes
+  puts "Element attributes: #{attributes}"
+  ```
+
+#### `#tag_name`
+
+Gets the HTML tag name of the element in lowercase.
+
+- **Returns:**
+  - `String`: The HTML tag name.
+
+- **Example:**
+  ```ruby
+  tag = element.tag_name
+  puts "Tag name: #{tag}"
+  ```
+
+#### `#set_attribute(name, value)`
+
+Sets an attribute on the element.
+
+- **Parameters:**
+  - `name` (String): The name of the attribute.
+  - `value` (String): The value to set for the attribute.
+
+- **Example:**
+  ```ruby
+  element.set_attribute('class', 'highlighted')
+  ```
+
+#### `#bounding_box`
+
+Returns a hash with the dimensions of the element's bounding box.
+
+- **Example:**
+  ```ruby
+  box = element.bounding_box
+  puts "Bounding box: #{box}"
+  ```
+
+#### `#x`
+
+Returns the x-coordinate of the element's position.
+
+- **Example:**
+  ```ruby
+  x_position = element.x
+  puts "X Position: #{x_position}"
+  ```
+
+#### `#y`
+
+Returns the y-coordinate of the element's position.
+
+- **Example:**
+  ```ruby
+  y_position = element.y
+  puts "Y Position: #{y_position}"
+  ```
+
+#### `#width`
+
+Returns the width of the element.
+
+- **Example:**
+  ```ruby
+  width = element.width
+  puts "Element width: #{width}"
+  ```
+
+#### `#height`
+
+Returns the height of the element.
+
+- **Example:**
+  ```ruby
+  height = element.height
+  puts "Element height: #{height}"
+  ```
+
+#### `#focus`
+
+Sets focus on the element.
+
+- **Example:**
+  ```ruby
+  element.focus
+  ```
+
+#### `#click`
+
+Simulates a click on the element.
+
+- **Example:**
+  ```ruby
+  element.click
+  ```
+
+#### `#hover`
+
+Simulates a hover action over the element.
+
+- **Example:**
+  ```ruby
+  element.hover
+  ```
+
+#### `#type(text)`
+
+Types the specified text into the element.
+
+- **Parameters:**
+  - `text` (String): The text to type.
+
+- **Example:**
+  ```ruby
+  element.type('Hello, Chromate!')
+  ```
+
+#### `#press_enter`
+
+Simulates pressing the Enter key and submits the form if the element is inside one.
+
+- **Example:**
+  ```ruby
+  element.press_enter
+  ```
+
+#### `#drop_to(element)`
+
+Drag current element and drop to target
+
+- **Example:**
+  ```ruby
+  element.drop_to(target_element)
+  ```
+
+#### `#find_element(selector)`
+
+Finds a single child element matching the given selector.
+
+- **Parameters:**
+  - `selector` (String): The CSS selector to find the element.
+
+- **Returns:**
+  - `Chromate::Element`: The found element.
+
+- **Example:**
+  ```ruby
+  child_element = element.find_element('.child')
+  puts child_element.text
+  ```
+
+#### `#find_elements(selector, max: 0)`
+
+Finds all child elements matching the given selector.
+
+- **Parameters:**
+  - `selector` (String): The CSS selector to find elements.
+  - `max` (Integer, optional): The maximum number of elements to find (0 for no limit).
+
+- **Returns:**
+  - `Array<Chromate::Element>`: An array of found elements.
+
+- **Example:**
+  ```ruby
+  elements = element.find_elements('.item')
+  elements.each { |el| puts el.text }
+  ```
+
+#### `#shadow_root_id`
+
+Returns the shadow root ID of the element if it has one.
+
+- **Example:**
+  ```ruby
+  shadow_id = element.shadow_root_id
+  puts "Shadow root ID: #{shadow_id}"
+  ```
+
+#### `#shadow_root?`
+
+Checks if the element has a shadow root.
+
+- **Returns:**
+  - `Boolean`: `true` if the element has a shadow root, otherwise `false`.
+
+- **Example:**
+  ```ruby
+  if element.shadow_root?
+    puts "Element has a shadow root."
+  end
+  ```
+
+#### `#find_shadow_child(selector)`
+
+Finds a single child element inside the shadow root using the given selector.
+
+- **Parameters:**
+  - `selector` (String): The CSS selector to find the shadow child element.
+
+- **Returns:**
+  - `Chromate::Element` or `nil`: The found element or `nil` if not found.
+
+- **Example:**
+  ```ruby
+  shadow_child = element.find_shadow_child('.shadow-element')
+  puts shadow_child.text if shadow_child
+  ```
+
+#### `#find_shadow_children(selector)`
+
+Finds all child elements inside the shadow root using the given selector.
+
+- **Parameters:**
+  - `selector` (String): The CSS selector to find shadow child elements.
+
+- **Returns:**
+  - `Array<Chromate::Element>`: An array of found elements.
+
+- **Example:**
+  ```ruby
+  shadow_elements = element.find_shadow_children('.shadow-item')
+  shadow_elements.each { |el| puts el.text }
+  ```
+
+#### `#value`
+
+Gets the value of the element.
+
+- **Returns:**
+  - `String`: The element's value.
+
+- **Example:**
+  ```ruby
+  value = element.value
+  puts "Element value: #{value}"
+  ```
+
+### Exceptions
+
+- `NotFoundError`: Raised when an element cannot be found with the given selector.
+- `InvalidSelectorError`: Raised when the selector cannot resolve to a valid element.
+
+## Specialized Elements
+
+Chromate provides specialized element classes for specific HTML elements that have unique behaviors and methods. When using `find_element`, Chromate automatically returns the appropriate specialized element based on the element type.
+
+### Available Specialized Elements
+
+- [Select Element](elements/select.md): For `<select>` elements
+- [Option Element](elements/option.md): For `<option>` elements within select elements
+- [Radio Element](elements/radio.md): For radio button inputs (`<input type="radio">`)
+- [Checkbox Element](elements/checkbox.md): For checkbox inputs (`<input type="checkbox">`)
+
+Each specialized element inherits from the base `Element` class and adds specific methods for interacting with that type of element. See the individual documentation files for details on the methods available for each element type.

data/docs/elements/checkbox.md

@@ -0,0 +1,69 @@
+# Checkbox Element
+
+The `Chromate::Elements::Checkbox` class represents a checkbox input element in the browser. It extends the base `Element` class with specific functionality for checkboxes.
+
+### Initialization
+
+```ruby
+checkbox = Chromate::Elements::Checkbox.new(selector, client, **options)
+```
+
+- **Parameters:**
+  - `selector` (String): The CSS selector used to locate the checkbox.
+  - `client` (Chromate::Client): An instance of the CDP client.
+  - `options` (Hash): Additional options passed to the Element constructor.
+    - `object_id` (String): Optional. The object ID of a pre-searched element.
+    - `node_id` (Integer): Optional. The node ID of a pre-searched element.
+    - `root_id` (Integer): Optional. The root ID of a pre-searched element.
+
+### Public Methods
+
+#### `#checked?`
+
+Returns whether the checkbox is currently checked.
+
+- **Returns:**
+  - `Boolean`: `true` if the checkbox is checked, `false` otherwise.
+
+- **Example:**
+  ```ruby
+  if checkbox.checked?
+    puts "Checkbox is checked"
+  end
+  ```
+
+#### `#check`
+
+Checks the checkbox if it's not already checked.
+
+- **Returns:**
+  - `self`: Returns the checkbox element for method chaining.
+
+- **Example:**
+  ```ruby
+  checkbox.check
+  ```
+
+#### `#uncheck`
+
+Unchecks the checkbox if it's currently checked.
+
+- **Returns:**
+  - `self`: Returns the checkbox element for method chaining.
+
+- **Example:**
+  ```ruby
+  checkbox.uncheck
+  ```
+
+#### `#toggle`
+
+Toggles the checkbox state (checks if unchecked, unchecks if checked).
+
+- **Returns:**
+  - `self`: Returns the checkbox element for method chaining.
+
+- **Example:**
+  ```ruby
+  checkbox.toggle
+  ```

data/docs/elements/radio.md

@@ -0,0 +1,57 @@
+# Radio Element
+
+The `Chromate::Elements::Radio` class represents a radio button input element in the browser. It extends the base `Element` class with specific functionality for radio buttons.
+
+### Initialization
+
+```ruby
+radio = Chromate::Elements::Radio.new(selector, client, **options)
+```
+
+- **Parameters:**
+  - `selector` (String): The CSS selector used to locate the radio button.
+  - `client` (Chromate::Client): An instance of the CDP client.
+  - `options` (Hash): Additional options passed to the Element constructor.
+    - `object_id` (String): Optional. The object ID of a pre-searched element.
+    - `node_id` (Integer): Optional. The node ID of a pre-searched element.
+    - `root_id` (Integer): Optional. The root ID of a pre-searched element.
+
+### Public Methods
+
+#### `#checked?`
+
+Returns whether the radio button is currently checked.
+
+- **Returns:**
+  - `Boolean`: `true` if the radio button is checked, `false` otherwise.
+
+- **Example:**
+  ```ruby
+  if radio.checked?
+    puts "Radio button is checked"
+  end
+  ```
+
+#### `#check`
+
+Checks the radio button if it's not already checked.
+
+- **Returns:**
+  - `self`: Returns the radio element for method chaining.
+
+- **Example:**
+  ```ruby
+  radio.check
+  ```
+
+#### `#uncheck`
+
+Unchecks the radio button if it's currently checked.
+
+- **Returns:**
+  - `self`: Returns the radio element for method chaining.
+
+- **Example:**
+  ```ruby
+  radio.uncheck
+  ```

data/lib/bot_browser/downloader.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Special thanks to the BotBrowser project (https://github.com/MiddleSchoolStudent/BotBrowser)
+# for providing an amazing foundation for browser automation and making this work possible.
+
+require 'chromate/binary'
+
+module BotBrowser
+  class Downloader
+    class << self
+      def download(version = nil, profile = nil, platform = :mac)
+        version ||= versions.keys.first
+        profile ||= profiles[version].keys.first
+        version       = version.to_sym
+        binary_path   = download_file(versions[version][platform], "/tmp/botbrowser_#{version}_#{platform}.dmg")
+        profile_path  = download_file(profiles[version][profile], "/tmp/botbrowser_#{version}_#{platform}.json")
+
+        [binary_path, profile_path]
+      end
+
+      def download_file(url, path)
+        Chromate::CLogger.log("Downloading #{url} to #{path}")
+        Chromate::Binary.run('curl', ['-L', url, '-o', path])
+
+        path
+      end
+
+      def versions
+        {
+          v132: {
+            mac: 'https://github.com/MiddleSchoolStudent/BotBrowser/releases/download/20250204/botbrowser_132.0.6834.84_mac_arm64.dmg',
+            linux: 'https://github.com/MiddleSchoolStudent/BotBrowser/releases/download/20250204/botbrowser_132.0.6834.84_amd64.deb',
+            windows: 'https://github.com/MiddleSchoolStudent/BotBrowser/releases/download/20250204/botbrowser_132.0.6834.84_win_x86_64.7z'
+          },
+          v130: {
+            mac: 'https://github.com/MiddleSchoolStudent/BotBrowser/releases/download/v130/botbrowser_130.0.6723.92_mac_arm64.dmg',
+            linux: 'https://github.com/MiddleSchoolStudent/BotBrowser/releases/download/v130/botbrowser_130.0.6723.117_amd64.deb',
+            windows: 'https://github.com/MiddleSchoolStudent/BotBrowser/releases/download/v130/botbrowser_130.0.6723.117_win_x86_64.7z'
+          }
+        }
+      end
+
+      def profiles
+        {
+          v128: {
+            mac: 'https://raw.githubusercontent.com/MiddleSchoolStudent/BotBrowser/refs/heads/main/profiles/v128/chrome128_mac_arm64.enc',
+            win: 'https://raw.githubusercontent.com/MiddleSchoolStudent/BotBrowser/refs/heads/main/profiles/v128/chrome128_win10_x86_64.enc'
+          },
+          v129: {
+            mac: 'https://raw.githubusercontent.com/MiddleSchoolStudent/BotBrowser/refs/heads/main/profiles/v129/chrome129_mac_arm64.enc'
+          },
+          v130: {
+            mac: 'https://raw.githubusercontent.com/MiddleSchoolStudent/BotBrowser/refs/heads/main/profiles/v130/chrome130_mac_arm64.enc',
+            iphone: 'https://raw.githubusercontent.com/MiddleSchoolStudent/BotBrowser/refs/heads/main/profiles/v130/chrome130_iphone.enc'
+          },
+          v132: {
+            mac: 'https://github.com/MiddleSchoolStudent/BotBrowser/blob/main/profiles/v132/chrome132_mac_arm64.enc',
+            win: 'https://github.com/MiddleSchoolStudent/BotBrowser/blob/main/profiles/v132/chrome132_win10_x86_64.enc'
+          }
+        }
+      end
+    end
+  end
+end

data/lib/bot_browser/installer.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'chromate/helpers'
+require 'chromate/c_logger'
+require 'bot_browser/downloader'
+
+module BotBrowser
+  class Installer
+    class NotInstalledError < StandardError; end
+    class << self
+      include Chromate::Helpers
+
+      def install(version = nil)
+        create_config_dir
+        binary_path, profile_path = Downloader.download(version)
+        bot_browser_path          = install_binary(binary_path)
+        bot_browser_profile_path  = install_profile(profile_path)
+
+        write_config(bot_browser_path, bot_browser_profile_path)
+      end
+
+      def config_dir
+        "#{Dir.home}/.botbrowser"
+      end
+
+      def installed?
+        File.exist?("#{config_dir}/config.yml")
+      end
+
+      def uninstall
+        raise NotInstalledError, 'BotBrowser is not installed' unless installed?
+
+        config = YAML.load_file("#{config_dir}/config.yml")
+        Chromate::CLogger.log("Uninstalling binary at #{config["bot_browser_path"]}")
+        FileUtils.rm_rf(config['bot_browser_path'])
+        Chromate::CLogger.log("Uninstalling profile at #{config["profile"]}")
+        FileUtils.rm_rf(config['profile'])
+        FileUtils.rm_rf(config_dir)
+        Chromate::CLogger.log('Uninstalled')
+      end
+
+      private
+
+      def install_binary(binary_path)
+        Chromate::CLogger.log("Installing binary from #{binary_path}")
+        return install_binary_mac(binary_path) if mac?
+        return install_binary_linux(binary_path) if linux?
+        return install_binary_windows(binary_path) if windows?
+
+        raise 'Unsupported platform'
+      end
+
+      def create_config_dir
+        Chromate::CLogger.log("Creating config directory at #{config_dir}")
+        FileUtils.mkdir_p(config_dir)
+      end
+
+      def install_profile(profile_path)
+        Chromate::CLogger.log("Installing profile from #{profile_path}")
+        `cp #{profile_path} #{config_dir}/`
+
+        "#{config_dir}/#{File.basename(profile_path)}"
+      end
+
+      def install_binary_mac(binary_path)
+        Chromate::Binary.run('hdiutil', ['attach', binary_path])
+        Chromate::Binary.run('cp', ['-r', '/Volumes/Chromium/Chromium.app', '/Applications/'])
+        Chromate::Binary.run('hdiutil', ['detach', '/Volumes/Chromium'])
+        Chromate::Binary.run('xattr', ['-rd', 'com.apple.quarantine', '/Applications/Chromium.app'])
+        Chromate::Binary.run('codesign', ['--force', '--deep', '--sign', '-', '/Applications/Chromium.app'], need_success: false)
+
+        '/Applications/Chromium.app/Contents/MacOS/Chromium'
+      end
+
+      def install_binary_linux(binary_path)
+        Chromate::Binary.run('sudo', ['dpkg', '-i', binary_path])
+        Chromate::Binary.run('sudo', ['apt-get', 'install', '-f'])
+
+        '/usr/bin/chromium'
+      end
+
+      def install_binary_windows(binary_path)
+        Chromate::Binary.run('7z', ['x', binary_path])
+
+        'chromium.exe'
+      end
+
+      def write_config(bot_browser_path, bot_browser_profile_path)
+        Chromate::CLogger.log("Writing config to #{config_dir}/config.yml")
+        File.write(File.expand_path("#{config_dir}/config.yml"), <<~YAML)
+          ---
+          bot_browser_path: #{bot_browser_path}
+          profile: #{bot_browser_profile_path}
+        YAML
+      end
+    end
+  end
+end

data/lib/bot_browser.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'chromate/c_logger'
+require 'bot_browser/installer'
+
+module BotBrowser
+  class << self
+    def install(version = nil)
+      Installer.install(version)
+    end
+
+    def uninstall
+      Installer.uninstall
+    end
+
+    def installed?
+      Installer.installed?
+    end
+
+    def load
+      yaml = YAML.load_file("#{Dir.home}/.botbrowser/config.yml")
+
+      Chromate.configure do |config|
+        ENV['CHROME_BIN'] = yaml['bot_browser_path']
+        config.args = [
+          "--bot-profile=#{yaml["profile"]}",
+          '--no-sandbox'
+        ]
+        config.startup_patch = false
+      end
+
+      Chromate::CLogger.log('BotBrowser loaded', level: :debug)
+    end
+  end
+end
+
+# Usage
+# require 'bot_browser'
+
+# BotBrowser.install
+# BotBrowser.load
+# browser = Chromate::Browser.new