Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
2e81a31
first try
aguspe Mar 26, 2026
69ac7c4
Merge upstream/master resolving conflict by keeping symbolize_keys re…
aguspe Apr 4, 2026
7b5588e
fix conflict
aguspe Jul 1, 2026
961d0c4
Merge branch 'master' into feat/remove-implicit-capabilities-handling
KazuCocoa Jul 14, 2026
023f678
Merge branch 'master' into feat/remove-implicit-capabilities-handling
KazuCocoa Aug 8, 2026
8933e08
Merge branch 'master' into feat/remove-implicit-capabilities-handling
KazuCocoa Oct 4, 2026
0b190af
Merge remote-tracking branch 'origin/master' into feat/remove-implici…
KazuCocoa Nov 15, 2026
1cf618f
feat!: complete migration away from implicit configuration
KazuCocoa Nov 15, 2026
8d5812c
test: preserve underscores in nested Chrome preference keys
KazuCocoa Nov 15, 2026
b3938cc
feat!: remove legacy element references and deprecated helpers
KazuCocoa Nov 15, 2026
744d196
docs: move core 14 migration details to changelog
KazuCocoa Nov 15, 2026
76fa48c
docs: use Selenium implicit waits in migration examples
KazuCocoa Nov 15, 2026
387c537
test: use implicit waits in Android W3C actions
KazuCocoa Nov 15, 2026
59c67a5
feat!: narrow default wait retries to missing elements
KazuCocoa Nov 15, 2026
6ffd066
docs: explain wait behavior compared with Selenium Ruby
KazuCocoa Nov 15, 2026
47e217b
docs: distinguish migration notes from release headers
KazuCocoa Nov 15, 2026
4f2db49
ci: expand Ruby unit test coverage
KazuCocoa Nov 15, 2026
fdacb1a
remove applesimutils
KazuCocoa Nov 15, 2026
653056a
fix: preserve clean element caches and migrate Android waits
KazuCocoa Nov 15, 2026
6fab682
test: use Appium driver waits for Android state changes
KazuCocoa Nov 15, 2026
14f479c
test: fix remaining wait migrations and iOS test assumptions
KazuCocoa Nov 15, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions .github/workflows/functional-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -166,8 +166,6 @@ jobs:
- name: Preparing other environment
run: |
brew install ffmpeg
brew tap wix/brew
brew install applesimutils

# Start Appium
- run: npm root -g
Expand Down
13 changes: 7 additions & 6 deletions .github/workflows/unittest.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,11 @@ jobs:
strategy:
fail-fast: false
matrix:
ruby: [3.1, 3.2, 3.3, 4.0]
ruby: ['3.1', '3.2', '3.3', '3.4', '4.0', ruby-head]

runs-on: ubuntu-latest
# Ruby 3.1 is not available on Ubuntu 26.04.
runs-on: ${{ matrix.ruby == '3.1' && 'ubuntu-24.04' || 'ubuntu-latest' }}
continue-on-error: ${{ matrix.ruby == 'ruby-head' }}

env:
UNIT_TEST: true
Expand All @@ -40,8 +42,7 @@ jobs:
strategy:
fail-fast: false
matrix:
# 4.0 is not available on Win env yet.
ruby: [3.1, 3.2, 3.3]
ruby: ['3.1', '3.2', '3.3', '3.4', '4.0']

runs-on: windows-latest

Expand All @@ -63,8 +64,8 @@ jobs:
run: |
bundle exec rake test:unit

setx APPIUM_DRIVER espresso
$env:APPIUM_DRIVER = 'espresso'
bundle exec rake test:unit:android

setx APPIUM_DRIVER appium
$env:APPIUM_DRIVER = 'appium'
bundle exec rake test:unit
115 changes: 115 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,121 @@
All notable changes to this project will be documented in this file.
New entries are generated by Release Please. Historical commit-level details through 13.1.0 remain in `release_notes.md`.

### Migration from v13 to v14

These changes are unreleased and planned for version 14.0.0.

Version 14 removes `Appium.symbolize_keys`, the `appium_lib[:wait]` option,
`Appium::Core::Options#default_wait`, `Appium::Core::Driver#default_wait`, and
`Appium::Core::Driver#set_implicit_wait_by_default`.

