chromate-rb 0.0.1.pre → 0.0.3.pre

data/docs/browser.md

@@ -1,163 +1,185 @@
-# 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')
-```
-
-### `click_element(selector)`
-
-Clicks on an element specified by the CSS selector.
+#### `#refresh`
 
-```ruby
-browser.click_element('#some-element')
-```
+Reloads the current page.
 
-### `hover_element(selector)`
+- **Example:**
+  ```ruby
+  browser.refresh
+  ```
 
-Hovers over an element specified by the CSS selector.
+#### `#go_back`
 
-```ruby
-browser.hover_element('#some-element')
-```
+Navigates back to the previous page in the browser history.
 
-### `type_text(selector, text)`
+- **Example:**
+  ```ruby
+  browser.go_back
+  ```
 
-Types text into an element specified by the CSS selector.
+### Screenshot Methods (from `Actions::Screenshot`)
 
-```ruby
-browser.type_text('#input-field', 'Hello, world!')
-```
+#### `#screenshot(file_path, options = {})`
 
-### `screenshot_to_file(file_path, options = {})`
+Takes a screenshot of the current page and saves it to the specified file.
 
-Takes a screenshot of the current page and saves it to the specified file path.
+- **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
 
-```ruby
-browser.screenshot_to_file('screenshot.png')
-```
+It will call `#xvfb_screenshot` private method if `xvfb` mode is `true`
 
-### 
+- **Example:**
+  ```ruby
+  browser.screenshot('screenshot.png')
+  ```
 
-native_control?
+### DOM Methods (from `Actions::Dom`)
 
+#### `#find_element(selector)`
 
+Finds a single element on the page using the specified CSS selector. Returns a specialized element class based on the element type:
 
-Returns whether native control is enabled.
+- **Parameters:**
+  - `selector` (String): The CSS selector to locate the element.
 
-```ruby
-puts browser.native_control? # => true or false
-```
+- **Returns:**
+  - `Chromate::Elements::Select`: For `<select>` elements
+  - `Chromate::Elements::Option`: For `<option>` elements
+  - `Chromate::Elements::Radio`: For radio button inputs (`<input type="radio">`)
+  - `Chromate::Elements::Checkbox`: For checkbox inputs (`<input type="checkbox">`)
+  - `Chromate::Element`: For all other element types
 
-## Example Usage
+Each specialized element type provides specific methods for interacting with that type of element. For example:
 
 ```ruby
-require 'chromate'
-
-browser = Chromate::Browser.new(headless: true, native_control: true)
-browser.start
+# Working with radio buttons
+radio = browser.find_element('input[type="radio"]')
+radio.check if !radio.checked?
 
-browser.navigate_to('http://example.com')
-browser.find_element('#some-element').click
-browser.screenshot_to_file('screenshot.png')
+# Working with checkboxes
+checkbox = browser.find_element('input[type="checkbox"]')
+checkbox.toggle
 
-browser.stop
+# Working with select elements
+select = browser.find_element('select#country')
+select.select_option('France')
 ```
 
-## Private Methods
-
-### 
-
-start_video_recording
-
-
-
-Starts recording the browser session using `ffmpeg`.
+See the [Element documentation](element.md) for more details about specialized elements.
 
-### 
+#### `#evaluate_script(script)`
 
-build_args
+Executes the specified JavaScript expression on the page.
 
+- **Parameters:**
+  - `script` (String): The JavaScript code to evaluate.
 
+- **Returns:**
+  - The result of the JavaScript evaluation.
 
-Builds the arguments for starting the Chrome process.
+- **Example:**
+  ```ruby
+  result = browser.evaluate_script('document.title')
+  puts "Page title: #{result}"
+  ```
 
-### 
+### Exception Handling
 
-stop_and_exit
-
-
-
-Stops the browser and exits the process.
-
-### 
-
-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/client.md

@@ -0,0 +1,126 @@
+# Client
+
+The `Chromate::Client` class is responsible for managing WebSocket connections to Chrome DevTools Protocol (CDP). It handles communication between the Chromate library and the Chrome browser, including message sending, receiving, and event handling.
+
+### Initialization
+
+```ruby
+client = Chromate::Client.new(browser)
+```
+
+- **Parameters:**
+  - `browser` (Chromate::Browser): The browser instance to connect to.
+
+### Public Methods
+
+#### `#start`
+
+Establishes the WebSocket connection to Chrome DevTools Protocol and sets up event handlers.
+
+- **Returns:**
+  - `self`: Returns the client instance for method chaining.
+
+- **Example:**
+  ```ruby
+  client.start
+  ```
+
+#### `#stop`
+
+Closes the WebSocket connection.
+
+- **Returns:**
+  - `self`: Returns the client instance for method chaining.
+
+- **Example:**
+  ```ruby
+  client.stop
+  ```
+
+#### `#send_message(method, params = {})`
+
+Sends a message to Chrome DevTools Protocol and waits for the response.
+
+- **Parameters:**
+  - `method` (String): The CDP method to call.
+  - `params` (Hash, optional): Parameters for the CDP method.
+
+- **Returns:**
+  - `Hash`: The response from Chrome DevTools Protocol.
+
+- **Example:**
+  ```ruby
+  result = client.send_message('DOM.getDocument')
+  ```
+
+#### `#reconnect`
+
+Reestablishes the WebSocket connection if it was lost.
+
+- **Returns:**
+  - `self`: Returns the client instance for method chaining.
+
+- **Example:**
+  ```ruby
+  client.reconnect
+  ```
+
+#### `#on_message`
+
+Subscribes to WebSocket messages. Allows different parts of the application to listen for CDP events.
+
+- **Parameters:**
+  - `&block` (Block): The block to execute when a message is received.
+
+- **Example:**
+  ```ruby
+  client.on_message do |message|
+    puts "Received message: #{message}"
+  end
+  ```
+
+### Class Methods
+
+#### `.listeners`
+
+Returns the array of registered message listeners.
+
+- **Returns:**
+  - `Array<Proc>`: The array of listener blocks.
+
+### Event Handling
+
+The client automatically handles several WebSocket events:
+
+- `:message`: Processes incoming CDP messages and notifies listeners
+- `:open`: Logs successful connection
+- `:error`: Logs WebSocket errors
+- `:close`: Logs connection closure
+
+### Error Handling
+
+The client includes automatic reconnection logic when message sending fails:
+
+- Attempts to reconnect to the WebSocket
+- Retries the failed message
+- Logs errors and debug information through `Chromate::CLogger`
+
+### Example Usage
+
+```ruby
+browser = Chromate::Browser.new
+client = Chromate::Client.new(browser)
+
+client.start
+
+# Send a CDP command
+result = client.send_message('DOM.getDocument')
+
+# Listen for specific events
+client.on_message do |msg|
+  puts msg if msg['method'] == 'DOM.documentUpdated'
+end
+
+# Clean up
+client.stop
+```