puppeteer-bidi 0.0.3.beta1 → 0.0.3.beta2

data/CLAUDE/javascript_evaluation.md

@@ -1,341 +0,0 @@
-# JavaScript Evaluation Implementation
-
-This document details the implementation of JavaScript evaluation in Page and Frame classes, including script detection logic, argument serialization, and result deserialization.
-
-### Page.evaluate and Frame.evaluate
-
-The `evaluate` method supports both JavaScript expressions and functions with proper argument serialization.
-
-#### Detection Logic
-
-The implementation distinguishes between three types of JavaScript code:
-
-1. **Expressions**: Simple JavaScript code
-2. **Functions**: Arrow functions or function declarations (use `script.callFunction`)
-3. **IIFE**: Immediately Invoked Function Expressions (use `script.evaluate`)
-
-```ruby
-# Expression - uses script.evaluate
-page.evaluate('7 * 3')  # => 21
-
-# Function - uses script.callFunction
-page.evaluate('(a, b) => a + b', 3, 4)  # => 7
-
-# IIFE - uses script.evaluate (not script.callFunction)
-page.evaluate('(() => document.title)()')  # => "Page Title"
-```
-
-#### IIFE Detection Pattern
-
-**Critical**: IIFE must be detected and treated as expressions:
-
-```ruby
-# Check if it's an IIFE - ends with () after the function body
-is_iife = script_trimmed.match?(/\)\s*\(\s*\)\s*\z/)
-
-# Only treat as function if not IIFE
-is_function = !is_iife && (
-  script_trimmed.match?(/\A\s*(?:async\s+)?(?:\(.*?\)|[a-zA-Z_$][\w$]*)\s*=>/) ||
-  script_trimmed.match?(/\A\s*(?:async\s+)?function\s*\w*\s*\(/)
-)
-```
-
-**Why this matters**: IIFE like `(() => {...})()` looks like a function but must be evaluated as an expression. Using `script.callFunction` on IIFE causes syntax errors.
-
-#### Argument Serialization
-
-Arguments are serialized to BiDi `LocalValue` format:
-
-```ruby
-# Special numbers
-{ type: 'number', value: 'NaN' }
-{ type: 'number', value: 'Infinity' }
-{ type: 'number', value: '-0' }
-
-# Collections
-{ type: 'array', value: [...] }
-{ type: 'object', value: [[key, value], ...] }
-{ type: 'map', value: [[key, value], ...] }
-```
-
-#### Result Deserialization
-
-BiDi returns results in special format that must be deserialized:
-
-```ruby
-# BiDi response format
-{
-  "type" => "success",
-  "realm" => "...",
-  "result" => {
-    "type" => "number",
-    "value" => 42
-  }
-}
-
-# Extract and deserialize
-actual_result = result['result'] || result
-deserialize_result(actual_result)  # => 42
-```
-
-#### Exception Handling
-
-Exceptions from JavaScript are returned in the result, not thrown by BiDi:
-
-```ruby
-if result['type'] == 'exception'
-  exception_details = result['exceptionDetails']
-  text = exception_details['text']  # "ReferenceError: notExistingObject is not defined"
-  raise text
-end
-```
-
-### Core::Realm Return Values
-
-**Important**: Core::Realm methods return the **complete BiDi result**, not just the value:
-
-```ruby
-# Core::Realm.call_function returns:
-{
-  "type" => "success" | "exception",
-  "realm" => "...",
-  "result" => {...} | nil,
-  "exceptionDetails" => {...} | nil
-}
-
-# NOT result['result'] (this was a bug that was fixed)
-```
-
-### Testing Strategy
-
-#### Integration Tests Organization
-
-```
-spec/
-├── unit/                    # Fast unit tests (future)
-├── integration/             # Browser automation tests
-│   ├── examples/           # Example-based tests
-│   │   └── screenshot_spec.rb
-│   └── screenshot_spec.rb  # Feature test suites
-├── assets/                 # Test HTML/CSS/JS files
-│   ├── grid.html
-│   ├── scrollbar.html
-│   ├── empty.html
-│   └── digits/*.png
-├── golden-firefox/         # Reference images
-│   └── screenshot-*.png
-└── support/               # Test utilities
-    ├── test_server.rb
-    └── golden_comparator.rb
-```
-
-#### Implemented Screenshot Tests
-
-All 12 tests ported from [Puppeteer's screenshot.spec.ts](https://github.com/puppeteer/puppeteer/blob/main/test/src/screenshot.spec.ts):
-
-1. **should work** - Basic screenshot functionality
-2. **should clip rect** - Clipping specific region
-3. **should get screenshot bigger than the viewport** - Offscreen clip with captureBeyondViewport
-4. **should clip bigger than the viewport without "captureBeyondViewport"** - Viewport coordinate transformation
-5. **should run in parallel** - Thread-safe parallel screenshots on single page
-6. **should take fullPage screenshots** - Full page with document origin
-7. **should take fullPage screenshots without captureBeyondViewport** - Full page with viewport resize
-8. **should run in parallel in multiple pages** - Concurrent screenshots across multiple pages
-9. **should work with odd clip size on Retina displays** - Odd pixel dimensions (11x11)
-10. **should return base64** - Base64 encoding verification
-11. **should take fullPage screenshots when defaultViewport is null** - No explicit viewport
-12. **should restore to original viewport size** - Viewport restoration after fullPage
-
-Run tests:
-```bash
-bundle exec rspec spec/integration/screenshot_spec.rb
-# Expected: 12 examples, 0 failures (completes in ~8 seconds with optimized spec_helper)
-```
-
-#### Test Performance Optimization
-
-**Critical**: Integration tests are ~19x faster with browser reuse strategy.
-
-##### Before Optimization (Per-test Browser Launch)
-```ruby
-def with_test_state(**options)
-  server = TestServer::Server.new
-  server.start
-
-  with_browser(**options) do |browser|  # New browser per test!
-    context = browser.default_browser_context
-    page = browser.new_page
-    yield(page: page, server: server, browser: browser, context: context)
-  end
-ensure
-  server.stop
-end
-```
-
-**Performance**: ~195 seconds for 35 tests (browser launch overhead × 35)
-
-##### After Optimization (Shared Browser)
-```ruby
-# In spec_helper.rb
-config.before(:suite) do
-  if RSpec.configuration.files_to_run.any? { |f| f.include?('spec/integration') }
-    $shared_browser = Puppeteer::Bidi.launch_browser_instance(headless: headless_mode?)
-    $shared_test_server = TestServer::Server.new
-    $shared_test_server.start
-  end
-end
-
-def with_test_state(**options)
-  if $shared_browser && options.empty?
-    # Create new page (tab) per test
-    page = $shared_browser.new_page
-    context = $shared_browser.default_browser_context
-
-    begin
-      yield(page: page, server: $shared_test_server, browser: $shared_browser, context: context)
-    ensure
-      page.close unless page.closed?  # Clean up tab
-    end
-  else
-    # Fall back to per-test browser for custom options
-  end
-end
-```
-
-**Performance**: ~10 seconds for 35 tests (1 browser launch + 35 tab creations)
-
-##### Performance Results
-
-| Test Suite | Before | After | Improvement |
-|------------|--------|-------|-------------|
-| **evaluation_spec (23 tests)** | 127s | **7.17s** | **17.7x faster** |
-| **screenshot_spec (12 tests)** | 68s | **8.47s** | **8.0x faster** |
-| **Combined (35 tests)** | 195s | **10.33s** | **18.9x faster** 🚀 |
-
-**Key Benefits**:
-- Browser launch only once per suite
-- Each test gets fresh page (tab) for isolation
-- Cleanup handled automatically
-- Backward compatible (custom options fall back to per-test browser)
-
-#### Environment Variables
-
-```bash
-HEADLESS=false  # Run browser in non-headless mode for debugging
-```
-
-### Debugging Techniques
-
-#### 1. Save Screenshots for Inspection
-
-```ruby
-# In golden_comparator.rb
-def save_screenshot(screenshot_base64, filename)
-  output_dir = File.join(__dir__, '../output')
-  FileUtils.mkdir_p(output_dir)
-  File.binwrite(File.join(output_dir, filename),
-                Base64.decode64(screenshot_base64))
-end
-```
-
-#### 2. Compare Images Pixel-by-Pixel
-
-```ruby
-cat > /tmp/compare.rb << 'EOF'
-require 'chunky_png'
-
-golden = ChunkyPNG::Image.from_file('spec/golden-firefox/screenshot.png')
-actual = ChunkyPNG::Image.from_file('spec/output/debug.png')
-
-diff_count = 0
-(0...golden.height).each do |y|
-  (0...golden.width).each do |x|
-    if golden[x, y] != actual[x, y]
-      diff_count += 1
-      puts "Diff at (#{x}, #{y})" if diff_count <= 10
-    end
-  end
-end
-puts "Total: #{diff_count} pixels differ"
-EOF
-ruby /tmp/compare.rb
-```
-
-#### 3. Debug BiDi Responses
-
-```ruby
-# Temporarily add debugging
-result = @browsing_context.default_realm.evaluate(script, true)
-puts "BiDi result: #{result.inspect}"
-deserialize_result(result)
-```
-
-### Common Pitfalls and Solutions
-
-#### 1. BiDi Protocol Differences
-
-**Problem:** BiDi `origin` parameter behavior differs from expectations
-
-**Solution:** Consult BiDi spec and test both `'document'` and `'viewport'` origins
-
-```ruby
-# document: Absolute coordinates in full page
-# viewport: Relative to current viewport
-options[:origin] = capture_beyond_viewport ? 'document' : 'viewport'
-```
-
-#### 2. Image Comparison Failures
-
-**Problem:** Golden images don't match exactly (1-2 pixel differences)
-
-**Solution:** Implement tolerance in comparison
-
-```ruby
-# Allow small rendering differences (±1 RGB per channel)
-compare_with_golden(screenshot, 'golden.png', pixel_threshold: 1)
-```
-
-#### 3. Viewport State Management
-
-**Problem:** Viewport not restored after fullPage screenshot
-
-**Solution:** Use `ensure` block
-
-```ruby
-begin
-  set_viewport(full_page_dimensions)
-  screenshot = capture_screenshot(...)
-ensure
-  set_viewport(original_viewport) if original_viewport
-end
-```
-
-#### 4. Thread Safety
-
-**Problem:** Parallel screenshots cause race conditions
-
-**Solution:** BiDi protocol handles this naturally - test with threads
-
-```ruby
-threads = (0...3).map do |i|
-  Thread.new { page.screenshot(clip: {...}) }
-end
-screenshots = threads.map(&:value)
-```
-
-### Documentation References
-
-**Essential reading for implementation:**
-
-1. **WebDriver BiDi Spec**: https://w3c.github.io/webdriver-bidi/
-2. **Puppeteer Source**: https://github.com/puppeteer/puppeteer
-3. **Puppeteer BiDi Tests**: https://github.com/puppeteer/puppeteer/tree/main/test/src
-4. **Firefox BiDi Impl**: Check Firefox implementation notes for quirks
-
-**Reference implementation workflow:**
-1. Find corresponding Puppeteer test in `test/src/`
-2. Read TypeScript implementation in `packages/puppeteer-core/src/`
-3. Check BiDi spec for protocol details
-4. Implement Ruby version maintaining same logic
-5. Download golden images and verify pixel-perfect match (with tolerance)
-