#### Waiting for elements

`appium_lib: { wait: 30 }` no longer configures an implicit wait; the option is
ignored. Starting a driver no longer sends an implicit-timeout command. Set the
implicit wait through Selenium after session creation:

```ruby
core = Appium::Core.for(
capabilities: { platformName: 'Android', automationName: 'UiAutomator2' }
)
driver = core.start_driver
driver.manage.timeouts.implicit_wait = 30 # seconds
button = driver.find_element(:accessibility_id, 'Continue')
button.click
```

Element lookup now waits up to 30 seconds for the element to appear.
`wait_timeout` controls `core.wait` / `core.wait_true`; it does not configure
implicit waits for ordinary `find_element` calls.

Keep any application-specific default wait in your own configuration instead of
reading `core.default_wait`. Explicit Selenium timeout configuration remains supported.

#### Exceptions retried by wait helpers

`wait` / `wait_until` and `wait_true` / `wait_until_true` now retry only
`Selenium::WebDriver::Error::NoSuchElementError` by default. Previously they
caught `Exception`, including programming errors and process interruption.
Other exceptions, including `NoMethodError`, `Interrupt`, and `SystemExit`, now
propagate immediately by default. This also applies to `Appium::Core::Wait.until`
and `.until_true`.

If a condition needs to retry other transient errors, pass their classes through
`ignored:`. This option replaces the default list, so include `NoSuchElementError`
explicitly if it should still be retried. For example, use
`ignored: [Selenium::WebDriver::Error::NoSuchElementError, Selenium::WebDriver::Error::StaleElementReferenceError]`.
Use `ignored: []` to disable exception retries. Connection refusal still propagates
immediately, even when included in `ignored:`.

`wait` still succeeds when the block returns without raising, even for `false` or
`nil`; `wait_true` still waits for a truthy result. Implicit waits configured through
`driver.manage.timeouts.implicit_wait` are unaffected.

