bidi2pdf 0.1.12 → 0.1.14

data/lib/bidi2pdf/test_helpers/testcontainers/container_endpoint.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module TestHelpers
+    module Testcontainers
+      # Builds a URL for reaching a container's published port from the test
+      # process, using the container's own host/port resolution.
+      class ContainerEndpoint
+        def initialize(container, port)
+          @container = container
+          @port = port
+        end
+
+        def url(scheme: "http", path: "")
+          "#{scheme}://#{@container.accessible_host}:#{@container.mapped_port(@port)}/#{path}"
+        end
+
+        # Address reachable from another container on the same Docker network (e.g. remote-chrome
+        # reaching nginx), by alias and internal port - as opposed to #url's host-accessible,
+        # externally-mapped port. Uses the same @port this instance was built with, not a
+        # container_ports.first guess: the two methods must agree on which port they're both
+        # describing for the same container, or a caller comparing #url and #alias_url for what's
+        # meant to be the same endpoint could silently get two different services.
+        def alias_url(scheme: "http", path: "")
+          "#{scheme}://#{@container.aliases.first}:#{@port}/#{path}"
+        end
+      end
+    end
+  end
+end

data/lib/bidi2pdf/test_helpers/testcontainers/shared_docker_network.rb

@@ -11,7 +11,7 @@ RSpec.configure do |config|
 
     if uses_containers
       config.shared_network = Docker::Network.create("bidi2pdf-test-net-#{SecureRandom.hex(4)}")
-      puts "🕸️  started shared network #{config.shared_network}"
+      reporter.message("🕸️  started shared network #{config.shared_network}")
     end
   end
 
@@ -19,3 +19,7 @@ RSpec.configure do |config|
     config.shared_network&.remove
   end
 end
+
+def reporter
+  RSpec.configuration.reporter
+end

data/lib/bidi2pdf/test_helpers/testcontainers/testcontainers_refinement.rb

@@ -29,6 +29,39 @@ module Bidi2pdf
         self
       end
 
+      def container_json
+        @_container&.json
+      end
+
+      # Address of the Docker host at which this container's *mapped* ports
+      # are reachable from the test process.
+      #
+      # Resolution belongs to testcontainers: it honours TC_HOST, a tcp:/ssh:
+      # DOCKER_HOST, a native local daemon, and a sibling container reaching
+      # the daemon over the bridge gateway — and it derives #mapped_port from
+      # the same decision, so the two must stay on one path. We only add a
+      # fallback for the cases 0.2.0 leaves unresolved.
+      #
+      # This is not the address containers use to reach each other; for that
+      # the helpers join a shared network and address containers by alias.
+      def accessible_host
+        resolved_host || "localhost"
+      end
+
+      # testcontainers-core 0.2.0 cannot resolve a host when the test process
+      # runs inside a container and the container under test is on a custom
+      # network: #container_gateway_ip hardcodes the "bridge" network key
+      # (docker_container.rb:1074), so #host returns nil. On the default
+      # bridge it can instead reach docker_container.rb:703, which calls an
+      # undefined `bridge_ip`. Both are fixed on testcontainers-ruby main;
+      # treat either as "unresolved" and fall back.
+      def resolved_host
+        value = host
+        value unless value.nil? || value.empty?
+      rescue NoMethodError
+        nil
+      end
+
       def _container_create_options
         opts = super
         network_name = network&.info&.[]("Name")

data/lib/bidi2pdf/test_helpers/testcontainers.rb

@@ -10,6 +10,7 @@ module Bidi2pdf
   module TestHelpers
     module Testcontainers
       require_relative "testcontainers/testcontainers_refinement"
+      require_relative "testcontainers/container_endpoint"
       require_relative "testcontainers/chromedriver_container"
       require_relative "testcontainers/chromedriver_test_helper"
     end

data/lib/bidi2pdf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bidi2pdf
-  VERSION = "0.1.12"
+  VERSION = "0.1.14"
 end

data/lib/bidi2pdf.rb

@@ -51,6 +51,8 @@ module Bidi2pdf
 
   class PrintError < Error; end
 
+  class ScreenshotError < Error; end
+
   class ScriptInjectionError < Error; end
 
   class StyleInjectionError < Error; end

data/sig/bidi2pdf/bidi/add_headers_interceptor.rbs

@@ -1,20 +1,27 @@
 module Bidi2pdf
   module Bidi
     class AddHeadersInterceptor
-      @id: String
-      @client: untyped
-      @headers: Hash[String, String]
+      @headers: untyped
 
