Puppeteer BiDi Development

Expert guidance for contributing to puppeteer-bidi, a Ruby port of Puppeteer using WebDriver BiDi protocol for standards-based Firefox automation.

Project Context

You are working on puppeteer-bidi, a Ruby implementation of Puppeteer that uses the W3C WebDriver BiDi protocol instead of Chrome DevTools Protocol (CDP). The project enables Firefox automation with a Ruby-idiomatic API.

**Core Principles:**

Architecture Understanding

Two-Layer Architecture

The project has a strict two-layer design pattern:

**Upper Layer (`Puppeteer::Bidi`)**

**Core Layer (`Puppeteer::Bidi::Core`)**

**Critical Rule:** Upper layer methods MUST call `.wait` on Core layer async tasks to convert them to synchronous results.

Async Programming Model

This project uses **Async (Fiber-based)**, NOT concurrent-ruby (Thread-based):

Development Workflow

When implementing new features:

1. **Study Puppeteer TypeScript source** - Understand the original implementation

2. **Identify BiDi protocol calls** - Map CDP calls to BiDi equivalents (skip CDP-only features)

3. **Implement with proper deserialization** - Handle BiDi response formats

4. **Port tests from Puppeteer** - Adapt TypeScript tests to RSpec

5. **Update API_COVERAGE.md** - Mark implemented methods as ✅ and update coverage percentage

6. **Write type annotations** - Use rbs-inline Doc style syntax

7. **Generate and check types** - Run `bundle exec rake rbs && bundle exec steep check`

Testing Guidelines

Running Tests

```bash

All integration tests (requires Firefox Nightly for full BiDi support)

bundle exec rspec spec/integration/

Single test file

bundle exec rspec spec/integration/click_spec.rb

Non-headless mode for debugging

HEADLESS=false bundle exec rspec spec/integration/

Debug BiDi protocol messages

DEBUG_BIDI_COMMAND=1 bundle exec rspec spec/integration/click_spec.rb

Use specific Firefox path (e.g., Nightly)

FIREFOX_PATH="/Applications/Firefox Nightly.app/Contents/MacOS/firefox" bundle exec rspec

```

Test Organization

Documenting Limitations

Use RSpec `pending` vs `skip`:

Type Annotations (rbs-inline)

Use Doc style syntax for type annotations:

```ruby

frozen_string_literal: true

rbs_inline: enabled

class Example

attr_reader :name #: String

# Initialize with a name

# @rbs name: String -- The name to set

# @rbs return: void

def initialize(name)

@name = name

end

# Query for an element matching the selector

# @rbs selector: String -- CSS selector to query

# @rbs return: ElementHandle? -- Matching element or nil

def query_selector(selector)

# ...

end

end

```

**Critical Conventions:**

**Generate RBS:**

```bash

bundle exec rake rbs # Generates sig/**/*.rbs

bundle exec steep check # Type check

```

**Special RBS Files (manually maintained):**

Common Pitfalls

Core Layer Gotchas

Type Checking Issues

Testing Constraints

Key Implementation Patterns

QueryHandler

CSS, XPath, and text selector handling with protocol-level evaluation

JavaScript Evaluation

`evaluate()` and `evaluate_handle()` for running JS in browser context

JSHandle and ElementHandle

Object handle management for remote objects

Mouse and Click

Input simulation including multi-line element clicking with `getClientRects()`

Navigation Waiting

`waitForNavigation` patterns for lifecycle events

ExposeFunction

Expose Ruby functions to page JavaScript using BiDi `script.message`

FileChooser

File upload dialog handling (Nightly-only feature)

Ruby Conventions

References

Consult these resources when implementing features:

Releasing

To release a new version:

1. Update version in `lib/puppeteer/bidi/version.rb`

2. Commit and push to main

3. Create and push version tag:

```bash

git tag 1.2.3

git push origin 1.2.3

```

GitHub Actions automatically publishes to RubyGems. Supported formats: `1.2.3`, `1.2.3.alpha1`, `1.2.3.beta2`

When Contributing