Expert guidance for developing and contributing to puppeteer-bidi, a Ruby port of Puppeteer using WebDriver BiDi protocol for Firefox automation. Covers architecture, async patterns, testing, and porting guidelines.
Expert guidance for contributing to puppeteer-bidi, a Ruby port of Puppeteer using WebDriver BiDi protocol for standards-based Firefox automation.
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:**
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.
This project uses **Async (Fiber-based)**, NOT concurrent-ruby (Thread-based):
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`
```bash
bundle exec rspec spec/integration/
bundle exec rspec spec/integration/click_spec.rb
HEADLESS=false bundle exec rspec spec/integration/
DEBUG_BIDI_COMMAND=1 bundle exec rspec spec/integration/click_spec.rb
FIREFOX_PATH="/Applications/Firefox Nightly.app/Contents/MacOS/firefox" bundle exec rspec
```
Use RSpec `pending` vs `skip`:
Use Doc style syntax for type annotations:
```ruby
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):**
CSS, XPath, and text selector handling with protocol-level evaluation
`evaluate()` and `evaluate_handle()` for running JS in browser context
Object handle management for remote objects
Input simulation including multi-line element clicking with `getClientRects()`
`waitForNavigation` patterns for lifecycle events
Expose Ruby functions to page JavaScript using BiDi `script.message`
File upload dialog handling (Nightly-only feature)
Consult these resources when implementing features:
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`
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/puppeteer-bidi-development/raw