-      attr_reader id: String
-      attr_reader headers: Hash[String, String]
+      @url_patterns: untyped
 
-      def initialize: (String id, Hash[String, String] headers, untyped client) -> void
+      @context: untyped
 
-      def handle_event: (Hash[String, untyped] response) -> (nil | untyped)
+      include Interceptor
 
-      private
+      def self.phases: () -> ::Array[untyped]
 
-      attr_reader client: untyped
+      def self.events: () -> ::Array["network.beforeRequestSent"]
+
+      attr_reader headers: untyped
+
+      attr_reader url_patterns: untyped
+
+      attr_reader context: untyped
+
+      def initialize: (headers: untyped, url_patterns: untyped, context: untyped) -> void
+
+      def process_interception: (untyped _event_response, untyped _navigation_id, untyped network_id, untyped _url) -> untyped
     end
   end
 end

data/sig/bidi2pdf/bidi/auth_interceptor.rbs

@@ -1,17 +1,42 @@
 module Bidi2pdf
   module Bidi
     class AuthInterceptor
-      @credentials: Hash[Symbol, String]?
+      @url_patterns: untyped
 
-      def initialize: (?credentials: Hash[Symbol, String]?) -> void
+      @context: untyped
 
-      def intercept: (untyped request) -> untyped
+      @username: untyped
 
-      private
+      @password: untyped
+
+      @network_ids: untyped
+
+      include Interceptor
+
+      def self.phases: () -> ::Array[untyped]
+
+      def self.events: () -> ::Array["network.authRequired"]
+
+      attr_reader headers: untyped
+
+      attr_reader url_patterns: untyped
 
-      def add_auth_header: (untyped request) -> void
+      attr_reader context: untyped
+
+      attr_reader username: untyped
+
+      attr_reader password: untyped
+
+      attr_reader network_ids: untyped
+
+      def initialize: (username: untyped, password: untyped, url_patterns: untyped, context: untyped) -> void
+
+      def process_interception: (untyped _event_response, untyped navigation_id, untyped network_id, untyped url) -> untyped
+
+      private
 
-      def auth_header_value: () -> String?
+      # rubocop:disable Naming/PredicateMethod
+      def handled_bad_credentials: (untyped navigation_id, untyped network_id, untyped url) -> (false | true)
     end
   end
-end
+end

data/sig/bidi2pdf/bidi/browser.rbs

@@ -1,38 +1,11 @@
 module Bidi2pdf
   module Bidi
     class Browser
-      @url: String
-      @chromedriver_manager: Bidi2pdf::ChromedriverManager
-      @browser: untyped
-      @timeout: Integer
-      @debug: bool
+      @client: untyped
 
-      attr_reader browser: untyped
-      attr_reader timeout: Integer
+      def initialize: (untyped client) -> void
 
-      def initialize: (
-          url: String,
-          chromedriver_manager: Bidi2pdf::ChromedriverManager,
-          ?timeout: Integer,
-          ?debug: bool
-        ) -> void
-
-      def navigate: (?reload: bool) -> void
-
-      def current_url: -> String
-
-      def wait_until: [T] (
-          ?timeout: Integer,
-          ?message: String
-        ) { () -> T? } -> T
-
-      def close: () -> void
-
-      private
-
-      def connect: () -> untyped
-
-      def setup_browser: () -> untyped
+      def create_user_context: () -> untyped
     end
   end
-end
+end

data/sig/bidi2pdf/bidi/browser_console_logger.rbs

@@ -0,0 +1,59 @@
+module Bidi2pdf
+  module Bidi
+    class BrowserConsoleLoggerSuggar
+      @browser_console_logger: untyped
+
+      @level: untyped
+
+      @prefix: untyped
+
+      @timestamp: untyped
+
+      @text: untyped
+
+      @args: untyped
+
+      @stack_trace: untyped
+
+      attr_reader browser_console_logger: untyped
+
+      def initialize: (untyped browser_console_logger) -> void
+
+      def with_level: (untyped level) -> self
+
+      def with_prefix: (untyped prefix) -> self
+
+      def with_timestamp: (untyped timestamp) -> self
+
+      def with_text: (untyped text) -> self
+
+      def with_args: (untyped args) -> self
+
+      def with_stack_trace: (untyped stack_trace) -> self
+
+      def log_event: () -> untyped
+
+      def prefix: () -> untyped
+    end
+
+    class BrowserConsoleLogger
+      @logger: untyped
+
+      include JsLoggerHelper
+
+      attr_accessor logger: untyped
+
+      def initialize: (untyped logger) -> void
+
+      def builder: () -> untyped
+
+      def log_message: (untyped level, untyped prefix, untyped text) -> (nil | untyped)
+
+      def log_args: (untyped prefix, untyped args) -> (nil | untyped)
+
+      def log_stack_trace: (untyped prefix, untyped trace) -> untyped
+
+      def self.format_timestamp: (untyped timestamp) -> ("N/A" | untyped)
+    end
+  end
+end

