puppeteer-ruby 0.45.6 → 0.50.0.alpha5

data/CLAUDE/testing.md

@@ -0,0 +1,278 @@
+# Testing Strategy
+
+This document describes the testing approach for puppeteer-ruby.
+
+## Test Organization
+
+```
+spec/
+├── integration/              # Browser automation tests (type: :puppeteer)
+│   ├── page_spec.rb
+│   ├── element_handle_spec.rb
+│   ├── click_spec.rb
+│   └── ...
+├── puppeteer/                # Unit tests (no browser required)
+│   ├── devices_spec.rb
+│   ├── launcher_spec.rb
+│   └── ...
+├── assets/                   # Test HTML/JS/CSS files
+├── golden_matcher.rb         # Screenshot comparison matcher
+├── spec_helper.rb            # RSpec configuration
+└── utils.rb                  # Test utilities
+```
+
+## Integration Tests
+
+### Basic Structure
+
+Integration tests use `type: :puppeteer` metadata which is automatically applied to files in `spec/integration/`:
+
+```ruby
+RSpec.describe 'Page#goto' do
+  # This file is in spec/integration/, so type: :puppeteer is applied
+
+  it 'navigates to a URL' do
+    page.goto('https://example.com')
+    expect(page.title).to eq('Example Domain')
+  end
+end
+```
+
+### Available Helpers
+
+The `type: :puppeteer` metadata provides these helpers:
+
+| Helper | Description |
+|--------|-------------|
+| `page` | Current `Puppeteer::Page` instance |
+| `browser` | Browser instance (requires `puppeteer: :browser` metadata) |
+| `browser_context` | BrowserContext (requires `browser_context: :incognito`) |
+| `headless?` | Whether running in headless mode |
+| `default_launch_options` | Launch options used for current test |
+
+### Test with Sinatra Server
+
+For tests requiring a web server, use `sinatra: true` metadata:
+
+```ruby
+RSpec.describe 'Page#goto', sinatra: true do
+  it 'navigates to local server' do
+    sinatra.get('/hello') { 'Hello World' }
+
+    page.goto("#{server_prefix}/hello")
+    expect(page.content).to include('Hello World')
+  end
+end
+```
+
+Sinatra helpers:
+
+| Helper | Description |
+|--------|-------------|
+| `sinatra` | Sinatra app instance |
+| `server_prefix` | `http://localhost:4567` |
+| `server_cross_process_prefix` | `http://127.0.0.1:4567` |
+| `server_empty_page` | `http://localhost:4567/empty.html` |
+
+### Test with Browser Instance
+
+For tests that need direct browser access:
+
+```ruby
+RSpec.describe 'Browser', puppeteer: :browser do
+  it 'creates new pages' do
+    page1 = browser.new_page
+    page2 = browser.new_page
+    expect(browser.pages.length).to eq(2)
+  end
+end
+```
+
+### Incognito Context Tests
+
+```ruby
+RSpec.describe 'BrowserContext', browser_context: :incognito do
+  it 'has isolated cookies' do
+    browser_context.set_cookie(name: 'test', value: 'value')
+    # Cookies are isolated to this context
+  end
+end
+```
+
+### OOPIF (Out-of-Process IFrame) Tests
+
+For tests requiring cross-process iframes, use `enable_site_per_process_flag: true`:
+
+```ruby
+it 'clicks button in cross-process iframe', enable_site_per_process_flag: true do
+  with_test_state do |page:, server:, **|
+    page.goto(server.empty_page)
+    # Use cross_process_prefix (127.0.0.1) instead of prefix (localhost)
+    attach_frame(page, 'frame-id', "#{server.cross_process_prefix}/input/button.html")
+
+    frame = page.frames[1]
+    frame.click('button')
+  end
+end
+```
+
+This metadata launches Chrome with `--site-per-process` and `--host-rules=MAP * 127.0.0.1` flags.
+
+## Running Tests
+
+### Basic Commands
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific file
+bundle exec rspec spec/integration/page_spec.rb
+
+# Run specific test by line number
+bundle exec rspec spec/integration/page_spec.rb:42
+
+# Run with documentation format
+bundle exec rspec --format documentation
+```
+
+### Chrome Configuration
+
+```bash
+# Run with custom Chrome path
+PUPPETEER_EXECUTABLE_PATH_RSPEC=/path/to/chrome bundle exec rspec
+
+# Run with Chrome channel
+PUPPETEER_CHANNEL_RSPEC=chrome-beta bundle exec rspec
+```
+
+### Debug Mode
+
+```bash
+# Non-headless mode (see the browser)
+DEBUG=1 bundle exec rspec spec/integration/page_spec.rb
+
+# With debug output
+DEBUG=1 bundle exec rspec spec/integration/page_spec.rb 2>&1 | tee test.log
+```
+
+### Container/CI Mode
+
+```bash
+# Add --no-sandbox flag
+PUPPETEER_NO_SANDBOX_RSPEC=true bundle exec rspec
+```
+
+## Screenshot Testing
+
+### Golden Matcher
+
+Use `match_golden` matcher for screenshot comparisons:
+
+```ruby
+RSpec.describe 'Page#screenshot' do
+  it 'captures page screenshot' do
+    page.goto(server_empty_page)
+    screenshot = page.screenshot
+
+    expect(screenshot).to match_golden('empty-page.png')
+  end
+end
+```
+
+Golden images are stored in `spec/golden/`.
+
+### Updating Golden Images
+
+When intentionally changing visual output:
+
+```bash
+# Remove old golden and re-run test to generate new one
+rm spec/golden/empty-page.png
+bundle exec rspec spec/integration/screenshot_spec.rb
+```
+
+## Writing New Tests
+
+### Guidelines
+
+1. **One assertion per test when possible** - Easier to identify failures
+2. **Use descriptive test names** - Should read like documentation
+3. **Clean up resources** - Close pages, restore state in `after` blocks
+4. **Minimize flakiness** - Use explicit waits, not sleeps
+
+### Example Test Pattern
+
+```ruby
+RSpec.describe 'ElementHandle#click', sinatra: true do
+  before do
+    sinatra.get('/button') do
+      <<~HTML
+        <button onclick="window.clicked = true">Click me</button>
+      HTML
+    end
+    page.goto("#{server_prefix}/button")
+  end
+
+  it 'clicks the button' do
+    button = page.query_selector('button')
+    button.click
+
+    result = page.evaluate('() => window.clicked')
+    expect(result).to eq(true)
+  end
+
+  it 'triggers click event' do
+    events = []
+    page.evaluate(<<~JS)
+      document.querySelector('button').addEventListener('click', () => {
+        window.clickEvent = true;
+      });
+    JS
+
+    page.click('button')
+
+    expect(page.evaluate('() => window.clickEvent')).to eq(true)
+  end
+end
+```
+
+## CI Configuration
+
+Tests run on GitHub Actions with matrix of:
+
+- Ruby versions: 3.2, 3.3, 3.4
+- Environments: Ubuntu with Chrome, Alpine with Chromium
+
+See `.github/workflows/ci.yml` for details.
+
+## Debugging Tips
+
+### See What's Happening
+
+```bash
+# Run with visible browser
+DEBUG=1 bundle exec rspec spec/integration/page_spec.rb
+
+# Add screenshots for debugging
+page.screenshot(path: 'debug.png')
+
+# Log page content
+puts page.content
+```
+
+### Slow Down Execution
+
+```ruby
+# In spec_helper.rb or individual test
+Puppeteer.launch(slow_mo: 100) do |browser|
+  # Actions are slowed by 100ms each
+end
+```
+
+### Inspect CDP Messages
+
+```bash
+# Enable CDP debug logging
+DEBUG=1 bundle exec rspec 2>&1 | grep -E "(SEND|RECV)"
+```

data/CLAUDE.md

@@ -0,0 +1,242 @@
+# Puppeteer-Ruby Development Guide
+
+> **IMPORTANT: Spec Migration Tracking**
+>
+> Test porting from Node.js Puppeteer to Ruby RSpec is tracked in **[CLAUDE/spec_migration_plans.md](./CLAUDE/spec_migration_plans.md)**.
+>
+> - Before porting tests: Check the migration plan for priorities and status
+> - After porting tests: Update the migration plan to reflect progress
+> - This file must be kept up-to-date with all spec migration work
+
+This document provides essential guidance for AI agents working on the puppeteer-ruby codebase.
+
+## Project Overview
+
+puppeteer-ruby is a Ruby port of [Puppeteer](https://pptr.dev/), the Node.js browser automation library. It uses the Chrome DevTools Protocol (CDP) to automate Chrome/Chromium browsers.
+
+### Core Principles
+
+1. **CDP Protocol Focus**: All browser automation is done via CDP
+2. **Chrome Specialization**: Focused on Chrome/Chromium automation
+3. **API Compatibility**: Follow Puppeteer's API design closely, but use Ruby idioms
+
+## Quick Reference
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/integration/page_spec.rb
+
+# Run in debug mode (non-headless)
+DEBUG=1 bundle exec rspec spec/integration/page_spec.rb
+```
+
+> **Note for Codex CLI**: When executing RSpec from Codex CLI, always use `rbenv exec`:
+> ```bash
+> rbenv exec bundle exec rspec spec/integration/click_spec.rb
+> ```
+
+### Key Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PUPPETEER_EXECUTABLE_PATH_RSPEC` | Custom browser executable path |
+| `PUPPETEER_CHANNEL_RSPEC` | Chrome channel (e.g., `chrome`, `chrome-beta`) |
+| `DEBUG` | Set to `1` for debug output |
+| `PUPPETEER_NO_SANDBOX_RSPEC` | Add `--no-sandbox` flag (for containers) |
+
+### Code Quality
+
+```bash
+# Run RuboCop
+bundle exec rubocop
+
+# Auto-fix RuboCop issues
+bundle exec rubocop -a
+
+# Run Steep type check
+bundle exec steep check
+```
+
+## Architecture
+
+The codebase follows a straightforward architecture:
+
+```
+lib/puppeteer/
+├── puppeteer.rb          # Main entry point (Puppeteer.launch, Puppeteer.connect)
+├── browser.rb            # Browser instance management
+├── browser_context.rb    # Incognito/default context
+├── page.rb               # Page API (main user-facing class)
+├── frame.rb              # Frame handling
+├── element_handle.rb     # DOM element operations
+├── js_handle.rb          # JavaScript object handles
+├── connection.rb         # WebSocket connection to browser
+├── cdp_session.rb        # CDP session management
+├── keyboard.rb           # Keyboard input simulation
+├── mouse.rb              # Mouse input simulation
+└── ...
+```
+
+### Key Components
+
+- **Connection**: Manages WebSocket connection to the browser's DevTools
+- **CDPSession**: Sends CDP commands and receives events
+- **FrameManager**: Tracks frames and their execution contexts
+- **NetworkManager**: Handles request interception and network events
+- **LifecycleWatcher**: Waits for navigation events (load, DOMContentLoaded, etc.)
+
+## Code Standards
+
+### Ruby Version & Style
+
+- Minimum Ruby version: 3.2
+- Follow RuboCop rules defined in `.rubocop.yml`
+- Use explicit keyword arguments for public APIs
+
+### API Naming Conventions
+
+JavaScript Puppeteer methods use camelCase, Ruby methods use snake_case:
+
+| Puppeteer (JS) | puppeteer-ruby |
+|----------------|----------------|
+| `page.waitForSelector()` | `page.wait_for_selector` |
+| `page.setContent()` | `page.content=` or `page.set_content` |
+| `element.boundingBox()` | `element.bounding_box` |
+| `browser.newPage()` | `browser.new_page` |
+
+### Error Classes
+
+All custom errors inherit from `Puppeteer::Error`:
+
+```ruby
+module Puppeteer
+  class Error < StandardError; end
+  class TimeoutError < Error; end
+  class FrameNotFoundError < Error; end
+  # etc.
+end
+```
+
+## Testing Strategy
+
+### Test Types
+
+- **Unit tests**: `spec/puppeteer/` - Test individual classes without browser
+- **Integration tests**: `spec/integration/` - Test with real browser
+
+### Integration Test Setup
+
+Integration tests use RSpec metadata:
+
+```ruby
+RSpec.describe 'Page', type: :puppeteer do
+  it 'navigates to a page' do
+    page.goto('https://example.com')
+    expect(page.title).to eq('Example Domain')
+  end
+end
+```
+
+The `type: :puppeteer` metadata automatically:
+- Launches Chrome before each test
+- Provides `page` helper method
+- Closes browser after test
+
+## Porting from Puppeteer
+
+When implementing new features, reference the TypeScript Puppeteer source:
+
+1. Find the corresponding TypeScript file in [puppeteer/puppeteer](https://github.com/puppeteer/puppeteer)
+2. Understand the CDP calls being made
+3. Implement in Ruby following existing patterns
+4. Port the relevant tests
+5. Update `docs/api_coverage.md`
+
+### CDP Command Pattern
+
+```ruby
+# TypeScript Puppeteer
+await this._client.send('Page.navigate', { url });
+
+# Ruby equivalent
+@client.send_message('Page.navigate', url: url)
+```
+
+## Concurrency Model
+
+### Current State (socketry/async)
+
+puppeteer-ruby uses Fiber-based concurrency with `socketry/async` (version 2.35.1+):
+
+- `Async::Promise` - For async operations that complete later
+- `Async` blocks - For running operations in Fiber context
+- `Puppeteer::AsyncUtils.await_promise_all` - For waiting on multiple promises
+- `Puppeteer::AsyncUtils.await_promise_race` - For waiting on any of multiple promises
+- `Puppeteer::ReactorRunner` - Dedicated Async reactor thread for sync API wrapping
+- Standard `Hash` with `Mutex` - For thread-safe callbacks and sessions
+
+### Key Components
+
+| Component | Purpose |
+|-----------|---------|
+| `Async::Promise` | Promise that can be resolved/rejected later |
+| `AsyncUtils.await_promise_all` | Wait for multiple async operations |
+| `AsyncUtils.await_promise_race` | Wait for first of multiple operations |
+| `AsyncUtils.async_timeout` | Timeout wrapper for async operations |
+| `ReactorRunner` | Bridges sync API calls into Async reactor |
+
+### Async Method Pattern
+
+```ruby
+class Page
+  # Synchronous version (blocks until complete)
+  def wait_for_selector(selector, timeout: nil)
+    # ...
+  end
+
+  # Async version (returns Async task)
+  define_async_method :async_wait_for_selector
+end
+```
+
+## Development Workflow
+
+### Before Submitting Changes
+
+1. Run tests: `bundle exec rspec`
+2. Run RuboCop: `bundle exec rubocop`
+3. Run type check: `bundle exec steep check`
+4. Update `docs/api_coverage.md` if adding new API methods
+
+### Pull Request Guidelines
+
+- **Language**: All Pull Requests must be written in English (title, description, and commit messages)
+- **`gh` command**: Available for exploring GitHub issues, codes, or creating pull requests
+- **PR Title**: Use a clear, concise title describing the change
+- **PR Description**: Include a summary of changes and testing done
+
+### Version Updates
+
+When updating the version, **both files must be updated**:
+- `lib/puppeteer/version.rb` - The canonical version constant
+- `docs/api_coverage.md` - The version displayed in documentation
+
+GitHub Actions automatically publishes to RubyGems when a version tag is pushed. Tag format is the version number without `v` prefix (e.g., `0.50.0.alpha3`, not `v0.50.0.alpha3`).
+
+## Detailed Documentation
+
+For in-depth information on specific topics, see the [CLAUDE/](./CLAUDE/) directory:
+
+- [README.md](./CLAUDE/README.md) - Documentation index
+- [architecture.md](./CLAUDE/architecture.md) - Detailed architecture overview
+- [testing.md](./CLAUDE/testing.md) - Testing strategies and patterns
+- [cdp_protocol.md](./CLAUDE/cdp_protocol.md) - CDP protocol details
+- [concurrency.md](./CLAUDE/concurrency.md) - Concurrency patterns
+- [porting_puppeteer.md](./CLAUDE/porting_puppeteer.md) - Guide for porting from TypeScript
+- [rbs_type_checking.md](./CLAUDE/rbs_type_checking.md) - RBS type annotations and Steep type checking
+- [spec_migration_plans.md](./CLAUDE/spec_migration_plans.md) - Test migration tracking and progress

data/README.md

@@ -1,5 +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).
+
 # Puppeteer in Ruby
 
 A Ruby port of [puppeteer](https://pptr.dev/).
@@ -228,6 +232,10 @@ end
 
 https://yusukeiwaki.github.io/puppeteer-ruby-docs/
 
+## Note on Firefox
+
+This library supports **Chrome/Chromium only**. For Firefox automation, consider using [playwright-ruby-client](https://github.com/YusukeIwaki/playwright-ruby-client) or [puppeteer-bidi](https://github.com/YusukeIwaki/puppeteer-bidi).
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/YusukeIwaki/puppeteer-ruby.

data/Rakefile

@@ -1 +1,8 @@
 require 'bundler/gem_tasks'
+
+desc 'Generate RBS files with rbs-inline'
+task :rbs do
+  sh 'bundle', 'exec', 'rbs-inline', '--output=sig', 'lib'
+end
+
+Rake::Task[:build].enhance([:rbs])

data/Steepfile

@@ -0,0 +1,28 @@
+# Steepfile for type checking
+
+target :lib do
+  signature "sig"
+
+  check "lib"
+
+  # Standard library
+  library "base64"
+  library "json"
+  library "net-http"
+  library "uri"
+
+  configure_code_diagnostics do |hash|
+    hash[Steep::Diagnostic::Ruby::UnannotatedEmptyCollection] = :hint
+    hash[Steep::Diagnostic::Ruby::UnknownConstant] = :hint
+    hash[Steep::Diagnostic::Ruby::NoMethod] = :hint
+    hash[Steep::Diagnostic::Ruby::UnresolvedOverloading] = :hint
+    hash[Steep::Diagnostic::Ruby::IncompatibleAssignment] = :hint
+    hash[Steep::Diagnostic::Ruby::ArgumentTypeMismatch] = :hint
+    hash[Steep::Diagnostic::Ruby::ReturnTypeMismatch] = :hint
+    hash[Steep::Diagnostic::Ruby::BlockTypeMismatch] = :hint
+    hash[Steep::Diagnostic::Ruby::BreakTypeMismatch] = :hint
+    hash[Steep::Diagnostic::Ruby::ImplicitBreakValueMismatch] = :hint
+    hash[Steep::Diagnostic::Ruby::UnexpectedBlockGiven] = :hint
+    hash[Steep::Diagnostic::Ruby::UnexpectedPositionalArgument] = :hint
+  end
+end