puppeteer-ruby 0.50.0.alpha5 → 0.50.0.alpha6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a20cad1d3b0ad0947041ff8086f0336e381d783f1f6edb1aee45263054f5b40
-  data.tar.gz: 70c27f24141dc2326762a419cd32c780fcb9c1b5474246e2dd339dd5246b2090
+  metadata.gz: 24705930799f6f57d44adea7741837c3e5af927f42990f43c1194e0c71a8b813
+  data.tar.gz: 68a01d815bc7d6fe2e7223d08a44c256274469bb5e665a98fb86da37ee202445
 SHA512:
-  metadata.gz: 89f6ed85a37682ced989ece6cddbac7ad9489bd6a1a31fb98f557f96527a8d298b572c078a6438d7030bd6e8c14d3b5a92042d4c1fd5caad1fc1a031335381a1
-  data.tar.gz: fe22e70a18f3319fcb7face324b2de32944f2ebfc0d594a8b33ad2bc95ceb2a0bd8a75bf63fa81369cd892fb8a125edf5c4221e0650476c618fef8455c794d0a
+  metadata.gz: 1c4fc76a84ee3da78f2bca282c0c7b799dffc1bc3160413c3fe32f7053bc007b614b42f4a0867db8e6a7fb10ffb9855d171c311d4a77d0127e7cc5a89737e247
+  data.tar.gz: 31602ed31b3710ba50b4f7b1594edc32ac3f18b1203448d8b4ed24424ff9c068d0d96a7578759d3419574416f7bcc7d9aef22b630f7f9d7e6baa3259c3479af0

data/AGENTS.md

@@ -155,6 +155,7 @@ See `CLAUDE/porting_puppeteer.md` for detailed examples.
   - RxJS Observable flows are replaced with manual EventEmitter listeners + `Async::Promise` (no `fromEmitterEvent`/`merge`/`timeout`), so compose waits explicitly (e.g., `wait_for_navigation`, `set_content`).
   - Use `AsyncUtils` (Barrier-based Promise.all/race + `async_timeout`) instead of RxJS `combineLatest`/`firstValueFrom`/`timeout`.
   - `WaitTask`/`TaskManager` mirror Puppeteer's polling waits; no AbortSignal, use Async tasks + cancellation.
+  - **AbortSignal is NOT supported**: Do NOT port `signal` parameters from upstream Puppeteer. Ruby's concurrency model doesn't align with JavaScript's AbortController pattern.
   - `ReactorRunner` runs a dedicated Async reactor thread and proxies sync calls into it (wrap/unwrap).
   - Use `Core::EventEmitter` + symbols instead of RxJS event streams; clean up listeners explicitly.
   - Disposable patterns: `Core::Disposable::DisposableStack`/`DisposableMixin` stand in for JS DisposableStack/AsyncDisposableStack.

data/CLAUDE/porting_puppeteer.md

@@ -197,6 +197,16 @@ Note: Some tests (e.g., `BrowserContext#override_permissions`) may be split into
 4. **Preserve asset files** - Keep `spec/assets/` identical to upstream `test/assets/`
 5. **Separate Ruby-specific tests** - Move Ruby-only features to `*_ext_spec.rb` files
 
+## Fidelity Notes
+
+- `JSHandle#json_value`: Node.js normalizes CDP errors like "Object reference chain is too long" and
+  "Object couldn't be returned by value" via `ExecutionContext#rewriteError` to `undefined`. The
+  Ruby port keeps the same behavior by rescuing in `JSHandle#json_value` and returning `nil`.
+- PSelectors/PQueryHandler: The Ruby PSelector path relies on `PQueryHandler` with the same
+  `IDENT_TOKEN_START` regex behavior as upstream. Keep the CSS query selector JS in a single-quoted
+  heredoc so the regex survives Ruby parsing. `wait_for` should use `Frame#default_timeout` to match
+  Node's timeout settings.
+
 ### Ruby-Specific Tests (`*_ext_spec.rb`)
 
 When porting tests, separate Ruby-only features into dedicated extension spec files:
@@ -410,6 +420,26 @@ diff spec/assets/input/keyboard.html <(curl -s https://raw.githubusercontent.com
 
 ### Common Gotchas
 
+#### 0. AbortSignal Not Supported
+
+**Do NOT port `signal` parameters from upstream Puppeteer.**
+
+```typescript
+// TypeScript - has signal parameter
+async click(options?: {signal?: AbortSignal}): Promise<void> {
+  // ...
+}
+```
+
+```ruby
+# Ruby - do NOT include signal parameter
+def click(delay: nil, button: nil)
+  # ...
+end
+```
+
+Ruby's concurrency model doesn't align with JavaScript's AbortController/AbortSignal pattern. Use timeout parameters instead for cancellation.
+
 #### 1. Event Type Differences
 
 Upstream keyboard tests use `input` events, not `keypress`:

data/CLAUDE/spec_migration_plans.md

@@ -88,7 +88,7 @@ Tests must be **faithfully ported** from Node.js Puppeteer to Ruby RSpec:
 | jshandle.spec.ts | js_handle_spec.rb | [x] Ported |
 | keyboard.spec.ts | keyboard_spec.rb | [x] Ported |
 | launcher.spec.ts | launcher_spec.rb | [x] Ported |
-| locator.spec.ts | - | **[MISSING]** Locator API not ported |
+| locator.spec.ts | locator_spec.rb | [x] Ported |
 | mouse.spec.ts | mouse_spec.rb | [x] Ported |
 | navigation.spec.ts | navigation_spec.rb | [x] Ported |
 | network.spec.ts | network_spec.rb | [x] Ported |
@@ -137,7 +137,7 @@ Node.js tests include:
 - `Locator.prototype.map/filter/wait/clone`
 - `FunctionLocator`
 
-**Ruby status:** Not implemented. This is a significant new API addition.
+**Ruby status:** Implemented and ported to `spec/integration/locator_spec.rb`.
 
 ### 3. Navigation Tests (`navigation.spec.ts`)
 **Priority: HIGH** - Core navigation functionality
@@ -191,7 +191,7 @@ Node.js tests:
 - [x] Port missing `target.spec.ts` tests → Create `target_spec.rb` (AbortSignal pending)
 
 ### Phase 2: New APIs (High Priority)
-- [ ] Implement Locator API and port `locator.spec.ts` tests
+- [x] Implement Locator API and port `locator.spec.ts` tests
 
 ### Phase 3: Medium Priority
 - [x] Port `download.spec.ts` tests
@@ -1000,17 +1000,16 @@ Most OOPIF tests are ported including:
 
 ### Spec Files Status Summary
 
-**Fully Ported (35):**
-aria_query_handler, browser, browser_context, browser_context_cookies, click, connect (in launcher), cookies, coverage, defaultbrowsercontext (in browser_context), dialog, download, drag_and_drop, element_handle, emulation, evaluation, frame, idle_override, input, js_handle, keyboard, launcher, mouse, navigation, network, oopif, page, query_handler, query_selector, request_interception, request_interception_experimental, screenshot, touchscreen, tracing, waittask, worker
+**Fully Ported (36):**
+aria_query_handler, browser, browser_context, browser_context_cookies, click, connect (in launcher), cookies, coverage, defaultbrowsercontext (in browser_context), dialog, download, drag_and_drop, element_handle, emulation, evaluation, frame, idle_override, input, js_handle, keyboard, launcher, locator, mouse, navigation, network, oopif, page, query_handler, query_selector, request_interception, request_interception_experimental, screenshot, touchscreen, tracing, waittask, worker
 
 **Partially Ported (1):**
 - target.spec.ts → target_spec.rb (AbortSignal unsupported)
 
-**Missing - High Priority (4):**
+**Missing - High Priority (3):**
 1. **accessibility.spec.ts** - Accessibility API not implemented
-2. **locator.spec.ts** - Locator API not implemented
-3. **proxy.spec.ts** - Proxy support not implemented
-4. **autofill.spec.ts** - Autofill not implemented
+2. **proxy.spec.ts** - Proxy support not implemented
+3. **autofill.spec.ts** - Autofill not implemented
 
 **Low Priority/N/A (11):**
 acceptInsecureCerts, bluetooth-emulation, debugInfo, device-request-prompt, fixtures, headful, injected, stacktrace, webExtension, webgl
@@ -1019,7 +1018,6 @@ acceptInsecureCerts, bluetooth-emulation, debugInfo, device-request-prompt, fixt
 
 #### High Priority (Core functionality gaps)
 1. **Accessibility API** - Add `Page#accessibility` and port accessibility.spec.ts
-2. **Locator API** - Implement Locator class and port locator.spec.ts
 
 #### Medium Priority
 1. **proxy.spec.ts** - Proxy configuration support

data/README.md

@@ -1,8 +1,9 @@
 [![Gem Version](https://badge.fury.io/rb/puppeteer-ruby.svg)](https://badge.fury.io/rb/puppeteer-ruby)
 
 > [!IMPORTANT]
-> The `main` branch is currently under **HEAVY DEVELOPMENT** for increased stability.
-> If you need the latest stable release, please refer to the [ref-2025 tag](https://github.com/YusukeIwaki/puppeteer-ruby/tree/ref-2025).
+> - This library now requires **Ruby 3.2 or later**.
+> - Firefox support has been moved to [puppeteer-bidi](https://github.com/YusukeIwaki/puppeteer-bidi).
+> - For older versions, please refer to the [ref-2025 tag](https://github.com/YusukeIwaki/puppeteer-ruby/tree/ref-2025).
 
 # Puppeteer in Ruby
 

data/docs/api_coverage.md

@@ -1,6 +1,6 @@
 # API coverages
 - Puppeteer version: v24.35.0
-- puppeteer-ruby version: 0.50.0.alpha5
+- puppeteer-ruby version: 0.50.0.alpha4
 
 ## Puppeteer
 
@@ -123,7 +123,7 @@
 * $$ => `#query_selector_all`
 * $$eval => `#eval_on_selector_all`
 * $eval => `#eval_on_selector`
-* ~~asLocator~~
+* asLocator => `#as_locator`
 * ~~autofill~~
 * ~~backendNodeId~~
 * boundingBox => `#bounding_box`
@@ -193,7 +193,7 @@
 * goto
 * hover
 * isDetached => `#detached?`
-* ~~locator~~
+* locator
 * name
 * page
 * parentFrame => `#parent_frame`
@@ -277,23 +277,23 @@
 * type => `#type_text`
 * up
 
-## ~~Locator~~
+## Locator
 
-* ~~click~~
-* ~~clone~~
-* ~~fill~~
-* ~~filter~~
-* ~~hover~~
-* ~~map~~
+* click
+* clone
+* fill
+* filter
+* hover
+* map
 * ~~race~~
-* ~~scroll~~
-* ~~setEnsureElementIsInTheViewport~~
-* ~~setTimeout~~
-* ~~setVisibility~~
-* ~~setWaitForEnabled~~
-* ~~setWaitForStableBoundingBox~~
-* ~~wait~~
-* ~~waitHandle~~
+* scroll
+* setEnsureElementIsInTheViewport => `#set_ensure_element_is_in_the_viewport`
+* setTimeout => `#set_timeout`
+* setVisibility => `#set_visibility`
+* setWaitForEnabled => `#set_wait_for_enabled`
+* setWaitForStableBoundingBox => `#set_wait_for_stable_bounding_box`
+* wait
+* waitHandle => `#wait_handle`
 
 ## Mouse
 
@@ -344,7 +344,7 @@
 * focus
 * frames
 * ~~getDefaultNavigationTimeout~~
-* ~~getDefaultTimeout~~
+* getDefaultTimeout => `#default_timeout`
 * goBack => `#go_back`
 * goForward => `#go_forward`
 * goto
@@ -353,7 +353,7 @@
 * isDragInterceptionEnabled => `#drag_interception_enabled?`
 * isJavaScriptEnabled => `#javascript_enabled?`
 * isServiceWorkerBypassed => `#service_worker_bypassed?`
-* ~~locator~~
+* locator
 * mainFrame => `#main_frame`
 * metrics
 * ~~openDevTools~~

data/lib/puppeteer/element_handle.rb

@@ -152,6 +152,11 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     self
   end
 
+  # @rbs return: Puppeteer::Locator -- Locator for this element
+  def as_locator
+    Puppeteer::NodeLocator.create_from_handle(@frame, self)
+  end
+
   # @rbs return: bool -- Whether element is visible
   def visible?
     check_visibility(true)

data/lib/puppeteer/frame.rb

@@ -51,6 +51,21 @@ class Puppeteer::Frame
     @frame_manager.page
   end
 
+  # @rbs return: Numeric -- Default timeout in milliseconds
+  def default_timeout
+    @frame_manager.timeout_settings.timeout
+  end
+
+  # @rbs selector_or_function: String -- Selector or JS function
+  # @rbs return: Puppeteer::Locator -- Locator for selector or function
+  def locator(selector_or_function)
+    if Puppeteer::Locator.function_string?(selector_or_function)
+      Puppeteer::FunctionLocator.create(self, selector_or_function)
+    else
+      Puppeteer::NodeLocator.create(self, selector_or_function)
+    end
+  end
+
   # @rbs return: bool -- Whether this is an OOPIF frame
   def oop_frame?
     @client != @frame_manager.client

data/lib/puppeteer/js_handle.rb

@@ -124,11 +124,30 @@ class Puppeteer::JSHandle
       return Time.iso8601(iso_value) if iso_value
     end
 
-    value = evaluate('(object) => object')
-    if value.nil?
+    begin
+      result = @client.send_message('Runtime.callFunctionOn',
+        functionDeclaration: 'function() { return this; }',
+        objectId: @remote_object.object_id_value,
+        returnByValue: true,
+        awaitPromise: true,
+        userGesture: true,
+      )
+    rescue Puppeteer::Connection::ProtocolError => err
+      if err.message.include?('Object reference chain is too long') ||
+        err.message.include?("Object couldn't be returned by value")
+        return nil
+      end
+      raise
+    end
+    if result['exceptionDetails']
+      raise Puppeteer::ExecutionContext::EvaluationError.new("Evaluation failed: #{result['exceptionDetails']}")
+    end
+
+    remote_object = Puppeteer::RemoteObject.new(result['result'])
+    if remote_object.type == 'undefined'
       raise Puppeteer::Error.new('Could not serialize referenced object')
     end
-    value
+    remote_object.value
   end
 
   def as_element