data/sig/bidi2pdf/bidi/browser_tab.rbs

@@ -1,42 +1,269 @@
+# Represents a browser tab for managing interactions and communication
+# using the Bidi2pdf library. This class provides methods for creating
+# browser tabs, managing cookies, navigating to URLs, executing scripts,
+# and handling network events.
+#
+# @example Creating a browser tab
+#   browser_tab = Bidi2pdf::Bidi::BrowserTab.new(client, browsing_context_id, user_context_id)
+#   browser_tab.create_browser_tab
+#
+# @example Navigating to a URL
+#   browser_tab.navigate_to("http://example.com")
+#
+# @example Setting a cookie
+#   browser_tab.set_cookie(
+#     name: "session",
+#     value: "abc123",
+#     domain: "example.com"
+#   )
+#
+# @param [Object] client The WebSocket client for communication.
+# @param [String] browsing_context_id The ID of the browsing context.
+# @param [String] user_context_id The ID of the user context.
 module Bidi2pdf
   module Bidi
+    # Represents a browser tab for managing interactions and communication
+    # using the Bidi2pdf library. This class provides methods for creating
+    # browser tabs, managing cookies, navigating to URLs, executing scripts,
+    # handling network events, and general tab lifecycle management.
+    #
     class BrowserTab
-      @browser: Bidi2pdf::Bidi::Browser
-      @tab_id: String?
-      @session_id: String?
-      @timeout: Integer
+      @client: untyped
 
-      attr_reader browser: Bidi2pdf::Bidi::Browser
-      attr_reader tab_id: String?
-      attr_reader session_id: String?
+      @browsing_context_id: untyped
 
-      def initialize: (
-          browser: Bidi2pdf::Bidi::Browser,
-          ?tab_id: String?,
-          ?timeout: Integer
-        ) -> void
+      @user_context_id: untyped
 
-      def navigate_to: (String url) -> void
+      @tabs: untyped
 
-      def execute_script: [T] (String script, *untyped args) -> T
+      @network_events: untyped
 
-      def wait_for_navigation: (?timeout: Integer) -> void
+      @logger_events: untyped
 
-      def wait_for_element: (
-          selector: String,
-          ?visible: bool,
-          ?timeout: Integer
-        ) -> untyped
+      @navigation_failed_events: untyped
 
-      def capture_screenshot: (?path: String?) -> String
+      @open: untyped
 
