AGENTS.md

1<!-- Guidance for AI agents working in Selenium Ruby Bindings -->
2 
3## Code location
4- Library: `rb/lib/selenium/webdriver`
5- Tests: `rb/spec/unit/` and `rb/spec/integration/`
6- Type signatures: `rb/sig/`
7 
8## Common commands
9- Build: `bazel build //rb/...`
10 
11## Testing
12See `rb/TESTING.md`
13 
14## Code conventions
15 
16### Logging
17```ruby
18WebDriver.logger.warn("actionable: something needs attention", id: :warning_id)
19WebDriver.logger.info("useful: driver started successfully")
20WebDriver.logger.debug("diagnostic: request details for debugging")
21```
22 
23### Deprecation
24```ruby
25WebDriver.logger.deprecate(
26  'OldClass#old_method',
27  'NewClass#new_method',
28  id: :old_method
29)
30```
31 
32### Internal APIs
33Mark internal APIs with `@api private` in YARD comments:
34```ruby
35# @api private
36def internal_method
37end
38```
39 
40### Type signatures (steep/rbs)
41When changing public API, update corresponding `.rbs` files in `rb/sig/`
42 
43### Documentation
44Use YARD for public APIs:
45```ruby
46# Brief description.
47#
48# @param name [Type] description
49# @return [Type] description
50# @raise [ErrorClass] when condition
51```
52 
53## Integration test guards
54 
55Integration specs are guarded by RSpec metadata on `describe`/`context`/`it` (all enclosing
56guards combine). Use one of these five, and always include a `reason:`:
57 
58- `skip_if:` — skip when config matches
59- `skip_unless:` — run only when config matches
60- `pending_if:` — expect failure when config matches
61- `pending_unless:` — expect failure unless config matches
62- `flaky:` — `skip_if` reserved for unreliable/intermittent tests
63 
64Matching within one Hash = AND (every pair must match); an Array value within a key = OR (matches any
65listed value). An Array of Hashes lists configs matched independently, and the combined effect depends
66on the guard direction: for `skip_if`/`pending_if` the guard triggers if **any** Hash matches (OR); for
67`skip_unless`/`pending_unless` the example is kept only where **all** Hashes match (i.e. it is
68skipped/pended if any does not). The `reason:` is a String or an issue number. Conditions (`browser`,
69`driver`, `platform`, `ci`, etc.) are registered in
70[`spec_helper.rb`](spec/integration/selenium/webdriver/spec_helper.rb).
71 
72```ruby
73skip_if: {browser: %i[chrome edge], headless: true, reason: '...'}                   # headless Chrome or Edge
74pending_if: [{browser: :firefox, reason: 1234}, {platform: :macosx, reason: 5678}]   # Firefox OR macOS
75skip_unless: [{bidi: false, reason: '...'}, {driver: :remote, reason: '...'}]        # only when non-bidi AND remote
76```
77