From 2e81a31ef601fc6ce149626481bd03da06821bb2 Mon Sep 17 00:00:00 2001
From: Augustin Gottlieb <33221555+aguspe@users.noreply.github.com>
Date: Thu, 26 Mar 2026 10:10:47 +0100
Subject: [PATCH 01/15] first try
---
lib/appium_lib_core.rb | 37 -------------
.../common/base/capabilities.rb | 6 +--
lib/appium_lib_core/driver.rb | 28 +---------
sig/lib/appium_lib_core.rbs | 3 --
sig/lib/appium_lib_core/driver.rbs | 10 ----
.../android/webdriver/device_test.rb | 2 +-
.../android/webdriver/w3c_actions_test.rb | 2 +-
test/test_helper.rb | 46 ----------------
test/unit/appium_lib_core_test.rb | 44 ----------------
test/unit/driver_test.rb | 52 -------------------
10 files changed, 6 insertions(+), 224 deletions(-)
diff --git a/lib/appium_lib_core.rb b/lib/appium_lib_core.rb
index 77e8ce27..4a4220d5 100644
--- a/lib/appium_lib_core.rb
+++ b/lib/appium_lib_core.rb
@@ -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|
- 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 = {})
diff --git a/lib/appium_lib_core/common/base/capabilities.rb b/lib/appium_lib_core/common/base/capabilities.rb
index 7683769c..e7f26bba 100644
--- a/lib/appium_lib_core/common/base/capabilities.rb
+++ b/lib/appium_lib_core/common/base/capabilities.rb
@@ -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}"
diff --git a/lib/appium_lib_core/driver.rb b/lib/appium_lib_core/driver.rb
index 165d687a..439db1ba 100644
--- a/lib/appium_lib_core/driver.rb
+++ b/lib/appium_lib_core/driver.rb
@@ -36,13 +36,12 @@ module Ios
# This options affects only client side as :appium_lib key.
# Read {::Appium::Core::Driver} about each attribute
class Options
- attr_reader :custom_url, :default_wait,
+ attr_reader :custom_url,
:port, :wait_timeout, :wait_interval, :listener,
:direct_connect, :enable_idempotency_header
def initialize(appium_lib_opts)
@custom_url = appium_lib_opts.fetch :server_url, nil
- @default_wait = appium_lib_opts.fetch :wait, nil
@enable_idempotency_header = appium_lib_opts.fetch :enable_idempotency_header, true
@direct_connect = appium_lib_opts.fetch :direct_connect, true
@@ -133,11 +132,6 @@ class Driver
# @return [String]
attr_reader :custom_url
- # Default wait time for elements to appear in Appium server side.
- # Provide { appium_lib: { wait: 30 } } to {::Appium::Core.for}
- # @return [Integer]
- attr_reader :default_wait
-
# Appium's server port. 4723 is by default. Defaults to {::Appium::Core::Driver::DEFAULT_APPIUM_PORT}.
# Provide { appium_lib: { port: 8080 } } to {::Appium::Core.for}.
# :custom_url is prior than :port if :custom_url is set.
@@ -213,7 +207,6 @@ class Driver
# },
# appium_lib: {
# port: 8080,
- # wait: 0,
# wait_timeout: 20,
# wait_interval: 0.3,
# listener: nil,
@@ -234,7 +227,6 @@ class Driver
# },
# appium_lib: {
# server_url: 'http://custom-host:8080/wd/hub',
- # wait: 0,
# wait_timeout: 20,
# wait_interval: 0.3,
# listener: nil,
@@ -254,7 +246,6 @@ class Driver
# app: '/path/to/MyiOS.app'
# },
# appium_lib: {
- # wait: 0,
# wait_timeout: 20,
# wait_interval: 0.3,
# listener: nil,
@@ -376,7 +367,6 @@ def setup_for_new_session(opts = {})
# app: '/path/to/MyiOS.app'
# },
# appium_lib: {
- # wait: 20,
# wait_timeout: 20,
# wait_interval: 0.3,
# }
@@ -430,8 +420,6 @@ def start_driver(server_url: nil,
@http_client.delete_additional_header Appium::Core::Base::Http::RequestHeaders::KEYS[:idempotency]
end
- set_implicit_wait_by_default(@default_wait)
-
@driver
end
@@ -478,18 +466,6 @@ def get_http_client(http_client: nil, open_timeout: nil, read_timeout: nil)
http_client || Appium::Core::Base::Http::Default.new(open_timeout: open_timeout, read_timeout: read_timeout)
end
- # Ignore setting default wait if the target driver has no implementation
- def set_implicit_wait_by_default(wait)
- return if @default_wait.nil?
-
- @driver.manage.timeouts.implicit_wait = wait
- rescue ::Selenium::WebDriver::Error::UnknownError => e
- raise ::Appium::Core::Error::ServerError, e.message unless e.message.include?('The operation requested is not yet implemented')
-
- ::Appium::Logger.debug(e.message)
- {}
- end
-
# Returns the server's version info. This method calls +driver.remote_status+ internally
#
# @return [Hash]
@@ -652,8 +628,6 @@ def set_appium_lib_specific_values(appium_lib_opts)
@custom_url ||= opts.custom_url # Keep existence capability if it's already provided
@enable_idempotency_header = opts.enable_idempotency_header
- @default_wait = opts.default_wait
-
@port = opts.port
@wait_timeout = opts.wait_timeout
diff --git a/sig/lib/appium_lib_core.rbs b/sig/lib/appium_lib_core.rbs
index 7e9a4bbe..284ca4f3 100644
--- a/sig/lib/appium_lib_core.rbs
+++ b/sig/lib/appium_lib_core.rbs
@@ -1,7 +1,4 @@
module Appium
- def self.symbolize_keys: (Hash[untyped, untyped] hash, ?nested: bool, ?enable_deprecation_msg: bool)
- -> Hash[Symbol, untyped]
-
module Core
def self.for: (Hash[Symbol, untyped] opts) -> Driver
end
diff --git a/sig/lib/appium_lib_core/driver.rbs b/sig/lib/appium_lib_core/driver.rbs
index 894b0e00..9575c1fb 100644
--- a/sig/lib/appium_lib_core/driver.rbs
+++ b/sig/lib/appium_lib_core/driver.rbs
@@ -20,8 +20,6 @@ module Appium
class Options
@custom_url: String
- @default_wait: Integer
-
@enable_idempotency_header: bool
@direct_connect: bool
@@ -36,8 +34,6 @@ module Appium
attr_reader custom_url: String
- attr_reader default_wait: Integer
-
attr_reader port: Integer
attr_reader wait_timeout: Integer
@@ -98,8 +94,6 @@ module Appium
@enable_idempotency_header: bool
- @default_wait: Integer
-
@port: Integer
@wait_timeout: Integer
@@ -124,8 +118,6 @@ module Appium
attr_reader custom_url: String
- attr_reader default_wait: Integer
-
attr_reader port: Integer
DEFAULT_APPIUM_PORT: Integer
@@ -167,8 +159,6 @@ module Appium
def get_http_client: (?http_client: untyped?, ?open_timeout: untyped?, ?read_timeout: untyped?) -> untyped
- def set_implicit_wait_by_default: (untyped wait) -> untyped
-
def appium_server_version: () -> Hash[String, String]
private
diff --git a/test/functional/android/webdriver/device_test.rb b/test/functional/android/webdriver/device_test.rb
index 6d7faa22..f75858f4 100644
--- a/test/functional/android/webdriver/device_test.rb
+++ b/test/functional/android/webdriver/device_test.rb
@@ -117,7 +117,7 @@ def test_dismiss_alert
def test_implicit_wait
# checking no method error
- assert(@driver.manage.timeouts.implicit_wait = @@core.default_wait)
+ assert(@driver.manage.timeouts.implicit_wait = 0)
end
# Not so stable on CI
diff --git a/test/functional/android/webdriver/w3c_actions_test.rb b/test/functional/android/webdriver/w3c_actions_test.rb
index 40afec64..6c3a21db 100644
--- a/test/functional/android/webdriver/w3c_actions_test.rb
+++ b/test/functional/android/webdriver/w3c_actions_test.rb
@@ -60,7 +60,7 @@ def test_tap_scroll
@driver.find_element(:accessibility_id, 'Custom')
end
end
- @driver.manage.timeouts.implicit_wait = @@core.default_wait
+ @driver.manage.timeouts.implicit_wait = 0
end
def test_double_tap
diff --git a/test/test_helper.rb b/test/test_helper.rb
index b21ef360..1194ece8 100644
--- a/test/test_helper.rb
+++ b/test/test_helper.rb
@@ -353,7 +353,6 @@ def android(activity_name = nil)
uiautomator2ServerLaunchTimeout: 60_000 # ms
},
appium_lib: {
- wait: 5,
wait_timeout: 20,
wait_interval: 1
}
@@ -381,7 +380,6 @@ def android_direct
{
capabilities: android[:capabilities],
appium_lib: {
- wait: 30,
wait_timeout: 20,
wait_interval: 1,
direct_connect: true
@@ -497,10 +495,6 @@ def android_mock_create_session_w3c
stub_request(:post, 'http://127.0.0.1:4723/session')
.to_return(headers: HEADER, status: 200, body: response)
- stub_request(:post, "#{SESSION}/timeouts")
- .with(body: { implicit: 5_000 }.to_json)
- .to_return(headers: HEADER, status: 200, body: { value: nil }.to_json)
-
driver = @core.start_driver
assert_equal ::Appium::Core::Base::Driver, driver.class
assert_equal ::Appium::Core::Base::Bridge, driver.bridge.class
@@ -516,24 +510,6 @@ def android_mock_create_session_w3c
},
times: 1
)
-
- assert_requested(
- :post,
- "#{SESSION}/timeouts",
- headers: {
- 'Content-Type' => 'application/json; charset=UTF-8',
- 'User-Agent' => /appium\/ruby_lib_core\/.+/
- },
- body: { implicit: 5_000 }.to_json,
- times: 1
- )
- assert_not_requested(
- :post,
- "#{SESSION}/timeouts",
- headers: { 'X-Idempotency-Key' => /.+/ },
- body: { implicit: 5_000 }.to_json,
- times: 1
- )
driver
end
@@ -554,10 +530,6 @@ def android_chrome_mock_create_session_w3c
stub_request(:post, 'http://127.0.0.1:4723/session')
.to_return(headers: HEADER, status: 200, body: response)
- stub_request(:post, "#{SESSION}/timeouts")
- .with(body: { implicit: 5_000 }.to_json)
- .to_return(headers: HEADER, status: 200, body: { value: nil }.to_json)
-
driver = @core.start_driver
assert_equal({}, driver.send(:bridge).http.additional_headers)
@@ -571,24 +543,6 @@ def android_chrome_mock_create_session_w3c
},
times: 1
)
-
- assert_requested(
- :post,
- "#{SESSION}/timeouts",
- headers: {
- 'Content-Type' => 'application/json; charset=UTF-8',
- 'User-Agent' => /appium\/ruby_lib_core\/.+/
- },
- body: { implicit: 5_000 }.to_json,
- times: 1
- )
- assert_not_requested(
- :post,
- "#{SESSION}/timeouts",
- headers: { 'X-Idempotency-Key' => /.+/ },
- body: { implicit: 5_000 }.to_json,
- times: 1
- )
driver
end
diff --git a/test/unit/appium_lib_core_test.rb b/test/unit/appium_lib_core_test.rb
index 264352f9..380e5b93 100644
--- a/test/unit/appium_lib_core_test.rb
+++ b/test/unit/appium_lib_core_test.rb
@@ -20,50 +20,6 @@ def test_version
assert !::Appium::Core::VERSION.nil?
end
- # TODO: Should be removed in the future
- def test_symbolize_keys
- result = ::Appium.symbolize_keys({ 'a' => 1, b: 2 })
- assert_equal({ a: 1, b: 2 }, result)
- end
-
- def test_not_symbolize_keys_nested1
- result = ::Appium.symbolize_keys(
- { 'caps': { 'automationName' => 'xcuitest', platformName: :ios } }, nested: true
- )
- assert_equal({ caps: { automationName: 'xcuitest', platformName: :ios } }, result)
- end
-
- def test_not_symbolize_keys_nested2
- result = ::Appium.symbolize_keys(
- { 'caps': { 'automationName' => 'xcuitest', platformName: :ios, other_caps: { 'something1': 1, something2: 2 } } },
- nested: true
- )
- assert_equal(
- { caps: { automationName: 'xcuitest', platformName: :ios, other_caps: { 'something1': 1, something2: 2 } } },
- result
- )
- end
-
- def test_not_symbolize_keys_nested3
- result = ::Appium.symbolize_keys(
- { 'caps': { 'automationName' => 'xcuitest', platformName: :ios, other_caps: { 'something1': 1, something2: 2 } } },
- nested: false
- )
- assert_equal(
- { caps: { 'automationName' => 'xcuitest', platformName: :ios, other_caps: { 'something1': 1, something2: 2 } } },
- result
- )
- end
-
- # TODO: Should be removed in the future
- def test_symbolize_keys_raise_argument_error
- e = assert_raises ::Appium::Core::Error::ArgumentError do
- ::Appium.symbolize_keys('no hash value')
- end
-
- assert_equal 'symbolize_keys requires a hash', e.message
- end
-
def test_core_instance_variables
opts = {
url: 'http://custom-host:8080/wd/hub/path',
diff --git a/test/unit/driver_test.rb b/test/unit/driver_test.rb
index c0e7ee0c..985fd9b1 100644
--- a/test/unit/driver_test.rb
+++ b/test/unit/driver_test.rb
@@ -112,10 +112,6 @@ def test_verify_appium_core_base_capabilities_create_capabilities_with_caps_stri
assert_equal 'test/functional/app/UIKitCatalog-iphonesimulator.zip', caps['appium:app']
end
- def test_default_wait
- assert_equal 5, @core.default_wait
- end
-
def test_default_timeout_for_http_client
driver = android_mock_create_session
@@ -159,15 +155,9 @@ def test_default_timeout_for_http_client_with_direct
stub_request(:post, 'http://127.0.0.1:4723/session')
.to_return(headers: HEADER, status: 200, body: response)
- stub_request(:post, 'http://localhost:8888/wd/hub/session/1234567890/timeouts')
- .with(body: { implicit: 30_000 }.to_json)
- .to_return(headers: HEADER, status: 200, body: { value: nil }.to_json)
-
driver = core.start_driver
assert_requested(:post, 'http://127.0.0.1:4723/session', times: 1)
- assert_requested(:post, 'http://localhost:8888/wd/hub/session/1234567890/timeouts',
- body: { implicit: 30_000 }.to_json, times: 1)
driver
end
@@ -209,15 +199,9 @@ def test_default_timeout_for_http_client_with_direct_appium_prefix
stub_request(:post, 'http://127.0.0.1:4723/session')
.to_return(headers: HEADER, status: 200, body: response)
- stub_request(:post, 'http://localhost:8888/wd/hub/session/1234567890/timeouts')
- .with(body: { implicit: 30_000 }.to_json)
- .to_return(headers: HEADER, status: 200, body: { value: nil }.to_json)
-
driver = core.start_driver
assert_requested(:post, 'http://127.0.0.1:4723/session', times: 1)
- assert_requested(:post, 'http://localhost:8888/wd/hub/session/1234567890/timeouts',
- body: { implicit: 30_000 }.to_json, times: 1)
driver
end
@@ -263,15 +247,9 @@ def test_default_timeout_for_http_client_with_direct_appium_prefix_prior_than_no
stub_request(:post, 'http://127.0.0.1:4723/session')
.to_return(headers: HEADER, status: 200, body: response)
- stub_request(:post, 'http://localhost:8888/wd/hub/session/1234567890/timeouts')
- .with(body: { implicit: 30_000 }.to_json)
- .to_return(headers: HEADER, status: 200, body: { value: nil }.to_json)
-
driver = core.start_driver
assert_requested(:post, 'http://127.0.0.1:4723/session', times: 1)
- assert_requested(:post, 'http://localhost:8888/wd/hub/session/1234567890/timeouts',
- body: { implicit: 30_000 }.to_json, times: 1)
driver
end
@@ -312,15 +290,9 @@ def test_default_timeout_for_http_client_with_direct_no_path
stub_request(:post, 'http://127.0.0.1:4723/session')
.to_return(headers: HEADER, status: 200, body: response)
- stub_request(:post, 'http://127.0.0.1:4723/session/1234567890/timeouts')
- .with(body: { implicit: 30_000 }.to_json)
- .to_return(headers: HEADER, status: 200, body: { value: nil }.to_json)
-
driver = core.start_driver
assert_requested(:post, 'http://127.0.0.1:4723/session', times: 1)
- assert_requested(:post, 'http://127.0.0.1:4723/session/1234567890/timeouts',
- body: { implicit: 30_000 }.to_json, times: 1)
driver
end
@@ -362,15 +334,9 @@ def test_default_timeout_for_http_client_with_direct_no_supported_client
stub_request(:post, 'http://127.0.0.1:4723/session')
.to_return(headers: HEADER, status: 200, body: response)
- stub_request(:post, 'http://127.0.0.1:4723/session/1234567890/timeouts')
- .with(body: { implicit: 30_000 }.to_json)
- .to_return(headers: HEADER, status: 200, body: { value: nil }.to_json)
-
driver = core.start_driver http_client_ops: { http_client: Selenium::WebDriver::Remote::Http::Default.new }
assert_requested(:post, 'http://127.0.0.1:4723/session', times: 1)
- assert_requested(:post, 'http://127.0.0.1:4723/session/1234567890/timeouts',
- body: { implicit: 30_000 }.to_json, times: 1)
driver
end
@@ -408,15 +374,9 @@ def _android_mock_create_session_w3c(core)
stub_request(:post, 'http://127.0.0.1:4723/session')
.to_return(headers: HEADER, status: 200, body: response)
- stub_request(:post, 'http://127.0.0.1:4723/session/1234567890/timeouts')
- .with(body: { implicit: 5_000 }.to_json)
- .to_return(headers: HEADER, status: 200, body: { value: nil }.to_json)
-
driver = core.start_driver
assert_requested(:post, 'http://127.0.0.1:4723/session', times: 1)
- assert_requested(:post, 'http://127.0.0.1:4723/session/1234567890/timeouts',
- body: { implicit: 5_000 }.to_json, times: 1)
driver
end
@@ -452,15 +412,9 @@ def _android_mock_create_session_w3c_with_custom_http_client(core)
stub_request(:post, 'http://127.0.0.1:4723/session')
.to_return(headers: HEADER, status: 200, body: response)
- stub_request(:post, 'http://127.0.0.1:4723/session/1234567890/timeouts')
- .with(body: { implicit: 5_000 }.to_json)
- .to_return(headers: HEADER, status: 200, body: { value: nil }.to_json)
-
driver = core.start_driver http_client_ops: { http_client: Selenium::WebDriver::Remote::Http::Default.new }
assert_requested(:post, 'http://127.0.0.1:4723/session', times: 1)
- assert_requested(:post, 'http://127.0.0.1:4723/session/1234567890/timeouts',
- body: { implicit: 5_000 }.to_json, times: 1)
driver
end
@@ -527,15 +481,9 @@ def test_attach_to_an_existing_session
stub_request(:post, 'http://127.0.0.1:4723/session')
.to_return(headers: HEADER, status: 200, body: response)
- stub_request(:post, 'http://localhost:8888/wd/hub/session/1234567890/timeouts')
- .with(body: { implicit: 30_000 }.to_json)
- .to_return(headers: HEADER, status: 200, body: { value: nil }.to_json)
-
driver = core.start_driver
assert_requested(:post, 'http://127.0.0.1:4723/session', times: 1)
- assert_requested(:post, 'http://localhost:8888/wd/hub/session/1234567890/timeouts',
- body: { implicit: 30_000 }.to_json, times: 1)
driver
end
From 1cf618feaae57d4d44888e82b674a144db9af58e Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 12:45:51 -0800
Subject: [PATCH 02/15] feat!: complete migration away from implicit
configuration
BREAKING CHANGE: remove Appium.symbolize_keys and automatic implicit waits configured through appium_lib[:wait]. Use explicit waits and migrate downstream callers before upgrading to core 14.
---
README.md | 58 ++++++++++++++++++-
.../common/base/bidi_bridge.rb | 2 +-
lib/appium_lib_core/common/base/bridge.rb | 2 +-
.../appium_lib_core/common/base/bridge.rbs | 2 +-
.../android/webdriver/w3c_actions_test.rb | 2 +-
test/unit/driver_test.rb | 17 ++++++
6 files changed, 77 insertions(+), 6 deletions(-)
diff --git a/README.md b/README.md
index 61b16914..2a79f8e3 100644
--- a/README.md
+++ b/README.md
@@ -120,14 +120,14 @@ $ IGNORE_VERSION_SKIP=true CI=true bundle exec rake test:func:android
automationName: 'XCUITest'
},
appium_lib: {
- wait: 30
+ wait_timeout: 30
}
}
@core = Appium::Core.for(opts) # create a core driver with `opts`
@driver = @core.start_driver
# Launch iPhone Simulator and `MyiOS.app`
- @driver.find_element(:accessibility_id, 'some accessibility') # find an element
+ @core.wait { @driver.find_element(:accessibility_id, 'some accessibility') } # wait for an element
```
- Run the script
```bash
@@ -243,3 +243,57 @@ Publishing. See [RELEASING.md](RELEASING.md) for setup, version overrides, and r
# License
Apache License v2
+
+## Migrating to 14.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. Prefer
+an explicit wait around operations that need to wait for the app:
+
+```ruby
+core = Appium::Core.for(
+ capabilities: { platformName: 'Android', automationName: 'UiAutomator2' },
+ appium_lib: { wait_timeout: 30, wait_interval: 0.5 }
+)
+driver = core.start_driver
+button = core.wait { driver.find_element(:accessibility_id, 'Continue') }
+button.click
+```
+
+`wait_timeout` controls `core.wait` / `core.wait_true`; it does not make ordinary
+`find_element` calls wait. If your application needs an implicit wait, set it
+explicitly after session creation:
+
+```ruby
+driver.manage.timeouts.implicit_wait = 30 # seconds
+```
+
+Keep any application-specific default wait in your own configuration instead of
+reading `core.default_wait`. Explicit Selenium timeout configuration remains supported.
+
+### 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.
+
+### 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 both call sites and its wait
+helpers. 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.
+
+The breaking-change commit is intended to make Release Please prepare 14.0.0.
+Version, date, manifest, and changelog updates belong in that generated release PR.
diff --git a/lib/appium_lib_core/common/base/bidi_bridge.rb b/lib/appium_lib_core/common/base/bidi_bridge.rb
index 09291194..e397ef46 100644
--- a/lib/appium_lib_core/common/base/bidi_bridge.rb
+++ b/lib/appium_lib_core/common/base/bidi_bridge.rb
@@ -39,7 +39,7 @@ class BiDiBridge < ::Appium::Core::Base::Bridge
# webSocketUrl: true,
# },
# appium_lib: {
- # wait: 30
+ # wait_timeout: 30
# }
# }
# core = ::Appium::Core.for(caps)
diff --git a/lib/appium_lib_core/common/base/bridge.rb b/lib/appium_lib_core/common/base/bridge.rb
index 72c2951e..7cc98d2c 100644
--- a/lib/appium_lib_core/common/base/bridge.rb
+++ b/lib/appium_lib_core/common/base/bridge.rb
@@ -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)
diff --git a/sig/lib/appium_lib_core/common/base/bridge.rbs b/sig/lib/appium_lib_core/common/base/bridge.rbs
index ec013f9a..5516f659 100644
--- a/sig/lib/appium_lib_core/common/base/bridge.rbs
+++ b/sig/lib/appium_lib_core/common/base/bridge.rbs
@@ -88,7 +88,7 @@ module Appium
# useNewWDA: true,
# },
# appium_lib: {
- # wait: 30
+ # wait_timeout: 30
# }
# }
# core = ::Appium::Core.for(caps)
diff --git a/test/functional/android/webdriver/w3c_actions_test.rb b/test/functional/android/webdriver/w3c_actions_test.rb
index 6c3a21db..92729f38 100644
--- a/test/functional/android/webdriver/w3c_actions_test.rb
+++ b/test/functional/android/webdriver/w3c_actions_test.rb
@@ -72,7 +72,7 @@ def test_double_tap
el = @@core.wait { @driver.find_element(:accessibility_id, 'Buttons') }
@driver.action.click(el).perform
- el = @driver.find_element(:id, 'io.appium.android.apis:id/button_toggle')
+ el = @@core.wait { @driver.find_element(:id, 'io.appium.android.apis:id/button_toggle') }
assert_equal 'OFF', el.text
@driver.action.click(el).perform
diff --git a/test/unit/driver_test.rb b/test/unit/driver_test.rb
index 9d7f42eb..159799fc 100644
--- a/test/unit/driver_test.rb
+++ b/test/unit/driver_test.rb
@@ -113,6 +113,23 @@ def test_verify_appium_core_base_capabilities_create_capabilities_with_caps_stri
assert_equal 'test/functional/app/UIKitCatalog-iphonesimulator.zip', caps['appium:app']
end
+ def test_removed_wait_option_does_not_set_session_timeout
+ opts = Caps.android
+ opts[:appium_lib][:wait] = 30
+ @core = ::Appium::Core.for(opts)
+ driver = android_mock_create_session_w3c
+
+ assert_not_requested(:post, "#{SESSION}/timeouts")
+
+ stub_request(:post, "#{SESSION}/timeouts")
+ .with(body: { implicit: 30_000 }.to_json)
+ .to_return(headers: HEADER, status: 200, body: { value: nil }.to_json)
+
+ driver.manage.timeouts.implicit_wait = 30
+
+ assert_requested(:post, "#{SESSION}/timeouts", body: { implicit: 30_000 }.to_json, times: 1)
+ end
+
def test_default_timeout_for_http_client
driver = android_mock_create_session
From 8d5812c9196cae236df0debbcc1b5e757efd3745 Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 12:50:34 -0800
Subject: [PATCH 03/15] test: preserve underscores in nested Chrome preference
keys
---
test/unit/common_test.rb | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git a/test/unit/common_test.rb b/test/unit/common_test.rb
index 44021374..59ff9995 100644
--- a/test/unit/common_test.rb
+++ b/test/unit/common_test.rb
@@ -208,6 +208,21 @@ def test_add_appium_prefix_already_have_appium_prefix
assert_equal expected, caps_with_appium.as_json
end
+ def test_chrome_preferences_preserve_underscores_in_symbol_keys
+ # ChromeDriver expects download.default_directory, not download.defaultDirectory.
+ # convert_key must preserve nested Symbol keys when serializing capabilities.
+ caps = Appium::Core::Base::Capabilities.new(
+ chromeOptions: { prefs: { 'download.default_directory': '/tmp/downloads' } }
+ )
+
+ serialized = JSON.parse(@bridge.add_appium_prefix(caps).to_json)
+
+ assert_equal(
+ { 'appium:chromeOptions' => { 'prefs' => { 'download.default_directory' => '/tmp/downloads' } } },
+ serialized
+ )
+ end
+
def test_add_appium_prefix_has_no_parameter
cap = {}
base_caps = Appium::Core::Base::Capabilities.new cap
From b3938cceb5be70d3879c20bfa92747d183f7f7ef Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 12:55:34 -0800
Subject: [PATCH 04/15] feat!: remove legacy element references and deprecated
helpers
---
README.md | 34 ++++++++++++++++-
lib/appium_lib_core/common/base/bridge.rb | 6 +--
lib/appium_lib_core/common/base/driver.rb | 2 +-
lib/appium_lib_core/common/base/screenshot.rb | 2 -
lib/appium_lib_core/common/command.rb | 4 +-
lib/appium_lib_core/element.rb | 33 ++---------------
.../appium_lib_core/common/base/bridge.rbs | 4 +-
.../common/base/screenshot.rbs | 2 -
sig/lib/appium_lib_core/element.rbs | 2 -
.../android/android/device_data_test.rb | 8 ++--
test/functional/android/patch_test.rb | 8 ----
test/functional/ios/patch_test.rb | 19 ----------
test/unit/android/device/w3c/commands_test.rb | 4 +-
.../android/device/w3c/screenshot_test.rb | 8 ++--
.../android/webdriver/w3c/actions_test.rb | 5 +++
.../android/webdriver/w3c/commands_test.rb | 4 +-
test/unit/common/element_cache_test.rb | 37 +++++++++++++++----
test/unit/common/element_test.rb | 19 ----------
test/unit/driver_test.rb | 2 +-
19 files changed, 91 insertions(+), 112 deletions(-)
diff --git a/README.md b/README.md
index 2a79f8e3..b1dad92e 100644
--- a/README.md
+++ b/README.md
@@ -286,12 +286,42 @@ For a hash whose top-level keys are all strings or symbols, Ruby provides
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 both call sites and its wait
-helpers. Do not simply relax the core version constraint. Applications using
+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.
diff --git a/lib/appium_lib_core/common/base/bridge.rb b/lib/appium_lib_core/common/base/bridge.rb
index 7cc98d2c..7cd8b339 100644
--- a/lib/appium_lib_core/common/base/bridge.rb
+++ b/lib/appium_lib_core/common/base/bridge.rb
@@ -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?
@@ -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,
@@ -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
diff --git a/lib/appium_lib_core/common/base/driver.rb b/lib/appium_lib_core/common/base/driver.rb
index ab452746..8e3561d8 100644
--- a/lib/appium_lib_core/common/base/driver.rb
+++ b/lib/appium_lib_core/common/base/driver.rb
@@ -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
#
diff --git a/lib/appium_lib_core/common/base/screenshot.rb b/lib/appium_lib_core/common/base/screenshot.rb
index 370f1135..4305fbf8 100644
--- a/lib/appium_lib_core/common/base/screenshot.rb
+++ b/lib/appium_lib_core/common/base/screenshot.rb
@@ -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
diff --git a/lib/appium_lib_core/common/command.rb b/lib/appium_lib_core/common/command.rb
index d978c8bc..054df955 100644
--- a/lib/appium_lib_core/common/command.rb
+++ b/lib/appium_lib_core/common/command.rb
@@ -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
diff --git a/lib/appium_lib_core/element.rb b/lib/appium_lib_core/element.rb
index 15fbaf6a..724ca3a7 100644
--- a/lib/appium_lib_core/element.rb
+++ b/lib/appium_lib_core/element.rb
@@ -115,9 +115,11 @@ def attribute_key(name)
def initialize(bridge, id, cached = nil)
if id.is_a?(Hash)
# Preserve any extra attributes included in the element response.
- cached = Cache.new(id.except('ELEMENT', ELEMENT_KEY))
- id = id['ELEMENT'] || id[ELEMENT_KEY]
+ cached = Cache.new(id.except(ELEMENT_KEY))
+ id = id[ELEMENT_KEY]
end
+ raise ::Selenium::WebDriver::Error::WebDriverError, 'Missing W3C element ID in response' if id.nil?
+
super(bridge, id)
@cached = cached
end
@@ -165,33 +167,6 @@ def respond_to_missing?(_method_name, _include_private = false)
# Alias for type
alias type send_keys
- # @deprecated Please use `Element#rect` instead to get location information.
- #
- # For use with location_rel.
- #
- # @return [Struct(:x, :y)] the relative x, y in a struct in string.
- #
- # @example
- #
- # e = @driver.find_element :accessibility_id, 'something'
- # e.location_rel @driver
- #
- def location_rel(driver)
- rect = self.rect
- location_x = rect.x.to_f
- location_y = rect.y.to_f
-
- size_width = rect.width.to_f
- size_height = rect.height.to_f
-
- center_x = location_x + (size_width / 2.0)
- center_y = location_y + (size_height / 2.0)
-
- w = driver.window_size
- point = Struct.new(:x, :y)
- point.new("#{center_x} / #{w.width.to_f}", "#{center_y} / #{w.height.to_f}")
- end
-
# Return an element screenshot as base64
#
# @return String Base 64 encoded string
diff --git a/sig/lib/appium_lib_core/common/base/bridge.rbs b/sig/lib/appium_lib_core/common/base/bridge.rbs
index 5516f659..66fb0584 100644
--- a/sig/lib/appium_lib_core/common/base/bridge.rbs
+++ b/sig/lib/appium_lib_core/common/base/bridge.rbs
@@ -139,9 +139,9 @@ module Appium
# element = @driver.find_element(:id, "some id")
# @driver.action.click(element).perform # The 'click' is a part of 'PointerActions'
#
- def action: (?untyped? _deprecated_async, ?async: bool, ?devices: untyped?) -> untyped
+ def action: (?async: bool, ?devices: untyped?) -> untyped
- # Port from MJSONWP
+ # W3C Get Timeouts
def get_timeouts: () -> untyped
# For Appium
diff --git a/sig/lib/appium_lib_core/common/base/screenshot.rbs b/sig/lib/appium_lib_core/common/base/screenshot.rbs
index d5d43aa7..b81e6ae2 100644
--- a/sig/lib/appium_lib_core/common/base/screenshot.rbs
+++ b/sig/lib/appium_lib_core/common/base/screenshot.rbs
@@ -10,8 +10,6 @@ module Appium
def save_element_screenshot: (untyped element, untyped png_path) -> untyped
- alias take_element_screenshot save_element_screenshot
-
def element_screenshot_as: (untyped element, untyped format) -> untyped
def save_viewport_screenshot: (untyped png_path) -> untyped
diff --git a/sig/lib/appium_lib_core/element.rbs b/sig/lib/appium_lib_core/element.rbs
index aa170b6e..7b10ae49 100644
--- a/sig/lib/appium_lib_core/element.rbs
+++ b/sig/lib/appium_lib_core/element.rbs
@@ -43,8 +43,6 @@ module Appium
# Alias for type
alias type send_keys
- def location_rel: (untyped driver) -> untyped
-
def screenshot: () -> untyped
def screenshot_as: (untyped format) -> untyped
diff --git a/test/functional/android/android/device_data_test.rb b/test/functional/android/android/device_data_test.rb
index 720ef589..7a06ee8b 100644
--- a/test/functional/android/android/device_data_test.rb
+++ b/test/functional/android/android/device_data_test.rb
@@ -74,13 +74,13 @@ def test_performance_related
data_type: 'cpuinfo')
end
- def test_take_element_screenshot
+ def test_save_element_screenshot
e = @driver.wait { |d| d.find_element :accessibility_id, 'App' }
- @driver.take_element_screenshot(e, 'take_element_screenshot.png')
+ @driver.save_element_screenshot(e, 'save_element_screenshot.png')
- assert File.exist? 'take_element_screenshot.png'
+ assert File.exist? 'save_element_screenshot.png'
- File.delete 'take_element_screenshot.png'
+ File.delete 'save_element_screenshot.png'
end
def test_viewport_screenshot
diff --git a/test/functional/android/patch_test.rb b/test/functional/android/patch_test.rb
index a68db369..54ac25fc 100644
--- a/test/functional/android/patch_test.rb
+++ b/test/functional/android/patch_test.rb
@@ -46,14 +46,6 @@ def test_type
text = @@core.wait { @driver.find_element :id, 'io.appium.android.apis:id/left_text_edit' }
assert_equal 'Left is bestPökémön', text.text
end
-
- def test_location_rel
- e = @@core.wait { @driver.find_element :accessibility_id, 'App' }
- location = e.location_rel @driver
-
- assert_match %r{\A[0-9]+\.[0-9]+ \/ [0-9]+\.[0-9]+\z}, location.x
- assert_match %r{\A[0-9]+\.[0-9]+ \/ [0-9]+\.[0-9]+\z}, location.y
- end
end
end
# rubocop:enable Style/ClassVars
diff --git a/test/functional/ios/patch_test.rb b/test/functional/ios/patch_test.rb
index e916e182..b5d11b56 100644
--- a/test/functional/ios/patch_test.rb
+++ b/test/functional/ios/patch_test.rb
@@ -49,25 +49,6 @@ def test_type
@@driver.back
end
-
- def test_location_rel
- e = @@core.wait { @@driver.find_element :accessibility_id, 'Date Picker' }
- location = e.location_rel @@driver
-
- expected_x, expected_y = if over_ios17?(@@driver)
- # iPhone 17
- ['64.0 / 402.0', '263.5 / 874.0']
- elsif over_ios14?(@@driver)
- # iPhone 11
- ['64.0 / 414.0', '239.5 / 896.0']
- else
- # iPhone 11
- ['64.0 / 414.0', '235.5 / 896.0']
- end
-
- assert_equal expected_x, location.x, "Expected X is #{expected_x}, actual is #{location.x}"
- assert_equal expected_y, location.y, "Expected y is #{expected_y}, actual is #{location.y}"
- end
end
end
# rubocop:enable Style/ClassVars
diff --git a/test/unit/android/device/w3c/commands_test.rb b/test/unit/android/device/w3c/commands_test.rb
index 0b496b16..8ad0c364 100644
--- a/test/unit/android/device/w3c/commands_test.rb
+++ b/test/unit/android/device/w3c/commands_test.rb
@@ -383,11 +383,11 @@ def test_get_battery_info
def test_search_element_child_element
stub_request(:post, "#{SESSION}/element")
.with(body: { using: 'id', value: 'example' }.to_json)
- .to_return(headers: HEADER, status: 200, body: { value: { ELEMENT: 'element_id_parent' },
+ .to_return(headers: HEADER, status: 200, body: { value: { ::Appium::Core::Element::ELEMENT_KEY => 'element_id_parent' },
sessionId: SESSION, status: 0 }.to_json)
stub_request(:post, "#{SESSION}/element/element_id_parent/element")
.with(body: { using: 'id', value: 'example2' }.to_json)
- .to_return(headers: HEADER, status: 200, body: { value: { ELEMENT: 'element_id_children' },
+ .to_return(headers: HEADER, status: 200, body: { value: { ::Appium::Core::Element::ELEMENT_KEY => 'element_id_children' },
sessionId: SESSION, status: 0 }.to_json)
@driver.find_element(:id, 'example').find_element(:id, 'example2')
diff --git a/test/unit/android/device/w3c/screenshot_test.rb b/test/unit/android/device/w3c/screenshot_test.rb
index 106e25d4..0e797b9d 100644
--- a/test/unit/android/device/w3c/screenshot_test.rb
+++ b/test/unit/android/device/w3c/screenshot_test.rb
@@ -64,20 +64,20 @@ def test_screenshot_as_raise_error
end
end
- def test_take_element_screenshot
+ def test_save_element_screenshot
stub_request(:get, "#{SESSION}/element/id/screenshot")
.to_return(headers: HEADER, status: 200, body: { value: '' }.to_json)
- @driver.take_element_screenshot ::Appium::Core::Element.new(@driver.send(:bridge), 'id'), 'sample.png'
+ @driver.save_element_screenshot ::Appium::Core::Element.new(@driver.send(:bridge), 'id'), 'sample.png'
assert_requested(:get, "#{SESSION}/element/id/screenshot", times: 1)
end
- def test_take_element_screenshot_wrong_ext
+ def test_save_element_screenshot_wrong_ext
stub_request(:get, "#{SESSION}/element/id/screenshot")
.to_return(headers: HEADER, status: 200, body: { value: '' }.to_json)
- @driver.take_element_screenshot ::Appium::Core::Element.new(@driver.send(:bridge), 'id'), 'sample.jpg'
+ @driver.save_element_screenshot ::Appium::Core::Element.new(@driver.send(:bridge), 'id'), 'sample.jpg'
assert_requested(:get, "#{SESSION}/element/id/screenshot", times: 1)
end
diff --git a/test/unit/android/webdriver/w3c/actions_test.rb b/test/unit/android/webdriver/w3c/actions_test.rb
index b27f5ae1..da95da05 100644
--- a/test/unit/android/webdriver/w3c/actions_test.rb
+++ b/test/unit/android/webdriver/w3c/actions_test.rb
@@ -28,6 +28,11 @@ def setup
@driver ||= android_mock_create_session_w3c
end
+ def test_action_requires_keyword_arguments
+ assert_raises(ArgumentError) { @driver.bridge.action(true) }
+ assert_instance_of Selenium::WebDriver::ActionBuilder, @driver.action(async: true)
+ end
+
def test_w3c_actions
action_body = {
actions: [{
diff --git a/test/unit/android/webdriver/w3c/commands_test.rb b/test/unit/android/webdriver/w3c/commands_test.rb
index df77fd9c..54a7b042 100644
--- a/test/unit/android/webdriver/w3c/commands_test.rb
+++ b/test/unit/android/webdriver/w3c/commands_test.rb
@@ -234,9 +234,9 @@ def test_orientation
def test_active_element
stub_request(:get, "#{SESSION}/element/active")
- .to_return(headers: HEADER, status: 200, body: { value: 'xxxx' }.to_json)
+ .to_return(headers: HEADER, status: 200, body: { value: { ::Appium::Core::Element::ELEMENT_KEY => 'xxxx' } }.to_json)
- @driver.switch_to.active_element
+ assert_equal 'xxxx', @driver.switch_to.active_element.id
assert_requested(:get, "#{SESSION}/element/active", times: 1)
end
diff --git a/test/unit/common/element_cache_test.rb b/test/unit/common/element_cache_test.rb
index ea076c33..cfb10e3c 100644
--- a/test/unit/common/element_cache_test.rb
+++ b/test/unit/common/element_cache_test.rb
@@ -78,13 +78,36 @@ def test_listener
assert_requested(:post, "#{SESSION}/element/id/click", times: 1)
end
- def test_compact_and_legacy
- [Appium::Core::Element::ELEMENT_KEY, 'ELEMENT'].each do |key|
- stub_value(:post, '/element', { key => 'id' })
- e = @driver.find_element(id: 'example')
- assert_equal 'id', e.id
- assert_empty e.cached.attributes
- end
+ def test_compact
+ stub_value(:post, '/element', { Appium::Core::Element::ELEMENT_KEY => 'id' })
+ e = @driver.find_element(id: 'example')
+ assert_equal 'id', e.id
+ assert_empty e.cached.attributes
+ end
+
+ def test_legacy_element_response_is_rejected
+ legacy = { 'ELEMENT' => 'legacy-id' }
+ stub_value(:post, '/element', legacy)
+ error = assert_raises(Selenium::WebDriver::Error::WebDriverError) { @driver.find_element(id: 'example') }
+ assert_match(/Missing W3C element ID/, error.message)
+ assert_raises(Selenium::WebDriver::Error::WebDriverError) { @driver.convert_to_element(legacy) }
+ assert_raises(Selenium::WebDriver::Error::WebDriverError) { Appium::Core::Element.new(@driver.bridge, legacy) }
+ end
+
+ def test_script_hash_with_legacy_key_remains_a_hash
+ value = { 'ELEMENT' => 'ordinary-data', 'nested' => [response] }
+ stub_value(:post, '/execute/sync', value)
+ result = @driver.execute_script('return results')
+ assert_instance_of Hash, result
+ assert_equal 'ordinary-data', result['ELEMENT']
+ assert_equal 'id', result['nested'].first.id
+ assert_equal 'original', result['nested'].first.cached.text
+ end
+
+ def test_w3c_element_id_takes_precedence
+ element = @driver.convert_to_element(response.merge('ELEMENT' => 'legacy-id'))
+ assert_equal 'id', element.id
+ assert_equal 'original', element.cached.text
end
def test_standard_boolean_fields_match_element_api
diff --git a/test/unit/common/element_test.rb b/test/unit/common/element_test.rb
index 4ec0030f..8f60914f 100644
--- a/test/unit/common/element_test.rb
+++ b/test/unit/common/element_test.rb
@@ -35,25 +35,6 @@ def test_method_missing
assert_requested(:get, "#{SESSION}/element/id/attribute/content-desc", times: 1)
end
- def test_location_rel
- stub_request(:get, "#{SESSION}/element/id/rect")
- .to_return(headers: HEADER, status: 200, body: { value: {
- x: '10', y: '10', width: '100', height: '200'
- } }.to_json)
- stub_request(:get, "#{SESSION}/window/rect")
- .to_return(headers: HEADER, status: 200, body: { value: {
- x: '0', y: '0', width: '375', height: '667'
- } }.to_json)
-
- e = ::Appium::Core::Element.new(@driver.send(:bridge), 'id')
- location = e.location_rel @driver
-
- assert_requested(:get, "#{SESSION}/element/id/rect", times: 1)
- assert_requested(:get, "#{SESSION}/window/rect", times: 1)
- assert_equal '60.0 / 375.0', location.x
- assert_equal '110.0 / 667.0', location.y
- end
-
def test_element_screenshot_as
stub_request(:get, "#{SESSION}/element/id/screenshot")
.to_return(headers: HEADER, status: 200,
diff --git a/test/unit/driver_test.rb b/test/unit/driver_test.rb
index 159799fc..6110e7c3 100644
--- a/test/unit/driver_test.rb
+++ b/test/unit/driver_test.rb
@@ -874,7 +874,7 @@ def test_elements
def test_convert_element
driver = android_mock_create_session
- response = { 'element-6066-11e4-a52e-4f735466cecf' => 'test-element-id', 'ELEMENT' => 'test-element-id' }
+ response = { 'element-6066-11e4-a52e-4f735466cecf' => 'test-element-id' }
e = driver.convert_to_element response
assert_equal 'test-element-id', e.id
assert_equal ::Appium::Core::Element, e.class
From 744d1961080b1559a3561ecb45ab9e3a34809ee3 Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 13:12:26 -0800
Subject: [PATCH 05/15] docs: move core 14 migration details to changelog
---
CHANGELOG.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++
README.md | 94 ++++++----------------------------------------------
2 files changed, 94 insertions(+), 84 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a083f254..f9bab37c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,90 @@
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`.
+## Unreleased
+
+### Migration from v13 to v14
+
+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. Prefer
+an explicit wait around operations that need to wait for the app:
+
+```ruby
+core = Appium::Core.for(
+ capabilities: { platformName: 'Android', automationName: 'UiAutomator2' },
+ appium_lib: { wait_timeout: 30, wait_interval: 0.5 }
+)
+driver = core.start_driver
+button = core.wait { driver.find_element(:accessibility_id, 'Continue') }
+button.click
+```
+
+`wait_timeout` controls `core.wait` / `core.wait_true`; it does not make ordinary
+`find_element` calls wait. If your application needs an implicit wait, set it
+explicitly after session creation:
+
+```ruby
+driver.manage.timeouts.implicit_wait = 30 # seconds
+```
+
+Keep any application-specific default wait in your own configuration instead of
+reading `core.default_wait`. Explicit Selenium timeout configuration remains supported.
+
+#### 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)
diff --git a/README.md b/README.md
index b1dad92e..ff364a48 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,16 @@ 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. Use explicit waits,
+`element.rect`, `save_element_screenshot`, keyword action arguments, and W3C references.
+
+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)
@@ -243,87 +253,3 @@ Publishing. See [RELEASING.md](RELEASING.md) for setup, version overrides, and r
# License
Apache License v2
-
-## Migrating to 14.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. Prefer
-an explicit wait around operations that need to wait for the app:
-
-```ruby
-core = Appium::Core.for(
- capabilities: { platformName: 'Android', automationName: 'UiAutomator2' },
- appium_lib: { wait_timeout: 30, wait_interval: 0.5 }
-)
-driver = core.start_driver
-button = core.wait { driver.find_element(:accessibility_id, 'Continue') }
-button.click
-```
-
-`wait_timeout` controls `core.wait` / `core.wait_true`; it does not make ordinary
-`find_element` calls wait. If your application needs an implicit wait, set it
-explicitly after session creation:
-
-```ruby
-driver.manage.timeouts.implicit_wait = 30 # seconds
-```
-
-Keep any application-specific default wait in your own configuration instead of
-reading `core.default_wait`. Explicit Selenium timeout configuration remains supported.
-
-### 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.
-
-The breaking-change commit is intended to make Release Please prepare 14.0.0.
-Version, date, manifest, and changelog updates belong in that generated release PR.
From 76fa48c01e31bc1159d2e5c6abb43f1471961442 Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 13:15:51 -0800
Subject: [PATCH 06/15] docs: use Selenium implicit waits in migration examples
---
CHANGELOG.md | 20 ++++++++------------
README.md | 9 ++++-----
2 files changed, 12 insertions(+), 17 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f9bab37c..2e7ed640 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,26 +13,22 @@ Version 14 removes `Appium.symbolize_keys`, the `appium_lib[:wait]` option,
#### 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. Prefer
-an explicit wait around operations that need to wait for the app:
+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' },
- appium_lib: { wait_timeout: 30, wait_interval: 0.5 }
+ capabilities: { platformName: 'Android', automationName: 'UiAutomator2' }
)
driver = core.start_driver
-button = core.wait { driver.find_element(:accessibility_id, 'Continue') }
+driver.manage.timeouts.implicit_wait = 30 # seconds
+button = driver.find_element(:accessibility_id, 'Continue')
button.click
```
-`wait_timeout` controls `core.wait` / `core.wait_true`; it does not make ordinary
-`find_element` calls wait. If your application needs an implicit wait, set it
-explicitly after session creation:
-
-```ruby
-driver.manage.timeouts.implicit_wait = 30 # seconds
-```
+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.
diff --git a/README.md b/README.md
index ff364a48..ca0a0cea 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,8 @@ This library wraps [selenium-webdriver](https://github.com/SeleniumHQ/selenium/w
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. Use explicit waits,
+`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.
See [Migration from v13 to v14](CHANGELOG.md#migration-from-v13-to-v14) in
@@ -128,16 +129,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_timeout: 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`
- @core.wait { @driver.find_element(:accessibility_id, 'some accessibility') } # wait for an element
+ @driver.find_element(:accessibility_id, 'some accessibility') # wait up to 30 seconds for an element
```
- Run the script
```bash
From 387c53706ac5669f5f8d803b7e17e27e9e6ce6c1 Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 13:18:03 -0800
Subject: [PATCH 07/15] test: use implicit waits in Android W3C actions
---
.../android/webdriver/w3c_actions_test.rb | 23 +++++++++----------
1 file changed, 11 insertions(+), 12 deletions(-)
diff --git a/test/functional/android/webdriver/w3c_actions_test.rb b/test/functional/android/webdriver/w3c_actions_test.rb
index 92729f38..e8374830 100644
--- a/test/functional/android/webdriver/w3c_actions_test.rb
+++ b/test/functional/android/webdriver/w3c_actions_test.rb
@@ -23,6 +23,7 @@ class W3CActionsTest < AppiumLibCoreTest::Function::TestCase
def setup
@@core ||= ::Appium::Core.for(Caps.android)
@driver = @@core.start_driver
+ @driver.manage.timeouts.implicit_wait = 20
end
def teardown
@@ -33,10 +34,10 @@ def teardown
def test_tap_scroll
skip_as_appium_version '1.8.0'
- el = @@core.wait { @driver.find_element(:accessibility_id, 'Views') }
+ el = @driver.find_element(:accessibility_id, 'Views')
@driver.action.click(el).perform
- el = @@core.wait { @driver.find_element(:accessibility_id, 'Custom') }
+ el = @driver.find_element(:accessibility_id, 'Custom')
rect1 = el.rect.dup
@driver
@@ -50,29 +51,27 @@ def test_tap_scroll
w3c_scroll @driver
- @driver.manage.timeouts.implicit_wait = 3
-
if @@core.automation_name == :espresso
- el = @@core.wait { @driver.find_element(:accessibility_id, 'Lists') }
+ el = @driver.find_element(:accessibility_id, 'Lists')
assert_equal 'Lists', el.text
else
+ @driver.manage.timeouts.implicit_wait = 3
assert_raises ::Selenium::WebDriver::Error::NoSuchElementError do
@driver.find_element(:accessibility_id, 'Custom')
end
end
- @driver.manage.timeouts.implicit_wait = 0
end
def test_double_tap
skip_as_appium_version '1.10.0' # unstable on 1.9.1-
- el = @@core.wait { @driver.find_element(:accessibility_id, 'Views') }
+ el = @driver.find_element(:accessibility_id, 'Views')
@driver.action.click(el).perform
- el = @@core.wait { @driver.find_element(:accessibility_id, 'Buttons') }
+ el = @driver.find_element(:accessibility_id, 'Buttons')
@driver.action.click(el).perform
- el = @@core.wait { @driver.find_element(:id, 'io.appium.android.apis:id/button_toggle') }
+ el = @driver.find_element(:id, 'io.appium.android.apis:id/button_toggle')
assert_equal 'OFF', el.text
@driver.action.click(el).perform
@@ -107,10 +106,10 @@ def test_double_tap
def test_actions_with_many_down_up
skip_as_appium_version '1.8.0'
- el = @@core.wait { @driver.find_element(:accessibility_id, 'Views') }
+ el = @driver.find_element(:accessibility_id, 'Views')
@driver.action.click_and_hold(el).release.perform
- el = @@core.wait { @driver.find_element(:accessibility_id, 'Custom') }
+ el = @driver.find_element(:accessibility_id, 'Custom')
rect1 = el.rect.dup
@@ -179,7 +178,7 @@ def test_multiple_actions
origin: ::Selenium::WebDriver::Interactions::PointerMove::VIEWPORT)
f2.create_pointer_up(:left)
- @@core.wait { @driver.perform_actions [f1, f2] }
+ @driver.perform_actions [f1, f2]
end
end
end
From 59c67a573cdb883ef1ed323af3ada08f7a176a34 Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 13:23:21 -0800
Subject: [PATCH 08/15] feat!: narrow default wait retries to missing elements
---
CHANGELOG.md | 20 +++++
README.md | 3 +
lib/appium_lib_core/common/wait.rb | 12 +--
test/unit/common/wait_test.rb | 126 +++++++++++++++++++++++++++++
4 files changed, 155 insertions(+), 6 deletions(-)
create mode 100644 test/unit/common/wait_test.rb
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2e7ed640..7d1ee053 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,6 +33,26 @@ 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.
+
#### Hash keys
Callers using `Appium.symbolize_keys` must replace that call. Prefer defining
diff --git a/README.md b/README.md
index ca0a0cea..ba1554de 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,9 @@ Version 14 removes automatic implicit-wait configuration, `Appium.symbolize_keys
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.
diff --git a/lib/appium_lib_core/common/wait.rb b/lib/appium_lib_core/common/wait.rb
index ce252b49..7ae17a32 100644
--- a/lib/appium_lib_core/common/wait.rb
+++ b/lib/appium_lib_core/common/wait.rb
@@ -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] ignored Exception classes to retry (default: Selenium::WebDriver::Error::NoSuchElementError)
# @param [Object, NilClass] object Object to evaluate block against
#
# @example
@@ -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)
@@ -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] ignored Exception classes to retry (default: Selenium::WebDriver::Error::NoSuchElementError)
# @param [Object, NilClass] object Object to evaluate block against
#
# @example
@@ -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)
@@ -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] ignored Exception classes to retry (default: Selenium::WebDriver::Error::NoSuchElementError)
#
# @example With core instance
#
@@ -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] ignored Exception classes to retry (default: Selenium::WebDriver::Error::NoSuchElementError)
#
# @example With core instance
#
diff --git a/test/unit/common/wait_test.rb b/test/unit/common/wait_test.rb
new file mode 100644
index 00000000..e8f9879f
--- /dev/null
+++ b/test/unit/common/wait_test.rb
@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'test_helper'
+
+class AppiumLibCoreTest
+ class WaitTest < Minitest::Test
+ def test_missing_elements_are_retried_by_default
+ %i[until until_true].each do |method|
+ calls = 0
+ result = Appium::Core::Wait.public_send(method, timeout: 1, interval: 0) do
+ calls += 1
+ raise Selenium::WebDriver::Error::NoSuchElementError, 'not ready' if calls == 1
+
+ :found
+ end
+ assert_equal :found, result
+ assert_equal 2, calls
+ end
+ end
+
+ def test_other_errors_propagate_without_retry
+ %i[until until_true].each do |method|
+ [NoMethodError.new('typo'), RuntimeError.new('failure'), Interrupt.new,
+ SystemExit.new, Selenium::WebDriver::Error::InvalidSessionIdError.new('closed')].each do |error|
+ calls = 0
+ actual = assert_raises(error.class) do
+ Appium::Core::Wait.public_send(method, timeout: 0.01, interval: 0) do
+ calls += 1
+ raise error
+ end
+ end
+ assert_same error, actual
+ assert_equal 1, calls
+ end
+ end
+ end
+
+ def test_explicit_ignored_errors_are_retried
+ %i[until until_true].each do |method|
+ [RuntimeError, [RuntimeError]].each do |ignored|
+ calls = 0
+ result = Appium::Core::Wait.public_send(method, timeout: 1, interval: 0, ignored: ignored) do
+ calls += 1
+ raise 'not ready' if calls == 1
+
+ :ready
+ end
+ assert_equal :ready, result
+ assert_equal 2, calls
+ end
+ end
+ end
+
+ def test_explicit_empty_list_disables_default_retry
+ %i[until until_true].each do |method|
+ calls = 0
+ assert_raises(Selenium::WebDriver::Error::NoSuchElementError) do
+ Appium::Core::Wait.public_send(method, timeout: 0.01, interval: 0, ignored: []) do
+ calls += 1
+ raise Selenium::WebDriver::Error::NoSuchElementError
+ end
+ end
+ assert_equal 1, calls
+ end
+ end
+
+ def test_timeout_keeps_the_last_missing_element_error
+ %i[until until_true].each do |method|
+ error = assert_raises(Appium::Core::Wait::TimeoutError) do
+ Appium::Core::Wait.public_send(method, timeout: 0.01, interval: 0, message: 'waiting for button') do
+ raise Selenium::WebDriver::Error::NoSuchElementError, 'button missing'
+ end
+ end
+ assert_match(/waiting for button/, error.message)
+ assert_match(/button missing/, error.message)
+ end
+ end
+
+ def test_success_conditions_are_unchanged
+ assert_nil Appium::Core::Wait.until(timeout: 1) { nil }
+ assert_equal false, Appium::Core::Wait.until(timeout: 1) { false }
+ values = [nil, false, :ready]
+ assert_equal :ready, Appium::Core::Wait.until_true(timeout: 1, interval: 0) { values.shift }
+ assert_empty values
+ end
+
+ def test_connection_refused_is_never_retried_even_when_explicitly_ignored
+ %i[until until_true].each do |method|
+ calls = 0
+ assert_raises(Errno::ECONNREFUSED) do
+ Appium::Core::Wait.public_send(method, timeout: 0.01, interval: 0, ignored: Exception) do
+ calls += 1
+ raise Errno::ECONNREFUSED
+ end
+ end
+ assert_equal 1, calls
+ end
+ end
+
+ def test_waitable_aliases_use_the_new_default
+ core = Appium::Core.for(Caps.android)
+ %i[wait wait_until wait_true wait_until_true].each do |method|
+ calls = 0
+ assert_raises(NoMethodError) do
+ core.public_send(method, timeout: 0.01, interval: 0) do
+ calls += 1
+ raise NoMethodError, 'typo'
+ end
+ end
+ assert_equal 1, calls
+ end
+ end
+ end
+end
From 6ffd066eb330ea8d6ba1a669f8283acc516f9344 Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 13:27:59 -0800
Subject: [PATCH 09/15] docs: explain wait behavior compared with Selenium Ruby
---
CHANGELOG.md | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7d1ee053..9361317c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -53,6 +53,21 @@ immediately, even when included in `ignored:`.
`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
From 47e217bc59f3d401802d79dbca0b96a4c51658d9 Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 13:28:51 -0800
Subject: [PATCH 10/15] docs: distinguish migration notes from release headers
---
CHANGELOG.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9361317c..dda8e26f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,10 +2,10 @@
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`.
-## Unreleased
-
### 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`.
From 4f2db49b1c9799bbb6a1b6a363324fb0caa07cf0 Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 13:32:38 -0800
Subject: [PATCH 11/15] ci: expand Ruby unit test coverage
---
.github/workflows/unittest.yml | 13 +++++++------
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/.github/workflows/unittest.yml b/.github/workflows/unittest.yml
index ec28c41c..1bd24a83 100644
--- a/.github/workflows/unittest.yml
+++ b/.github/workflows/unittest.yml
@@ -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
@@ -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
@@ -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
From fdacb1ad464417c2e4c59491d4c86a76adb2a4f8 Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 14:47:18 -0800
Subject: [PATCH 12/15] remove applesimutils
---
.github/workflows/functional-test.yml | 2 --
1 file changed, 2 deletions(-)
diff --git a/.github/workflows/functional-test.yml b/.github/workflows/functional-test.yml
index 0f25a805..7891f8e7 100644
--- a/.github/workflows/functional-test.yml
+++ b/.github/workflows/functional-test.yml
@@ -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
From 653056a4d14919607f62ccbb6abe70b6b4fefea9 Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 14:54:46 -0800
Subject: [PATCH 13/15] fix: preserve clean element caches and migrate Android
waits
---
lib/appium_lib_core/element.rb | 3 +-
.../functional/android/android/device_test.rb | 82 +++++++++----------
.../android/android/search_context_test.rb | 4 +-
test/functional/android/driver_test.rb | 1 +
test/unit/common/element_cache_test.rb | 2 +
5 files changed, 49 insertions(+), 43 deletions(-)
diff --git a/lib/appium_lib_core/element.rb b/lib/appium_lib_core/element.rb
index 724ca3a7..fc64148f 100644
--- a/lib/appium_lib_core/element.rb
+++ b/lib/appium_lib_core/element.rb
@@ -115,7 +115,8 @@ def attribute_key(name)
def initialize(bridge, id, cached = nil)
if id.is_a?(Hash)
# Preserve any extra attributes included in the element response.
- cached = Cache.new(id.except(ELEMENT_KEY))
+ # Legacy IDs can accompany a W3C ID, but are not cached attributes.
+ cached = Cache.new(id.except('ELEMENT', ELEMENT_KEY))
id = id[ELEMENT_KEY]
end
raise ::Selenium::WebDriver::Error::WebDriverError, 'Missing W3C element ID in response' if id.nil?
diff --git a/test/functional/android/android/device_test.rb b/test/functional/android/android/device_test.rb
index 849287cb..65bcc5b7 100644
--- a/test/functional/android/android/device_test.rb
+++ b/test/functional/android/android/device_test.rb
@@ -22,6 +22,8 @@ class DeviceTest < AppiumLibCoreTest::Function::TestCase
def setup
@@core ||= ::Appium::Core.for(Caps.android)
@driver = @@core.start_driver
+ @driver.manage.timeouts.implicit_wait = 20
+ @state_wait = Selenium::WebDriver::Wait.new(timeout: 20)
end
def teardown
@@ -51,16 +53,16 @@ def test_shake
def test_lock_unlock
@driver.lock 0
# Unstable on CI
- @@core.wait { assert @driver.device_locked? } unless ci?
+ @state_wait.until { @driver.device_locked? } unless ci?
@driver.unlock
- @driver.wait_until { |d| assert !d.device_locked? }
+ @state_wait.until { !@driver.device_locked? }
end
def test_background_reset
@driver.background_app 3
- e = @driver.wait_until { |d| d.find_element :accessibility_id, 'App' }
+ e = @driver.find_element(:accessibility_id, 'App')
assert_equal 'App', e.text
@driver.background_app(-1)
@@ -70,7 +72,7 @@ def test_background_reset
# Instrumentation process will crash in Espresso
if @@core.automation_name == :espresso
@driver.activate_app('io.appium.android.apis')
- @driver.wait_until { |d| assert d.app_state('io.appium.android.apis') == :running_in_foreground }
+ @state_wait.until { @driver.app_state('io.appium.android.apis') == :running_in_foreground }
else
error = assert_raises ::Selenium::WebDriver::Error::WebDriverError do
@driver.find_element :accessibility_id, 'App'
@@ -98,25 +100,23 @@ def test_context_related
@@core.wait { scroll_to('Views') }.click
@@core.wait { scroll_to('WebView') }.click
- @@core.wait { assert_equal 'NATIVE_APP', @driver.current_context }
+ @state_wait.until { @driver.current_context == 'NATIVE_APP' }
native_page = @driver.page_source
- webview_context = @@core.wait do
+ webview_context = @state_wait.until do
@driver.execute_script 'mobile: getContexts', { waitForWebviewMs: 5000 }
- context = @driver.available_contexts.detect { |c| c.start_with?('WEBVIEW') }
- assert context
- context
+ @driver.available_contexts.detect { |c| c.start_with?('WEBVIEW') }
end
@driver.set_context webview_context
- @driver.wait { |d| assert d.current_context.start_with? 'WEBVIEW' }
+ @state_wait.until { @driver.current_context.start_with? 'WEBVIEW' }
webview_page = @driver.page_source
@driver.set_context 'NATIVE_APP'
- @driver.wait { |d| assert_equal 'NATIVE_APP', d.current_context }
+ @state_wait.until { @driver.current_context == 'NATIVE_APP' }
assert native_page != webview_page
end
@@ -144,11 +144,12 @@ def test_app_management
# Instrumentation process will crash in Espresso
unless @@core.automation_name == :espresso
assert @driver.terminate_app('io.appium.android.apis')
- @driver.wait_until { |d| assert d.app_state('io.appium.android.apis') == :not_running }
+ @state_wait.until { @driver.app_state('io.appium.android.apis') == :not_running }
end
assert @driver.activate_app('io.appium.android.apis').nil?
- @driver.wait_until { assert @driver.app_state('io.appium.android.apis') == :running_in_foreground }
+ @state_wait.until { @driver.app_state('io.appium.android.apis') == :running_in_foreground }
+ assert_equal :running_in_foreground, @driver.app_state('io.appium.android.apis')
end
def test_current_package
@@ -157,11 +158,10 @@ def test_current_package
end
def test_hidekeyboard
- @driver.wait_until { |d| d.find_element :accessibility_id, 'App' }.click
- @driver.wait_until { |d| d.find_element :accessibility_id, 'Activity' }.click
- @driver.wait_until { |d| d.find_element :accessibility_id, 'Custom Title' }.click
- # make sure to show keyboard
- @driver.wait_until { |d| d.find_element :id, 'io.appium.android.apis:id/left_text_edit' }.click
+ @driver.find_element(:accessibility_id, 'App').click
+ @driver.find_element(:accessibility_id, 'Activity').click
+ @driver.find_element(:accessibility_id, 'Custom Title').click
+ original_ime = @driver.ime_active_engine
latin_android = 'com.android.inputmethod.latin/.LatinIME'
latin_google = 'com.google.android.inputmethod.latin/com.android.inputmethod.latin.LatinIME'
@@ -175,12 +175,15 @@ def test_hidekeyboard
end
@driver.ime_activate ime_latin
- assert @driver.keyboard_shown?
-
- @driver.wait(&:hide_keyboard)
- sleep 1 # wait animation
-
- assert !@driver.is_keyboard_shown
+ # Select the IME before focusing the field so switching engines does not
+ # race with the keyboard visibility check or hide command.
+ @driver.find_element(:id, 'io.appium.android.apis:id/left_text_edit').click
+ @state_wait.until { @driver.keyboard_shown? }
+ @driver.hide_keyboard
+ @state_wait.until { !@driver.keyboard_shown? }
+ refute @driver.is_keyboard_shown
+ ensure
+ @driver.ime_activate(original_ime) if original_ime
end
def test_get_system_bars
@@ -206,21 +209,19 @@ def test_long_press_keycode
def test_open_notifications
skip if @@core.automation_name == :espresso
- @driver.open_notifications
- # shouldn't see the elements behind shade
-
- # Sometimes, we should wait animation
- @@core.wait(timeout: 5) do
- error = assert_raises ::Selenium::WebDriver::Error::WebDriverError do
- @driver.find_element :accessibility_id, 'Appium Settings'
- end
- assert 'An element could not be located on the page using the given search parameters.', error.message
+ assert_equal 'Accessibility', @driver.find_element(:accessibility_id, 'Accessibility').text
+ begin
+ @driver.open_notifications
+ # Poll absence without applying the session's positive-lookup timeout.
+ @driver.manage.timeouts.implicit_wait = 0
+ @state_wait.until { @driver.find_elements(:accessibility_id, 'Accessibility').empty? }
+ assert_empty @driver.find_elements(:accessibility_id, 'Accessibility')
+ ensure
+ @driver.execute_script('mobile: statusBar', { command: 'collapse' })
+ @driver.manage.timeouts.implicit_wait = 20
end
- # return to app
- @driver.back
- # should be able to see elements from app
- @@core.wait_true { @driver.find_element :accessibility_id, 'Accessibility' }
+ assert_equal 'Accessibility', @driver.find_element(:accessibility_id, 'Accessibility').text
end
def test_ime_available_engines
@@ -235,10 +236,9 @@ def test_ime_available_engines
@@core.wait { @driver.ime_deactivate }
refute_equal available_ime, @driver.ime_active_engine
- @@core.wait do
- @driver.ime_activate(available_ime)
- assert_equal available_ime, @driver.ime_active_engine
- end
+ @driver.ime_activate(available_ime)
+ @state_wait.until { @driver.ime_active_engine == available_ime }
+ assert_equal available_ime, @driver.ime_active_engine
end
def test_within_context
diff --git a/test/functional/android/android/search_context_test.rb b/test/functional/android/android/search_context_test.rb
index edd2eb6c..76418d58 100644
--- a/test/functional/android/android/search_context_test.rb
+++ b/test/functional/android/android/search_context_test.rb
@@ -22,6 +22,7 @@ class SearchContextTest < AppiumLibCoreTest::Function::TestCase
def setup
@@core ||= ::Appium::Core.for(Caps.android)
@driver = @@core.start_driver
+ @driver.manage.timeouts.implicit_wait = 20
end
def teardown
@@ -50,7 +51,8 @@ def test_cached_element_attributes_remain_a_snapshot
assert_equal element.size, element.cached.size
element.click
- @@core.wait { assert_equal 'ON', element.text }
+ Selenium::WebDriver::Wait.new(timeout: 20).until { element.text == 'ON' }
+ assert_equal 'ON', element.text
assert_equal 'OFF', element.cached.text
assert_equal 'ON', @driver.find_element(:id, 'io.appium.android.apis:id/button_toggle').cached.text
end
diff --git a/test/functional/android/driver_test.rb b/test/functional/android/driver_test.rb
index 33cbcd17..6b38b676 100644
--- a/test/functional/android/driver_test.rb
+++ b/test/functional/android/driver_test.rb
@@ -21,6 +21,7 @@ class DriverTest < AppiumLibCoreTest::Function::TestCase
def setup
@@core ||= ::Appium::Core.for(Caps.android)
@driver = @@core.start_driver
+ @driver.manage.timeouts.implicit_wait = 20
end
def teardown
diff --git a/test/unit/common/element_cache_test.rb b/test/unit/common/element_cache_test.rb
index cfb10e3c..4a127deb 100644
--- a/test/unit/common/element_cache_test.rb
+++ b/test/unit/common/element_cache_test.rb
@@ -108,6 +108,8 @@ def test_w3c_element_id_takes_precedence
element = @driver.convert_to_element(response.merge('ELEMENT' => 'legacy-id'))
assert_equal 'id', element.id
assert_equal 'original', element.cached.text
+ refute element.cached.attributes.key?('ELEMENT')
+ refute element.cached.attributes.key?(Appium::Core::Element::ELEMENT_KEY)
end
def test_standard_boolean_fields_match_element_api
From 6fab6826b03b0c2ab05068540bbf8919d76f03d6 Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 15:03:16 -0800
Subject: [PATCH 14/15] test: use Appium driver waits for Android state changes
---
.../functional/android/android/device_test.rb | 27 +++++++++----------
.../android/android/search_context_test.rb | 2 +-
2 files changed, 14 insertions(+), 15 deletions(-)
diff --git a/test/functional/android/android/device_test.rb b/test/functional/android/android/device_test.rb
index 65bcc5b7..a9112ab2 100644
--- a/test/functional/android/android/device_test.rb
+++ b/test/functional/android/android/device_test.rb
@@ -23,7 +23,6 @@ def setup
@@core ||= ::Appium::Core.for(Caps.android)
@driver = @@core.start_driver
@driver.manage.timeouts.implicit_wait = 20
- @state_wait = Selenium::WebDriver::Wait.new(timeout: 20)
end
def teardown
@@ -53,10 +52,10 @@ def test_shake
def test_lock_unlock
@driver.lock 0
# Unstable on CI
- @state_wait.until { @driver.device_locked? } unless ci?
+ @driver.wait_true(timeout: 20) { @driver.device_locked? } unless ci?
@driver.unlock
- @state_wait.until { !@driver.device_locked? }
+ @driver.wait_true(timeout: 20) { !@driver.device_locked? }
end
def test_background_reset
@@ -72,7 +71,7 @@ def test_background_reset
# Instrumentation process will crash in Espresso
if @@core.automation_name == :espresso
@driver.activate_app('io.appium.android.apis')
- @state_wait.until { @driver.app_state('io.appium.android.apis') == :running_in_foreground }
+ @driver.wait_true(timeout: 20) { @driver.app_state('io.appium.android.apis') == :running_in_foreground }
else
error = assert_raises ::Selenium::WebDriver::Error::WebDriverError do
@driver.find_element :accessibility_id, 'App'
@@ -100,23 +99,23 @@ def test_context_related
@@core.wait { scroll_to('Views') }.click
@@core.wait { scroll_to('WebView') }.click
- @state_wait.until { @driver.current_context == 'NATIVE_APP' }
+ @driver.wait_true(timeout: 20) { @driver.current_context == 'NATIVE_APP' }
native_page = @driver.page_source
- webview_context = @state_wait.until do
+ webview_context = @driver.wait_true(timeout: 20) do
@driver.execute_script 'mobile: getContexts', { waitForWebviewMs: 5000 }
@driver.available_contexts.detect { |c| c.start_with?('WEBVIEW') }
end
@driver.set_context webview_context
- @state_wait.until { @driver.current_context.start_with? 'WEBVIEW' }
+ @driver.wait_true(timeout: 20) { @driver.current_context.start_with? 'WEBVIEW' }
webview_page = @driver.page_source
@driver.set_context 'NATIVE_APP'
- @state_wait.until { @driver.current_context == 'NATIVE_APP' }
+ @driver.wait_true(timeout: 20) { @driver.current_context == 'NATIVE_APP' }
assert native_page != webview_page
end
@@ -144,11 +143,11 @@ def test_app_management
# Instrumentation process will crash in Espresso
unless @@core.automation_name == :espresso
assert @driver.terminate_app('io.appium.android.apis')
- @state_wait.until { @driver.app_state('io.appium.android.apis') == :not_running }
+ @driver.wait_true(timeout: 20) { @driver.app_state('io.appium.android.apis') == :not_running }
end
assert @driver.activate_app('io.appium.android.apis').nil?
- @state_wait.until { @driver.app_state('io.appium.android.apis') == :running_in_foreground }
+ @driver.wait_true(timeout: 20) { @driver.app_state('io.appium.android.apis') == :running_in_foreground }
assert_equal :running_in_foreground, @driver.app_state('io.appium.android.apis')
end
@@ -178,9 +177,9 @@ def test_hidekeyboard
# Select the IME before focusing the field so switching engines does not
# race with the keyboard visibility check or hide command.
@driver.find_element(:id, 'io.appium.android.apis:id/left_text_edit').click
- @state_wait.until { @driver.keyboard_shown? }
+ @driver.wait_true(timeout: 20) { @driver.keyboard_shown? }
@driver.hide_keyboard
- @state_wait.until { !@driver.keyboard_shown? }
+ @driver.wait_true(timeout: 20) { !@driver.keyboard_shown? }
refute @driver.is_keyboard_shown
ensure
@driver.ime_activate(original_ime) if original_ime
@@ -214,7 +213,7 @@ def test_open_notifications
@driver.open_notifications
# Poll absence without applying the session's positive-lookup timeout.
@driver.manage.timeouts.implicit_wait = 0
- @state_wait.until { @driver.find_elements(:accessibility_id, 'Accessibility').empty? }
+ @driver.wait_true(timeout: 20) { @driver.find_elements(:accessibility_id, 'Accessibility').empty? }
assert_empty @driver.find_elements(:accessibility_id, 'Accessibility')
ensure
@driver.execute_script('mobile: statusBar', { command: 'collapse' })
@@ -237,7 +236,7 @@ def test_ime_available_engines
refute_equal available_ime, @driver.ime_active_engine
@driver.ime_activate(available_ime)
- @state_wait.until { @driver.ime_active_engine == available_ime }
+ @driver.wait_true(timeout: 20) { @driver.ime_active_engine == available_ime }
assert_equal available_ime, @driver.ime_active_engine
end
diff --git a/test/functional/android/android/search_context_test.rb b/test/functional/android/android/search_context_test.rb
index 76418d58..d1426e83 100644
--- a/test/functional/android/android/search_context_test.rb
+++ b/test/functional/android/android/search_context_test.rb
@@ -51,7 +51,7 @@ def test_cached_element_attributes_remain_a_snapshot
assert_equal element.size, element.cached.size
element.click
- Selenium::WebDriver::Wait.new(timeout: 20).until { element.text == 'ON' }
+ @driver.wait_true(timeout: 20) { element.text == 'ON' }
assert_equal 'ON', element.text
assert_equal 'OFF', element.cached.text
assert_equal 'ON', @driver.find_element(:id, 'io.appium.android.apis:id/button_toggle').cached.text
From 14f479c957465afa250895270bcb047908e1b6e8 Mon Sep 17 00:00:00 2001
From: Kazuaki Matsuo
Date: Sun, 15 Nov 2026 15:51:28 -0800
Subject: [PATCH 15/15] test: fix remaining wait migrations and iOS test
assumptions
---
.../android/android/image_comparison_test.rb | 1 +
test/functional/ios/ios/device_test.rb | 10 ++++------
test/functional/ios/ios/device_wda_attachment_test.rb | 6 +++---
test/functional/ios/webdriver/w3c_actions_test.rb | 4 ++--
4 files changed, 10 insertions(+), 11 deletions(-)
diff --git a/test/functional/android/android/image_comparison_test.rb b/test/functional/android/android/image_comparison_test.rb
index 23723d46..2e8cf1e5 100644
--- a/test/functional/android/android/image_comparison_test.rb
+++ b/test/functional/android/android/image_comparison_test.rb
@@ -22,6 +22,7 @@ class ImageComparisionTest < AppiumLibCoreTest::Function::TestCase
def setup
@@core ||= ::Appium::Core.for(Caps.android)
@driver = @@core.start_driver
+ @driver.manage.timeouts.implicit_wait = 20
end
def teardown
diff --git a/test/functional/ios/ios/device_test.rb b/test/functional/ios/ios/device_test.rb
index 23da4ccb..288610c5 100644
--- a/test/functional/ios/ios/device_test.rb
+++ b/test/functional/ios/ios/device_test.rb
@@ -98,20 +98,18 @@ def test_context_related
e = @@core.wait { @@driver.find_element :accessibility_id, 'Web View' }
e.click
- webview_context = @@core.wait do
- context = @@driver.available_contexts.detect { |c| c.start_with?('WEBVIEW') }
- assert context
- context
+ webview_context = @@driver.wait_true do
+ @@driver.available_contexts.detect { |c| c.start_with?('WEBVIEW') }
end
@@driver.set_context webview_context
- @@core.wait { assert @@driver.current_context.start_with? 'WEBVIEW' }
+ @@driver.wait_true { @@driver.current_context.start_with? 'WEBVIEW' }
@@driver.set_context 'NATIVE_APP'
assert_equal 'NATIVE_APP', @@driver.current_context
@@driver.back # go to top
- @@core.wait { assert [1, 2].member? @@driver.available_contexts.size }
+ @@driver.wait_true { [1, 2].member? @@driver.available_contexts.size }
end
def test_app_string
diff --git a/test/functional/ios/ios/device_wda_attachment_test.rb b/test/functional/ios/ios/device_wda_attachment_test.rb
index 88b4c1c2..4ddbedc4 100644
--- a/test/functional/ios/ios/device_wda_attachment_test.rb
+++ b/test/functional/ios/ios/device_wda_attachment_test.rb
@@ -35,7 +35,7 @@ def test_localhost_wda_agent_url
status = JSON.parse(Net::HTTP.get('localhost', '/status', @core.caps[:wdaLocalPort]))['value']
# Run with webDriverAgentUrl
- current_host = status['ios']['ip']
+ current_host = 'localhost'
current_port = @core.caps[:wdaLocalPort]
new_ios_caps = Caps.ios.dup
@@ -59,8 +59,8 @@ def test_localhost_wda_agent_url
# Create the original driver again
@driver = @core.start_driver
- status = JSON.parse(Net::HTTP.get('localhost', '/status', @core.caps[:wdaLocalPort]))['value']
- current_host = status['ios']['ip']
+ assert JSON.parse(Net::HTTP.get('localhost', '/status', @core.caps[:wdaLocalPort]))['value']
+ current_host = 'localhost'
current_port = @core.caps[:wdaLocalPort]
@driver.quit
diff --git a/test/functional/ios/webdriver/w3c_actions_test.rb b/test/functional/ios/webdriver/w3c_actions_test.rb
index d0db36a3..d63f0100 100644
--- a/test/functional/ios/webdriver/w3c_actions_test.rb
+++ b/test/functional/ios/webdriver/w3c_actions_test.rb
@@ -52,7 +52,7 @@ def test_scroll
@@driver.action.click(el).perform
[1, 2, 3].each do |count|
- el = @@driver.find_element(:accessibility_id, 'TINTED')
+ el = @@driver.find_element(:predicate, 'name ==[c] "Tinted"')
rect = el.rect
@@driver.execute_script('mobile: scroll', direction: 'down')
@@ -71,7 +71,7 @@ def test_scroll2
el = @@core.wait { @@driver.find_element(:accessibility_id, 'Segmented Controls') }
@@driver.action.click(el).perform
- el = @@core.wait { @@driver.find_element(:accessibility_id, 'TINTED') }
+ el = @@core.wait { @@driver.find_element(:predicate, 'name ==[c] "Tinted"') }
rect = el.rect
w3c_scroll @@driver