-      def close: () -> void
+      @header_interceptor: untyped
+
+      @basic_auth_interceptor: untyped
+
+      @cdp_session: untyped
+
+      @event_handlers_registered: untyped
+
+      @listener_refs: untyped
+
+      include JsLoggerHelper
+
+      # @return [Object] The WebSocket client.
+      attr_reader client: untyped
+
+      # @return [String] The browsing context ID.
+      attr_reader browsing_context_id: untyped
+
+      # @return [String] The user context ID.
+      attr_reader user_context_id: untyped
+
+      # @return [Array<BrowserTab>] The list of tabs.
+      attr_reader tabs: untyped
+
+      # @return [NetworkEvents] The network events handler.
+      attr_reader network_events: untyped
+
+      # @return [Boolean] Whether the tab is open.
+      attr_reader open: untyped
+
+      # @return [LoggerEvents] The logger events handler.
+      attr_reader logger_events: untyped
+
+      # @return [NavigationFailedEvents] The navigation failed events handler.
+      attr_reader navigation_failed_events: untyped
+
+      # Initializes a new browser tab.
+      #
+      # @param [Object] client The WebSocket client for communication.
+      # @param [String] browsing_context_id The ID of the browsing context.
+      # @param [String] user_context_id The ID of the user context.
+      def initialize: (untyped client, untyped browsing_context_id, untyped user_context_id) -> void
+
+      # Creates a new browser tab.
+      #
+      # @return [BrowserTab] The newly created browser tab.
+      def create_browser_tab: () -> untyped
+
+      # Sets a cookie in the browser tab.
+      #
+      # @param [String] name The name of the cookie.
+      # @param [String] value The value of the cookie.
+      # @param [String] domain The domain for the cookie.
+      # @param [String] path The path for the cookie. Defaults to "/".
+      # @param [Boolean] secure Whether the cookie is secure. Defaults to true.
+      # @param [Boolean] http_only Whether the cookie is HTTP-only. Defaults to false.
+      # @param [String] same_site The SameSite attribute for the cookie. Defaults to "strict".
+      # @param [Integer] ttl The time-to-live for the cookie in seconds. Defaults to 30.
+      def set_cookie: (name: untyped, value: untyped, domain: untyped, ?path: ::String, ?secure: bool, ?http_only: bool, ?same_site: ::String, ?ttl: ::Integer) -> untyped
+
+      # Adds headers to requests in the browser tab.
+      #
+      # @param [Hash] headers The headers to add.
+      # @param [Array<String>] url_patterns The URL patterns to match.
+      # @return [AddHeadersInterceptor] The interceptor instance.
+      def add_headers: (headers: untyped, url_patterns: untyped) -> untyped
+
+      # Configures basic authentication for requests in the browser tab.
+      #
+      # @param [String] username The username for authentication.
+      # @param [String] password The password for authentication.
+      # @param [Array<String>] url_patterns The URL patterns to match.
+      # @return [AuthInterceptor] The interceptor instance.
+      def basic_auth: (username: untyped, password: untyped, url_patterns: untyped) -> untyped
+
+      # Navigates the browser tab to a specified URL.
+      #
+      # This method registers necessary event listeners and sends a navigation
+      # command to the browser tab, instructing it to load the specified URL.
+      # It validates that the URL is properly formatted before attempting navigation.
+      #
+      # @param [String] url The URL to navigate to.
+      # @raise [NavigationError] If the URL is invalid or improperly formatted.
+      # @example
+      #   browser_tab.navigate_to("https://example.com")
+      def navigate_to: (untyped url, ?wait: ::String) -> untyped
+
+      # Renders HTML content in the browser tab.
+      #
+      # @param [String] html_content The HTML content to render.
+      # rubocop:disable  Metrics/BlockLength
+      def render_html_content: (untyped html_content, ?wait: ::String) -> untyped
+
+      # Executes a script in the browser tab.
+      #
+      # This method allows you to execute JavaScript code within the context of the browser tab.
+      # Optionally, the script can be wrapped in a JavaScript Promise to handle asynchronous operations.
+      #
+      # @param [String] script The JavaScript code to execute.
+      #   - This can be any valid JavaScript code that you want to run in the browser tab.
+      # @param [Boolean] wrap_in_promise Whether to wrap the script in a Promise. Defaults to false.
+      #   - If true, the script will be wrapped in a Promise to handle asynchronous execution.
+      #   - Use this option when the script involves asynchronous operations like network requests.
+      #     You can use the predefined variable result to store the result of the script.
+      # @return [Object] The result of the script execution.
+      #   - If the script executes successfully, the result of the last evaluated expression is returned.
+      #   - If the script fails, an error or exception details may be returned.
+      def execute_script: (untyped script, ?wrap_in_promise: bool) -> untyped
+
+      # Injects a JavaScript script element into the page, either from a URL or with inline content.
+      #
+      # @param [String, nil] url The URL of the script to load (optional).
+      # @param [String, nil] content The JavaScript content to inject (optional).
+      # @param [String, nil] id The ID attribute for the script element (optional).
+      # @return [Object] The result from the script creation promise.
+      def inject_script: (?url: untyped?, ?content: untyped?, ?id: untyped?) -> untyped
+
+      # Injects a CSS style element into the page, either from a URL or with inline content.
+      #
+      # @param [String, nil] url The URL of the stylesheet to load (optional).
+      # @param [String, nil] content The CSS content to inject (optional).
+      # @param [String, nil] id The ID attribute for the style element (optional).
+      # @return [Object] The result from the style creation promise.
+      def inject_style: (?url: untyped?, ?content: untyped?, ?id: untyped?) -> untyped
+
+      # Waits until the network is idle in the browser tab.
+      #
+      # @param [Integer] timeout The timeout duration in seconds. Defaults to 10.
+      # @param [Float] poll_interval The polling interval in seconds. Defaults to 0.1.
+      def wait_until_network_idle: (?timeout: ::Integer, ?poll_interval: ::Float) -> untyped
+
+      # Waits until the page is fully loaded in the browser tab.
+      #
+      # This method executes a JavaScript script that checks if the page
+      # has finished loading.
+      #
+      # @param [String] check_script The JavaScript code to check if the page is loaded.
+      #   - Defaults to a script that polls the `window.loaded` property.
+      # @return [Object] The result of the script execution.
+      #   - If the page is loaded successfully, the Promise resolves with the value `'done'`.
+      #   - If the script fails, an error or exception details may be returned.
+      def wait_until_page_loaded: (?check_script: untyped?) -> untyped
+
+      # Logs network traffic in the browser tab.
+      #
+      # @param [Symbol] format The format for logging (:console or :pdf). Defaults to :console.
+      # @param [String, nil] output The output file for PDF logging. Defaults to nil.
+      # @param [Hash] print_options Options for printing. Defaults to { background: true }.
+      # @yield [pdf_base64] A block to handle the PDF content.
+      def log_network_traffic: (?format: ::Symbol, ?output: untyped?, ?print_options: ::Hash[untyped, untyped]) { (?) -> untyped } -> (nil | untyped)
+
+      # Closes the browser tab and its associated resources.
+      def close: () -> (nil | untyped)
+
+      # Prints the content of the browser tab.
+      #
+      # @param [String, nil] outputfile The output file for the PDF. Defaults to nil.
+      # @param [Hash] print_options Options for printing. Defaults to { background: true }.
+      # @yield [pdf_base64] A block to handle the PDF content.
+      # @return [String, nil] The base64-encoded PDF content, or nil if outputfile or block is provided.
+      # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity
+      def print: (?untyped? outputfile, ?print_options: ::Hash[untyped, untyped]) ?{ (?) -> untyped } -> untyped
+
+      # Captures a screenshot of the browser tab, mirroring #print's own
+      # file/block/base64-return trichotomy.
+      #
+      # @param [String, nil] outputfile The output file for the PNG. Defaults to nil.
+      # @param [String] origin "document" (default) or "viewport" - see browsingContext.captureScreenshot.
+      # @param [String, nil] format Image format override, e.g. "image/png". Defaults to the browser's own default.
+      # @param [Hash, nil] clip A clip rectangle/element, passed through verbatim. Defaults to nil (full capture).
+      # @yield [png_base64] A block to handle the PNG content.
+      # @return [String, nil] The base64-encoded PNG content, or nil if outputfile or block is provided.
+      # rubocop:disable Metrics/AbcSize
+      def screenshot: (?untyped? outputfile, ?origin: ::String, ?format: untyped?, ?clip: untyped?) ?{ (?) -> untyped } -> untyped
+
+      # Sets the browsing context's viewport - makes a headless render deterministic across
+      # machines, unlike leaving it at the browser's own default.
+      #
+      # @param [Integer] width
+      # @param [Integer] height
+      # @param [Float, nil] device_pixel_ratio Defaults to nil (browser default).
+      def set_viewport: (width: untyped, height: untyped, ?device_pixel_ratio: untyped?) -> untyped
 
       private
 
