chromate-rb 0.0.1.pre → 0.0.2.pre

data/docs/browser.md

@@ -1,163 +1,220 @@
-# Browser
+## `Chromate::Browser` Class
 
-The `Chromate::Browser` class is the main interface for interacting with the Chrome browser using the Chromate gem. It provides methods for navigating, interacting with elements, taking screenshots, and more.
+The `Chromate::Browser` class is responsible for controlling a browser instance using the Chrome DevTools Protocol (CDP). It provides methods for navigation, screenshots, and DOM interactions, as well as handling browser lifecycle (start and stop).
 
-## Initialization
-
-To create a new instance of the `Browser` class, you can pass in various options:
+### Initialization
 
 ```ruby
-browser = Chromate::Browser.new(
-  headless: true,
-  native_control: true,
-  user_data_dir: '/path/to/user/data',
-  record: false
-)
+browser = Chromate::Browser.new(options = {})
 ```
 
-### Options
+- **Parameters:**
+  - `options` (Hash, optional): Configuration options for the browser instance.
+    - `:chrome_path` (String): Path to the Chrome executable.
+    - `:user_data_dir` (String): Directory for storing user data (default: a temporary directory).
+    - `:headless` (Boolean): Run the browser in headless mode.
+    - `:xfvb` (Boolean): Use Xvfb for headless mode on Linux.
+    - `:native_control` (Boolean): Enable native control for enhanced undetection.
+    - `:record` (Boolean): Enable video recording of the browser session.
 
-- `headless`: Run Chrome in headless mode (default: true).
-- `native_control`: Use native mouse control (default: false).
-- `user_data_dir`: Directory to store user data (default: a temporary directory).
-- `record`: Record the browser session (default: false).
-- `xfvb`: Use xvfb for headless mode (default: false).
+### Public Methods
 
-## Methods
+#### `#start`
 
-### 
+Starts the browser process and initializes the CDP client.
 
-start
+- **Example:**
+  ```ruby
+  browser.start
+  ```
 
+#### `#stop`
 
+Stops the browser process, including any associated Xvfb or video recording processes.
 
-Starts the Chrome browser with the specified options.
+- **Example:**
+  ```ruby
+  browser.stop
+  ```
 
-```ruby
-browser.start
-```
+#### `#native_control?`
 
-### 
+Checks if native control is enabled for the browser instance.
 
-stop
+- **Returns:**
+  - `Boolean`: `true` if native control is enabled, `false` otherwise.
 
+- **Example:**
+  ```ruby
+  puts "Native control enabled" if browser.native_control?
+  ```
 
+### Navigation Methods (from `Actions::Navigate`)
 
-Stops the Chrome browser and any associated processes.
+#### `#navigate_to(url)`
 
-```ruby
-browser.stop
-```
+Navigates the browser to the specified URL.
 
-### `navigate_to(url)`
+- **Parameters:**
+  - `url` (String): The URL to navigate to.
 
-Navigates to the specified URL and waits for the page to load.
+- **Example:**
+  ```ruby
+  browser.navigate_to('https://example.com')
+  ```
 
-```ruby
-browser.navigate_to('http://example.com')
-```
+#### `#wait_for_page_load`
 
-### `find_element(selector)`
+Waits until the page has fully loaded, including the `DOMContentLoaded` event, `load` event, and `frameStoppedLoading` event.
 
-Finds an element on the page using the specified CSS selector.
+- **Example:**
+  ```ruby
+  browser.wait_for_page_load
+  ```
 
-```ruby
-element = browser.find_element('#some-element')
-```
+#### `#refresh`
 
-### `click_element(selector)`
+Reloads the current page.
 
-Clicks on an element specified by the CSS selector.
+- **Example:**
+  ```ruby
+  browser.refresh
+  ```
 
-```ruby
-browser.click_element('#some-element')
-```
+#### `#go_back`
 
-### `hover_element(selector)`
+Navigates back to the previous page in the browser history.
 
-Hovers over an element specified by the CSS selector.
+- **Example:**
+  ```ruby
+  browser.go_back
+  ```
 
-```ruby
-browser.hover_element('#some-element')
-```
+### Screenshot Methods (from `Actions::Screenshot`)
 
-### `type_text(selector, text)`
+#### `#screenshot(file_path, options = {})`
 
-Types text into an element specified by the CSS selector.
+Takes a screenshot of the current page and saves it to the specified file.
 
-```ruby
-browser.type_text('#input-field', 'Hello, world!')
-```
+- **Parameters:**
+  - `file_path` (String, optional): The file path to save the screenshot.
+  - `options` (Hash, optional): Additional options for the screenshot.
+  - - `full_page` (Boolean, optional): Take a full page screenshot
 
-### `screenshot_to_file(file_path, options = {})`
+It will call `#xvfb_screenshot` private method if `xvfb` mode is `true`
 
-Takes a screenshot of the current page and saves it to the specified file path.
+- **Example:**
+  ```ruby
+  browser.screenshot('screenshot.png')
+  ```
 
-```ruby
-browser.screenshot_to_file('screenshot.png')
-```
+### DOM Methods (from `Actions::Dom`)
 
-### 
+#### `#find_element(selector)`
 
-native_control?
+Finds a single element on the page using the specified CSS selector.
 
+- **Parameters:**
+  - `selector` (String): The CSS selector to locate the element.
 
+- **Returns:**
+  - `Chromate::Element`: The found element.
 
-Returns whether native control is enabled.
+- **Example:**
+  ```ruby
+  element = browser.find_element('#my-element')
+  puts element.text
+  ```
 
