rb/AGENTS.md

<!-- Guidance for AI agents working in Selenium Ruby Bindings -->

## Code location
- Library: `rb/lib/selenium/webdriver`
- Tests: `rb/spec/unit/` and `rb/spec/integration/`
- Type signatures: `rb/sig/`

## Common commands
- Build: `bazel build //rb/...`

## Testing
See `rb/TESTING.md`

## Code conventions

### Logging
```ruby
WebDriver.logger.warn("actionable: something needs attention", id: :warning_id)
WebDriver.logger.info("useful: driver started successfully")
WebDriver.logger.debug("diagnostic: request details for debugging")
```

### Deprecation
```ruby
WebDriver.logger.deprecate(
  'OldClass#old_method',
  'NewClass#new_method',
  id: :old_method
)
```

### Internal APIs
Mark internal APIs with `@api private` in YARD comments:
```ruby
# @api private
def internal_method
end
```

### Type signatures (steep/rbs)
When changing public API, update corresponding `.rbs` files in `rb/sig/`

### Documentation
Use YARD for public APIs:
```ruby
# Brief description.
#
# @param name [Type] description
# @return [Type] description
# @raise [ErrorClass] when condition
```

## Integration test guards

Integration specs are guarded by RSpec metadata on `describe`/`context`/`it` (all enclosing
guards combine). Use one of these five, and always include a `reason:`:

- `skip_if:` — skip when config matches
- `skip_unless:` — run only when config matches
- `pending_if:` — expect failure when config matches
- `pending_unless:` — expect failure unless config matches
- `flaky:` — `skip_if` reserved for unreliable/intermittent tests

Matching within one Hash = AND (every pair must match); an Array value within a key = OR (matches any
listed value). An Array of Hashes lists configs matched independently, and the combined effect depends
on the guard direction: for `skip_if`/`pending_if` the guard triggers if **any** Hash matches (OR); for
`skip_unless`/`pending_unless` the example is kept only where **all** Hashes match (i.e. it is
skipped/pended if any does not). The `reason:` is a String or an issue number. Conditions (`browser`,
`driver`, `platform`, `ci`, etc.) are registered in
[`spec_helper.rb`](spec/integration/selenium/webdriver/spec_helper.rb).

```ruby
skip_if: {browser: %i[chrome edge], headless: true, reason: '...'}                   # headless Chrome or Edge
pending_if: [{browser: :firefox, reason: 1234}, {platform: :macosx, reason: 5678}]   # Firefox OR macOS
skip_unless: [{bidi: false, reason: '...'}, {driver: :remote, reason: '...'}]        # only when non-bidi AND remote
```