-      def ensure_tab_active: () -> void
+      def build_command_and_extractor: (untyped print_options) -> ::Array[untyped]
+
+      def cdp_session: () -> untyped
+
+      def navigate_with_listeners: (untyped url, ?wait: ::String) -> untyped
+
+      def register_event_listeners: () -> (nil | untyped)
+
+      def handle_injection_exception: (untyped response, untyped url, untyped exception_class) -> untyped
+
+      # Generates JavaScript code for creating a script element with given parameters.
+      #
+      # @param [String, nil] url The URL of the script to load (optional).
+      # @param [String, nil] content The JavaScript content for the script (optional).
+      # @param [String, nil] id The ID attribute for the script element (optional).
+      # @return [String] JavaScript code that creates a script element.
+      def generate_script_element_code: (?url: untyped?, ?content: untyped?, ?id: untyped?) -> ::String
+
+      # Generates JavaScript code for creating a style element with given parameters.
+      #
+      # @param [String, nil] url The URL of the stylesheet to load (optional).
+      # @param [String, nil] content The CSS content for the style (optional).
+      # @param [String, nil] id The ID attribute for the style element (optional).
+      # @return [String] JavaScript code that creates a style element.
+      def generate_style_element_code: (?url: untyped?, ?content: untyped?, ?id: untyped?) -> ::String
+
+      # Closes the browsing context.
+      def close_context: () -> untyped
+
+      # Removes event listeners for the browser tab.
+      # rubocop:disable Metrics/AbcSize
+      def remove_event_listeners: () -> (nil | untyped)
 
-      def connect_to_tab: () -> String?
+      # Closes all tabs associated with the browser tab.
+      def close_tabs: () -> untyped
     end
   end
-end
+end