The default retry policy now matches
[`Selenium::WebDriver::Wait`](https://www.selenium.dev/selenium/docs/api/rb/Selenium/WebDriver/Wait.html)
(verified with Selenium Ruby 4.21.0 and 4.52.0). The existing Appium API retains
these differences:

| Behavior | Selenium Ruby | Appium Ruby core |
| --- | --- | --- |
| Exception option | `ignore:` | `ignored:` |
| Explicit exception list | Replaces the default list | Replaces the default list |
| Success condition | `until` requires a truthy result | `wait_true` requires a truthy result; `wait` accepts any result without an exception |
| Connection refusal (`Errno::ECONNREFUSED`) | Can be retried when explicitly included in `ignore:` | Always propagates immediately, even when included in `ignored:` |

This change aligns the default exception policy without renaming Appium's options
or changing its wait success conditions. The minimum Selenium version remains 4.21.0.

#### Hash keys

Callers using `Appium.symbolize_keys` must replace that call. Prefer defining
client option keys as symbols (`:capabilities`, `:appium_lib`, `:server_url`, etc.).
For a hash whose top-level keys are all strings or symbols, Ruby provides
`options.transform_keys(&:to_sym)`. This is a shallow conversion; normalize nested
client options separately if needed. Capability string/symbol names are still
preserved when serialized; this change does not introduce camelCase conversion.

#### Element location and screenshots

`Element#location_rel(driver)` has been removed. Use `element.rect` for the
position and size. If you need the element center relative to the window,
calculate numeric ratios explicitly:

```ruby
rect = element.rect
window = driver.window_size
relative_x = (rect.x + rect.width / 2.0) / window.width
relative_y = (rect.y + rect.height / 2.0) / window.height
```

The old method returned strings such as `"60.0 / 375.0"`, not numeric ratios.

Replace `driver.take_element_screenshot(element, path)` with
`driver.save_element_screenshot(element, path)`. Only the compatibility alias
has been removed; element screenshot support remains available.

#### W3C element responses and actions

For Appium 4, element responses must use the W3C
`element-6066-11e4-a52e-4f735466cecf` key. The legacy JSONWP/MJSONWP `ELEMENT`
key is no longer interpreted as an element reference, including in script results.
Update custom drivers, plugins, and test fixtures that still return legacy references.
W3C noncompact element responses still preserve cached attributes.

The bridge's unused positional argument to `action` has been removed. Use
`driver.action(async: true)` instead of passing a positional boolean.

#### Using appium_lib, appium_console, or appium_capybara

The current `appium_lib` dependency constraint excludes core 14, and its driver
still calls the removed `symbolize_keys` and `default_wait` APIs. Keep that upper
bound until a compatible `appium_lib` release adapts those call sites, its wait
helpers, and its use of the removed `take_element_screenshot` alias. Do not simply
relax the core version constraint. Applications using
`appium_console` or `appium_capybara` through `appium_lib` should upgrade with that
compatible release. Direct users of `appium_lib_core` can migrate as described above.

## [13.2.1](https://github.com/appium/ruby_lib_core/compare/v13.2.0...v13.2.1) (2026-10-27)


Expand Down
20 changes: 16 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,20 @@ This library wraps [selenium-webdriver](https://github.com/SeleniumHQ/selenium/w
- Appium 2.0
- https://appium.github.io/appium/docs/en/2.0/ (Not completed yet)

# Migration from v13 to v14

Version 14 removes automatic implicit-wait configuration, `Appium.symbolize_keys`,
`Element#location_rel`, the `take_element_screenshot` alias, the bridge's positional
`action` argument, and legacy JSONWP/MJSONWP element references. Configure implicit
waits through Selenium and use
`element.rect`, `save_element_screenshot`, keyword action arguments, and W3C references.

Wait helpers now retry only `NoSuchElementError` by default; other exceptions
propagate unless explicitly listed in `ignored:`.

See [Migration from v13 to v14](CHANGELOG.md#migration-from-v13-to-v14) in
[CHANGELOG](CHANGELOG.md) for replacement examples and downstream compatibility notes.

# Migration from v4 to v5

Please read [`[5.0.0]`](CHANGELOG.md#500---2021-11-05) section in [CHANGELOG](CHANGELOG.md)
Expand Down Expand Up @@ -118,16 +132,14 @@ $ IGNORE_VERSION_SKIP=true CI=true bundle exec rake test:func:android
deviceName: 'iPhone 17',
# app: '/path/to/MyiOS.app', # Without 'app' capability, an appium session starts with the home screen
automationName: 'XCUITest'
},
appium_lib: {
wait: 30
}
}
@core = Appium::Core.for(opts) # create a core driver with `opts`
@driver = @core.start_driver
@driver.manage.timeouts.implicit_wait = 30 # seconds

# Launch iPhone Simulator and `MyiOS.app`
@driver.find_element(:accessibility_id, 'some accessibility') # find an element
@driver.find_element(:accessibility_id, 'some accessibility') # wait up to 30 seconds for an element
```
- Run the script
```bash
Expand Down
37 changes: 0 additions & 37 deletions lib/appium_lib_core.rb
Original file line number Diff line number Diff line change
Expand Up @@ -22,43 +22,6 @@
require_relative 'appium_lib_core/support/event_firing_bridge'

module Appium
# convert the top level keys to symbols.
#
# @param [Hash] hash Hash value to make symbolise
#
# @example
#
# opts = Appium.symbolize_keys(opts)
#
def self.symbolize_keys(hash, nested: false, enable_deprecation_msg: true)
# FIXME: As https://github.com/appium/ruby_lib/issues/945, we must remove this implicit string to symbol.
# But appium_lib_core's some capability handling expect to be symbol, so we should test to remove
# the methods which expect the symbol first.
raise ::Appium::Core::Error::ArgumentError, 'symbolize_keys requires a hash' unless hash.is_a? Hash

hash.each_with_object({}) do |pair, acc| # steep:ignore
key = begin
if enable_deprecation_msg && !(pair[0].is_a? Symbol)
::Appium::Logger.warn("[Deprecation] The key '#{pair[0]}' must be a symbol while currently it " \
"is #{pair[0].class.name}. Please define the key as a Symbol. " \
'Converting it to Symbol for now.')
end

pair[0].to_sym
rescue StandardError => e
::Appium::Logger.warn(e.message)
pair[0]
end

value = pair[1]
acc[key] = if nested
value.is_a?(Hash) ? symbolize_keys(value, nested: false, enable_deprecation_msg: false) : value
else
value
end
end
end

module Core
# @see Appium::Core::Driver.for
def self.for(opts = {})
Expand Down
2 changes: 1 addition & 1 deletion lib/appium_lib_core/common/base/bidi_bridge.rb
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ class BiDiBridge < ::Appium::Core::Base::Bridge
# webSocketUrl: true,
# },
# appium_lib: {
# wait: 30
# wait_timeout: 30
# }
# }
# core = ::Appium::Core.for(caps)
Expand Down
8 changes: 4 additions & 4 deletions lib/appium_lib_core/common/base/bridge.rb
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ def attach_to(session_id, platform_name, automation_name)
# useNewWDA: true,
# },
# appium_lib: {
# wait: 30
# wait_timeout: 30
# }
# }
# core = ::Appium::Core.for(caps)
Expand Down Expand Up @@ -152,7 +152,7 @@ def add_appium_prefix(capabilities)
# Selenium calls this immediately before constructing an element. Keep nil for
# non-element hashes so ordinary script results and shadow roots stay intact.
def element_id_from(response)
response if super
response if response[::Appium::Core::Element::ELEMENT_KEY]
end

def selenium_bridge_accepts_url?
Expand Down Expand Up @@ -211,7 +211,7 @@ def status
# element = @driver.find_element(:id, "some id")
# @driver.action.click(element).perform # The 'click' is a part of 'PointerActions'
#
def action(_deprecated_async = nil, async: false, devices: nil)
def action(async: false, devices: nil)
# steep:ignore:start
::Selenium::WebDriver::ActionBuilder.new(
self,
Expand All @@ -222,7 +222,7 @@ def action(_deprecated_async = nil, async: false, devices: nil)
# steep:ignore:end
end

# Port from MJSONWP
# W3C Get Timeouts
def get_timeouts
execute :get_timeouts
end
Expand Down
6 changes: 3 additions & 3 deletions lib/appium_lib_core/common/base/capabilities.rb
Original file line number Diff line number Diff line change
Expand Up @@ -24,14 +24,14 @@ class Capabilities < ::Selenium::WebDriver::Remote::Capabilities
# standard options like chrome and firefox etc. So, the implementation should differ from
# other browsers. But here should inherit `Options` to follow Selenium.

# Method override
# FIXME: when we drop "symbolize_keys", this can be removed.
# Override Selenium's convert_key to prevent camelCase conversion.
# Appium capability names should be preserved as-is (e.g., :some_capability stays "some_capability",
# not converted to "someCapability" as Selenium's default would do).
def convert_key(key)
case key
when String
key.to_s
when Symbol
# here do not convert to camel case
key.to_s
else
raise ::Appium::Core::Error::ArgumentError, "expected String or Symbol, got #{key.inspect}:#{key.class}"
Expand Down
2 changes: 1 addition & 1 deletion lib/appium_lib_core/common/base/driver.rb
Original file line number Diff line number Diff line change
Expand Up @@ -1022,7 +1022,7 @@ def execute_driver(script: '', type: 'webdriverio', timeout_ms: nil)
# @return [::Appium::Core::Element]
#
# @example
# response = {"element-6066-11e4-a52e-4f735466cecf"=>"xxxx", "ELEMENT"=>"xxxx"}
# response = {"element-6066-11e4-a52e-4f735466cecf"=>"xxxx"}
# ele = @driver.convert_to_element(response) #=> ::Appium::Core::Element
# ele.rect #=> Can get the rect of the element
#
Expand Down
2 changes: 0 additions & 2 deletions lib/appium_lib_core/common/base/screenshot.rb
Original file line number Diff line number Diff line change
Expand Up @@ -68,8 +68,6 @@ def save_element_screenshot(element, png_path)
end
File.open(png_path, 'wb') { |f| f << element_screenshot_as(element, :png) }
end
# backward compatibility
alias take_element_screenshot save_element_screenshot

#
# Return a PNG screenshot in the given format as a string
Expand Down
4 changes: 1 addition & 3 deletions lib/appium_lib_core/common/command.rb
Original file line number Diff line number Diff line change
Expand Up @@ -148,11 +148,9 @@ module Commands
upload_file: [:post, 'session/:session_id/se/file'],

###
# Used by Appium, but no in W3C
# Additional WebDriver and Appium commands
###

# ::Appium::Core::Base::Commands::OSS has the following commands and Appium also use them.
# Delegated to ::Appium::Core::Base::Commands::OSS commands
is_element_displayed: [:get, 'session/:session_id/element/:id/displayed'], # hint: https://w3c.github.io/webdriver/#element-displayedness

get_timeouts: [:get, 'session/:session_id/timeouts'], # https://w3c.github.io/webdriver/#get-timeouts
Expand Down
12 changes: 6 additions & 6 deletions lib/appium_lib_core/common/wait.rb
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ class << self
# @param [Integer] timeout Seconds to wait before timing out. Set default by +appium_wait_timeout+ (30).
# @param [Integer] interval Seconds to sleep between polls. Set default by +appium_wait_interval+ (0.5).
# @param [String] message Exception message if timed out.
# @param [Array, Exception] ignored Exceptions to ignore while polling (default: Exception)
# @param [Array<Class>, Class] ignored Exception classes to retry (default: Selenium::WebDriver::Error::NoSuchElementError)
# @param [Object, NilClass] object Object to evaluate block against
#
# @example
Expand All @@ -45,7 +45,7 @@ class << self
# }
#
def until(timeout: DEFAULT_TIMEOUT, interval: DEFAULT_INTERVAL, message: nil, ignored: nil, object: nil)
ignored = Array(ignored || ::Exception)
ignored = Array(ignored || ::Selenium::WebDriver::Error::NoSuchElementError)

last_error = nil
timer = Wait::Timer.new(timeout)
Expand Down Expand Up @@ -79,7 +79,7 @@ def until(timeout: DEFAULT_TIMEOUT, interval: DEFAULT_INTERVAL, message: nil, ig
# @param [Integer] timeout Seconds to wait before timing out. Set default by +appium_wait_timeout+ (30).
# @param [Integer] interval Seconds to sleep between polls. Set default by +appium_wait_interval+ (0.5).
# @param [String] message Exception message if timed out.
# @param [Array, Exception] ignored Exceptions to ignore while polling (default: Exception)
# @param [Array<Class>, Class] ignored Exception classes to retry (default: Selenium::WebDriver::Error::NoSuchElementError)
# @param [Object, NilClass] object Object to evaluate block against
#
# @example
Expand All @@ -93,7 +93,7 @@ def until(timeout: DEFAULT_TIMEOUT, interval: DEFAULT_INTERVAL, message: nil, ig
# }
#
def until_true(timeout: DEFAULT_TIMEOUT, interval: DEFAULT_INTERVAL, message: nil, ignored: nil, object: nil)
ignored = Array(ignored || ::Exception)
ignored = Array(ignored || ::Selenium::WebDriver::Error::NoSuchElementError)

last_error = nil
timer = Wait::Timer.new(timeout)
Expand Down Expand Up @@ -139,7 +139,7 @@ module Waitable
# @param [Integer] timeout Seconds to wait before timing out. Set default by +appium_wait_timeout+ (30).
# @param [Integer] interval Seconds to sleep between polls. Set default by +appium_wait_interval+ (0.5).
# @param [String] message Exception message if timed out.
# @param [Array, Exception] ignored Exceptions to ignore while polling (default: Exception)
# @param [Array<Class>, Class] ignored Exception classes to retry (default: Selenium::WebDriver::Error::NoSuchElementError)
#
# @example With core instance
#
Expand Down Expand Up @@ -175,7 +175,7 @@ def wait_until_true(timeout: nil, interval: nil, message: nil, ignored: nil, &bl
# @param [Integer] timeout Seconds to wait before timing out. Set default by +appium_wait_timeout+ (30).
# @param [Integer] interval Seconds to sleep between polls. Set default by +appium_wait_interval+ (0.5).
# @param [String] message Exception message if timed out.
# @param [Array, Exception] ignored Exceptions to ignore while polling (default: Exception)
# @param [Array<Class>, Class] ignored Exception classes to retry (default: Selenium::WebDriver::Error::NoSuchElementError)
#
# @example With core instance
#
Expand Down
Loading
Loading