-```ruby
-puts browser.native_control? # => true or false
-```
+#### `#click_element(selector)`
 
-## Example Usage
+Finds an element by selector and clicks it.
 
-```ruby
-require 'chromate'
+- **Parameters:**
+  - `selector` (String): The CSS selector of the element to click.
 
-browser = Chromate::Browser.new(headless: true, native_control: true)
-browser.start
+- **Example:**
+  ```ruby
+  browser.click_element('#submit-button')
+  ```
 
-browser.navigate_to('http://example.com')
-browser.find_element('#some-element').click
-browser.screenshot_to_file('screenshot.png')
+#### `#hover_element(selector)`
 
-browser.stop
-```
-
-## Private Methods
+Finds an element by selector and hovers over it.
 
-### 
+- **Parameters:**
+  - `selector` (String): The CSS selector of the element to hover.
 
-start_video_recording
+- **Example:**
+  ```ruby
+  browser.hover_element('#hover-target')
+  ```
 
+#### `#type_text(selector, text)`
 
+Finds an element by selector and types the specified text into it.
 
-Starts recording the browser session using `ffmpeg`.
+- **Parameters:**
+  - `selector` (String): The CSS selector of the element.
+  - `text` (String): The text to type into the element.
 
-### 
+- **Example:**
+  ```ruby
+  browser.type_text('#input-field', 'Hello, Chromate!')
+  ```
 
-build_args
+#### `#select_option(selector, option)`
 
+Selects an option from a dropdown element.
 
+- **Parameters:**
+  - `selector` (String): The CSS selector of the dropdown element.
+  - `option` (String): The value of the option to select.
 
-Builds the arguments for starting the Chrome process.
+- **Example:**
+  ```ruby
+  browser.select_option('#dropdown', 'option2')
+  ```
 
-### 
+#### `#evaluate_script(script)`
 
-stop_and_exit
+Executes the specified JavaScript expression on the page.
 
+- **Parameters:**
+  - `script` (String): The JavaScript code to evaluate.
 
+- **Returns:**
+  - The result of the JavaScript evaluation.
 
-Stops the browser and exits the process.
+- **Example:**
+  ```ruby
+  result = browser.evaluate_script('document.title')
+  puts "Page title: #{result}"
+  ```
 
-### 
+### Exception Handling
 
-config
+- The browser handles `INT` and `TERM` signals gracefully by stopping the browser process and exiting safely.
+- The `stop_and_exit` method is used to ensure proper shutdown.
 
+### Example Usage
 
+```ruby
+require 'chromate'
 
-Returns the Chromate configuration.
+options = {
+  chrome_path: '/usr/bin/google-chrome',
+  headless: true,
+  native_control: true,
+  record: true
+}
 
-## Conclusion
+browser = Chromate::Browser.new(options)
 
-The `Chromate::Browser` class provides a powerful interface for automating interactions with the Chrome browser. With support for headless mode, native mouse control, and more, it is a versatile tool for creating undetectable bots with human-like behavior.
+browser.start
+browser.navigate_to('https://example.com')
+browser.screenshot('example.png')
+element = browser.find_element('#main-header')
+puts element.text
+browser.stop
+```

data/docs/element.md

@@ -0,0 +1,289 @@
+# 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.
+
+### 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}"
+  ```
+
+#### `#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 }
+  ```
+
+### Exceptions
+
+- `NotFoundError`: Raised when an element cannot be found with the given selector.
+- `InvalidSelectorError`: Raised when the selector cannot resolve to a valid element.

data/lib/bot_browser/downloader.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module BotBrowser
+  class Downloader
+    class << self
+      def download(version = nil)
+        version ||= versions.keys.first
+        version       = version.to_sym
+        platform      = :mac
+        arch          = :arm64
+        binary_path   = download_file(versions[version][platform][arch][:binary], "/tmp/botbrowser_#{version}_#{platform}_#{arch}.dmg")
+        profile_path  = download_file(versions[version][platform][arch][:profile], "/tmp/botbrowser_#{version}_#{platform}_#{arch}.json")
+
+        [binary_path, profile_path]
+      end
+
+      def download_file(url, path)
+        Chromate::CLogger.log("Downloading #{url} to #{path}")
+        `curl -L #{url} >> #{path}`
+
+        path
+      end
+
+      def versions
+        {
+          v130: {
+            mac: {
+              arm64: {
+                binary: 'https://github.com/MiddleSchoolStudent/BotBrowser/releases/download/v130/botbrowser_130.0.6723.92_mac_arm64.dmg',
+                profile: 'https://raw.githubusercontent.com/MiddleSchoolStudent/BotBrowser/refs/heads/main/profiles/v130/chrome130-macarm.enc'
+              }
+            },
+            linux: {
+              x64: {
+                binary: 'https://github.com/MiddleSchoolStudent/BotBrowser/releases/download/v130/botbrowser_130.0.6723.117_amd64.deb',
+                # no specifi linux profile for moment
+                profile: 'https://raw.githubusercontent.com/MiddleSchoolStudent/BotBrowser/refs/heads/main/profiles/v130/chrome130-macarm.enc'
+              }
+            },
+            windows: {
+              x64: {
+                binary: 'https://github.com/MiddleSchoolStudent/BotBrowser/releases/download/v130/botbrowser_130.0.6723.117_win_x86_64.7z',
+                # no specific windows profile for moment
+                profile: 'https://raw.githubusercontent.com/MiddleSchoolStudent/BotBrowser/refs/heads/main/profiles/v130/chrome130-macarm.enc'
+              }
+            }
+          }
+        }
+      end
+    end
+  end
+end