puppeteer-bidi 0.0.3.beta1 → 0.0.3.beta2

data/CLAUDE/rspec_pending_vs_skip.md

@@ -1,262 +0,0 @@
-# RSpec: pending vs skip
-
-## Overview
-
-RSpec provides two mechanisms for handling tests that cannot or should not run: `pending` and `skip`. Understanding when to use each is critical for documenting browser limitations and future work.
-
-## Difference
-
-### skip
-
-**Completely skips the test** - does not run any code:
-
-```ruby
-it 'should work' do
-  skip 'feature not implemented'
-
-  # This code NEVER runs
-  page.do_something
-  expect(result).to be_truthy
-end
-```
-
-**Output**: Test marked as skipped, no execution, no error trace.
-
-### pending
-
-**Runs the test** and expects it to fail:
-
-```ruby
-it 'should work' do
-  pending 'feature not implemented'
-
-  # This code RUNS and is expected to fail
-  page.do_something  # Raises error
-  expect(result).to be_truthy
-end
-```
-
-**Output**: Test marked as pending with full error trace showing exactly what failed.
-
-## When to Use Each
-
-### Use `pending` for:
-
-1. **Browser limitations** - Features not yet supported by Firefox BiDi
-2. **Known failures** - Code exists but fails due to external issues
-3. **Documentation** - Want to show error trace to document what's missing
-
-### Use `skip` for:
-
-1. **Unimplemented features** - Code doesn't exist yet
-2. **Environment issues** - Test requires specific setup not available
-3. **Temporary exclusion** - Test is broken and needs fixing
-
-## Firefox BiDi Limitations
-
-For features that exist in BiDi spec but not yet implemented in Firefox, use `pending`:
-
-```ruby
-describe 'Page.setJavaScriptEnabled' do
-  it 'should work' do
-    # Pending: Firefox does not yet support emulation.setScriptingEnabled BiDi command
-    pending 'emulation.setScriptingEnabled not supported by Firefox yet'
-
-    with_test_state do |page:, **|
-      page.set_javascript_enabled(false)
-      expect(page.javascript_enabled?).to be false
-
-      page.goto('data:text/html, <script>var something = "forbidden"</script>')
-
-      error = nil
-      begin
-        page.evaluate('something')
-      rescue => e
-        error = e
-      end
-
-      expect(error).not_to be_nil
-      expect(error.message).to include('something is not defined')
-    end
-  end
-end
-```
-
-**Why pending, not skip**:
-- Code path exists (`page.set_javascript_enabled`)
-- BiDi command exists in spec (`emulation.setScriptingEnabled`)
-- Firefox just hasn't implemented it yet
-- Running the test shows exactly what error Firefox returns
-
-## Output Comparison
-
-### With `skip`
-
-```
-Page
-  Page.setJavaScriptEnabled
-    should work (SKIPPED)
-```
-
-No error information, no way to know what's missing.
-
-### With `pending`
-
-```
-Page
-  Page.setJavaScriptEnabled
-    should work (PENDING: emulation.setScriptingEnabled not supported by Firefox yet)
-
-Pending: (Failures listed here are expected and do not affect your suite's status)
-
-  1) Page Page.setJavaScriptEnabled should work
-     # emulation.setScriptingEnabled not supported by Firefox yet
-     Failure/Error: raise ProtocolError, "BiDi error (#{method}): #{result['error']['message']}"
-
-     Puppeteer::Bidi::Connection::ProtocolError:
-       BiDi error (emulation.setScriptingEnabled):
-     # ./lib/puppeteer/bidi/connection.rb:71:in 'send_command'
-     # ./lib/puppeteer/bidi/core/browsing_context.rb:331:in 'set_javascript_enabled'
-     # ./lib/puppeteer/bidi/page.rb:313:in 'set_javascript_enabled'
-```
-
-Full error trace shows:
-- Which BiDi command failed
-- Error message from Firefox
-- Complete stack trace
-- Where in our code it failed
-
-## Implementation Pattern
-
-### Before (Incorrect - Using skip in before block)
-
-```ruby
-describe 'Page.setJavaScriptEnabled' do
-  before do
-    skip 'emulation.setScriptingEnabled not supported by Firefox yet'
-  end
-
-  it 'should work' do
-    # Never runs
-  end
-
-  it 'setInterval should pause' do
-    # Never runs
-  end
-end
-```
-
-**Problems**:
-- Tests don't run at all
-- No error information
-- Not clear which BiDi command is missing
-
-### After (Correct - Using pending in individual tests)
-
-```ruby
-describe 'Page.setJavaScriptEnabled' do
-  it 'should work' do
-    pending 'emulation.setScriptingEnabled not supported by Firefox yet'
-
-    with_test_state do |page:, **|
-      # Test code runs and fails with proper error trace
-    end
-  end
-
-  it 'setInterval should pause' do
-    pending 'emulation.setScriptingEnabled not supported by Firefox yet'
-
-    with_test_state do |page:, **|
-      # Test code runs and fails with proper error trace
-    end
-  end
-end
-```
-
-**Benefits**:
-- Tests run and document exact failure
-- Each test can have specific pending message
-- Easy to identify when Firefox adds support (test will pass)
-- Full error trace available for debugging
-
-## Best Practices
-
-### 1. Be Specific in Pending Messages
-
-```ruby
-# Good
-pending 'emulation.setScriptingEnabled not supported by Firefox yet'
-
-# Bad
-pending 'not supported'
-```
-
-### 2. Include BiDi Command Name
-
-```ruby
-# Good
-pending 'browsingContext.setViewport not implemented'
-
-# Bad
-pending 'viewport not working'
-```
-
-### 3. Document When to Re-check
-
-```ruby
-# Good
-pending 'network.addIntercept requires Firefox 120+, current: 119'
-
-# Bad
-pending 'network interception broken'
-```
-
-### 4. Remove Pending When Fixed
-
-When Firefox adds support, the test will fail with:
-```
-Expected example to fail but it passed
-```
-
-This is your signal to remove the `pending` line!
-
-## Firefox BiDi Limitations (Current)
-
-As of this implementation, the following BiDi commands are not supported by Firefox:
-
-1. `emulation.setScriptingEnabled` - Control JavaScript execution
-   - Tests: `spec/integration/page_spec.rb` (2 tests)
-   - Tests: `spec/integration/click_spec.rb` (1 test)
-
-## Files Changed
-
-- `spec/integration/click_spec.rb`: Changed `skip` to `pending` (line 71)
-- `spec/integration/page_spec.rb`: Moved `skip` from before block to individual tests as `pending` (lines 19, 48)
-
-## Test Results
-
-```bash
-bundle exec rspec spec/integration/
-# 108 examples, 0 failures, 4 pending
-```
-
-All pending tests show proper error traces documenting Firefox limitations.
-
-## Key Takeaways
-
-1. **Use `pending` for browser limitations** - Shows what's missing with error trace
-2. **Use `skip` for unimplemented features** - Our code doesn't exist yet
-3. **Be specific in messages** - Include BiDi command name and reason
-4. **Pending in test body, not before block** - Each test should be explicit
-5. **Pending tests run code** - They document exact failure mode
-6. **Remove pending when fixed** - Test will fail with "expected to fail but passed"
-
-## References
-
-- [RSpec Documentation: Pending and Skipped Examples](https://rspec.info/features/3-12/rspec-core/pending-and-skipped-examples/)
-- [WebDriver BiDi Spec](https://w3c.github.io/webdriver-bidi/) - Check which commands are standardized
-- [Firefox BiDi Implementation Status](https://wiki.mozilla.org/WebDriver/RemoteProtocol/WebDriver_BiDi) - Check Firefox support
-
-## Commit Reference
-
-See commit: "test: Use pending instead of skip for Firefox unsupported features"

data/CLAUDE/selector_evaluation.md

@@ -1,198 +0,0 @@
-# Selector Evaluation Methods Implementation
-
-This document explains the implementation of `eval_on_selector` and `eval_on_selector_all` methods, including delegation patterns, handle lifecycle, and performance considerations.
-
-### Overview
-
-The `eval_on_selector` and `eval_on_selector_all` methods provide convenient shortcuts for querying elements and evaluating JavaScript functions on them, equivalent to Puppeteer's `$eval` and `$$eval`.
-
-### API Design
-
-#### Method Naming Convention
-
-Ruby cannot use `$` in method names, so we use descriptive alternatives:
-
-| Puppeteer | Ruby | Description |
-|-----------|------|-------------|
-| `$eval` | `eval_on_selector` | Evaluate on first matching element |
-| `$$eval` | `eval_on_selector_all` | Evaluate on all matching elements |
-
-#### Implementation Hierarchy
-
-Following Puppeteer's delegation pattern:
-
-```
-Page#eval_on_selector(_all)
-  ↓ delegates to
-Frame#eval_on_selector(_all)
-  ↓ delegates to
-ElementHandle#eval_on_selector(_all) (on document)
-  ↓ implementation
-  1. query_selector(_all) - Find element(s)
-  2. Validate results
-  3. evaluate() - Execute function
-  4. dispose - Clean up handles
-```
-
-### Implementation Details
-
-#### Page and Frame Methods
-
-```ruby
-# lib/puppeteer/bidi/page.rb
-def eval_on_selector(selector, page_function, *args)
-  main_frame.eval_on_selector(selector, page_function, *args)
-end
-
-# lib/puppeteer/bidi/frame.rb
-def eval_on_selector(selector, page_function, *args)
-  document.eval_on_selector(selector, page_function, *args)
-end
-```
-
-**Design rationale**: Page and Frame act as thin wrappers, delegating to the document element handle.
-
-#### ElementHandle#eval_on_selector
-
-```ruby
-def eval_on_selector(selector, page_function, *args)
-  assert_not_disposed
-
-  element_handle = query_selector(selector)
-  raise SelectorNotFoundError, selector unless element_handle
-
-  begin
-    element_handle.evaluate(page_function, *args)
-  ensure
-    element_handle.dispose
-  end
-end
-```
-
-**Key points**:
-- Throws `SelectorNotFoundError` if no element found (matches Puppeteer behavior)
-- Uses `begin/ensure` to guarantee handle disposal
-- Searches within element's subtree (not page-wide)
-
-#### ElementHandle#eval_on_selector_all
-
-```ruby
-def eval_on_selector_all(selector, page_function, *args)
-  assert_not_disposed
-
-  element_handles = query_selector_all(selector)
-
-  begin
-    # Create array handle in browser context
-    array_handle = @realm.call_function(
-      '(...elements) => elements',
-      false,
-      arguments: element_handles.map(&:remote_value)
-    )
-
-    array_js_handle = JSHandle.from(array_handle['result'], @realm)
-
-    begin
-      array_js_handle.evaluate(page_function, *args)
-    ensure
-      array_js_handle.dispose
-    end
-  ensure
-    element_handles.each(&:dispose)
-  end
-end
-```
-
-**Key points**:
-- Returns result for empty array without error (differs from `eval_on_selector`)
-- Creates array handle using spread operator trick: `(...elements) => elements`
-- Nested `ensure` blocks for proper resource cleanup
-- Disposes both individual element handles and array handle
-
-### Error Handling Differences
-
-| Method | Behavior when no elements found |
-|--------|--------------------------------|
-| `eval_on_selector` | Throws `SelectorNotFoundError` |
-| `eval_on_selector_all` | Returns evaluation result (e.g., `0` for `divs => divs.length`) |
-
-This matches Puppeteer's behavior:
-- `$eval`: Must find exactly one element
-- `$$eval`: Works with zero or more elements
-
-### Usage Examples
-
-```ruby
-# Basic usage
-page.set_content('<section id="test">Hello</section>')
-id = page.eval_on_selector('section', 'e => e.id')
-# => "test"
-
-# With arguments
-text = page.eval_on_selector('section', '(e, suffix) => e.textContent + suffix', '!')
-# => "Hello!"
-
-# ElementHandle arguments
-div = page.query_selector('div')
-result = page.eval_on_selector('section', '(e, div) => e.textContent + div.textContent', div)
-
-# eval_on_selector_all with multiple elements
-page.set_content('<div>A</div><div>B</div><div>C</div>')
-count = page.eval_on_selector_all('div', 'divs => divs.length')
-# => 3
-
-# Subtree search with ElementHandle
-tweet = page.query_selector('.tweet')
-likes = tweet.eval_on_selector('.like', 'node => node.innerText')
-# Only searches within .tweet element
-```
-
-### Test Coverage
-
-**Total**: 13 integration tests
-
-**Page.eval_on_selector** (4 tests):
-- Basic functionality (property access)
-- Argument passing
-- ElementHandle arguments
-- Error on missing selector
-
-**ElementHandle.eval_on_selector** (3 tests):
-- Basic functionality
-- Subtree isolation
-- Error on missing selector
-
-**Page.eval_on_selector_all** (4 tests):
-- Basic functionality (array length)
-- Extra arguments
-- ElementHandle arguments
-- Large element count (1001 elements)
-
-**ElementHandle.eval_on_selector_all** (2 tests):
-- Subtree retrieval
-- Empty result handling
-
-### Performance Considerations
-
-#### Handle Lifecycle
-
-- **eval_on_selector**: Creates 1 temporary handle per call
-- **eval_on_selector_all**: Creates N+1 handles (N elements + 1 array)
-- All handles automatically disposed after evaluation
-
-#### Large Element Sets
-
-Tested with 1001 elements without issues. The implementation efficiently:
-1. Queries all elements at once
-2. Creates single array handle
-3. Evaluates function in single round-trip
-4. Disposes all handles in parallel
-
-### Reference Implementation
-
-Based on Puppeteer's implementation:
-- [Page.$eval](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts)
-- [Frame.$eval](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Frame.ts)
-- [ElementHandle.$eval](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/ElementHandle.ts)
-- [Test specs](https://github.com/puppeteer/puppeteer/blob/main/test/src/queryselector.spec.ts)
-