diff --git a/.github/workflows/functional-test.yml b/.github/workflows/functional-test.yml
index 609e4ba5..d506ab08 100644
--- a/.github/workflows/functional-test.yml
+++ b/.github/workflows/functional-test.yml
@@ -44,10 +44,12 @@ jobs:
- run: defaults write com.apple.iphonesimulator PasteboardAutomaticSync -bool false
- uses: futureware-tech/simulator-action@v6
+ id: simulator
with:
# https://github.com/actions/runner-images/blob/main/images/macos/macos-14-arm64-Readme.md
model: ${{ env.IOS_DEVICE_NAME }}
os_version: ${{ env.IOS_VERSION }}
+ wait_for_boot: true
- name: Preparing other environment
run: |
@@ -79,6 +81,7 @@ jobs:
timeout-minutes: 60
working-directory: ios_tests
env:
+ IOS_UDID: ${{ steps.simulator.outputs.udid }}
LOCAL_PREBUILT_WDA: ${{ github.workspace }}/wda/WebDriverAgentRunner-Runner.app
- name: Save server output
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 186230d1..d9fc937f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,34 @@ New entries are maintained by Release Please.
Release tags are https://github.com/appium/ruby_lib/releases .
+### Upgrading to core 14 (unreleased)
+
+This library requires `appium_lib_core >= 14.0.0, < 15.0`.
+
+- `wait` and `wait_true` now retry only `Selenium::WebDriver::Error::NoSuchElementError`
+ by default. Other errors, including assertion failures and interruptions, propagate
+ immediately. Use `ignored: [SomeTransientError]` to choose retryable exceptions;
+ this replaces the default list. Use `ignored: []` to disable exception retries.
+ `wait` still accepts false or nil results, while `wait_true` requires a truthy result.
+- `Appium::Driver` continues to support `appium_lib: { wait: seconds }`, `default_wait`,
+ `no_wait`, and `set_wait`. The wrapper applies a configured implicit wait after each
+ session starts. Without that option, it sends no implicit-timeout command.
+ Direct `Appium::Core` users must configure `driver.manage.timeouts.implicit_wait`
+ themselves. `wait_timeout` controls explicit waits, not implicit waits.
+- `element_screenshot` and `take_element_screenshot` remain available on
+ `Appium::Driver`; they now use core's `save_element_screenshot`.
+- Replace `element.location_rel(driver)` with `element.rect`. To calculate the
+ center relative to the window, use `(rect.x + rect.width / 2.0) / window.width`
+ and `(rect.y + rect.height / 2.0) / window.height`.
+- `Appium.symbolize_keys` is removed. Use symbol keys for client options or Ruby's
+ `transform_keys(&:to_sym)` where appropriate. The wrapper accepts string client
+ option keys without converting capability keys or nested capability values.
+- Custom server responses must use the W3C element key
+ `element-6066-11e4-a52e-4f735466cecf`; legacy `ELEMENT` references are no longer supported.
+
+See the [core 14 migration notes](https://github.com/appium/ruby_lib_core/blob/v14.0.0/CHANGELOG.md)
+for changes affecting direct core API usage.
+
## [16.5.1](https://github.com/appium/ruby_lib/compare/v16.5.0...v16.5.1) (2026-11-06)
diff --git a/android_tests/lib/android/navigation.rb b/android_tests/lib/android/navigation.rb
index 40bade11..f6cd59c1 100644
--- a/android_tests/lib/android/navigation.rb
+++ b/android_tests/lib/android/navigation.rb
@@ -12,6 +12,10 @@ def start_test_activity(component)
end
def reset_test_app
+ AppiumTestSession.driver.set_context 'NATIVE_APP'
start_test_activity('io.appium.android.apis/.ApiDemos')
+ AppiumTestSession.driver.wait_true do
+ AppiumTestSession.driver.text_exact('NFC').displayed?
+ end
end
end
diff --git a/android_tests/lib/android/specs/android/element/alert.rb b/android_tests/lib/android/specs/android/element/alert.rb
index 0072d923..4f302d8a 100644
--- a/android_tests/lib/android/specs/android/element/alert.rb
+++ b/android_tests/lib/android/specs/android/element/alert.rb
@@ -32,41 +32,44 @@ def teardown
end
def open_alert
- # trigger the alert
+ # Click once, then wait for the dialog rather than matching its launch button again.
wait { button('OK Cancel dialog with a message').click }
+ wait_true do
+ button_exact('OK').displayed? && button_exact('Cancel').displayed?
+ end
end
def test_01_alert_click
# test
- wait { open_alert }
+ open_alert
wait { alert_click('OK') }
end
def test_02_alert_accept
- wait { open_alert }
+ open_alert
wait { alert_accept }
end
def test_03_alert_accept_text
- wait { open_alert }
- wait { assert_equal alert_accept_text, 'OK' }
+ open_alert
+ wait_true { alert_accept_text == 'OK' }
wait { alert_accept }
end
def test_04_alert_dismiss
- wait { open_alert }
+ open_alert
wait { alert_dismiss }
end
def test_05_alert_dismiss_text
- wait { open_alert }
+ open_alert
# alert dialog button placement changed:
# 'OK Cancel dialog with a long message'
# Android L: 'Something, Cancel, Ok'
# Android 19: 'Cancel, Something, Ok'
- wait { assert_equal alert_dismiss_text.downcase, 'cancel' }
+ wait_true { alert_dismiss_text.downcase == 'cancel' }
wait { alert_dismiss }
end
end
diff --git a/android_tests/lib/android/specs/common/device_touchaction.rb b/android_tests/lib/android/specs/common/device_touchaction.rb
index f2d89ff2..5a6e8e23 100644
--- a/android_tests/lib/android/specs/common/device_touchaction.rb
+++ b/android_tests/lib/android/specs/common/device_touchaction.rb
@@ -57,12 +57,20 @@ def test_04_swipe
wait { text('Animation').click }
wait { text_exact('Bouncing Balls').click }
+ # W3C actions take pixels, not ratios; avoid swiping from the system status bar.
+ size = driver.window_size
+ x = (size.width * 0.75).to_i
+ start_y = (size.height * 0.25).to_i
+ end_y = (size.height * 0.5).to_i
driver.action
- .move_to_location(0.75, 0.25).pointer_down(:left)
- .move_to_location(0.75, 50)
+ .move_to_location(x, start_y).pointer_down(:left)
+ .move_to_location(x, end_y)
.release.perform
- 3.times { back }
+ # Bouncing Balls -> Animation -> ApiDemos. A third Back exits the app.
+ back
+ wait { text_exact('Bouncing Balls') }
+ back
wait { text_exact 'NFC' }
end
diff --git a/android_tests/lib/android/specs/common/helper.rb b/android_tests/lib/android/specs/common/helper.rb
index 08640bb1..806e4e77 100644
--- a/android_tests/lib/android/specs/common/helper.rb
+++ b/android_tests/lib/android/specs/common/helper.rb
@@ -34,17 +34,16 @@ def test_01_wait
wait(wait_opts) { nil }
# failed wait should error
- assert_raises ::Appium::Core::Wait::TimeoutError do
- wait(wait_opts) { raise }
+ assert_raises RuntimeError do
+ wait(wait_opts) { raise 'wait condition failed' }
end
- # regular rescue will not handle exceptions outside of StandardError hierarchy
- # must rescue Exception explicitly to rescue everything
- assert_raises ::Appium::Core::Wait::TimeoutError do
+ # Wait helpers propagate errors outside their default retry list.
+ assert_raises NoMemoryError do
wait(wait_opts) { raise NoMemoryError }
end
- assert_raises ::Appium::Core::Wait::TimeoutError do
+ assert_raises NoMemoryError do
wait(timeout: 0.2, interval: 0.0) { raise NoMemoryError }
end
@@ -78,17 +77,16 @@ def test_03_wait_true
end
# raise should error
- assert_raises ::Appium::Core::Wait::TimeoutError do
- wait_true(wait_opts) { raise }
+ assert_raises RuntimeError do
+ wait_true(wait_opts) { raise 'wait condition failed' }
end
- # regular rescue will not handle exceptions outside of StandardError hierarchy
- # must rescue Exception explicitly to rescue everything
- assert_raises ::Appium::Core::Wait::TimeoutError do
+ # Wait helpers propagate errors outside their default retry list.
+ assert_raises NoMemoryError do
wait_true(wait_opts) { raise NoMemoryError }
end
- assert_raises ::Appium::Core::Wait::TimeoutError do
+ assert_raises NoMemoryError do
wait_true(timeout: 0.2, interval: 0.0) { raise NoMemoryError }
end
diff --git a/android_tests/lib/android/specs/common/patch.rb b/android_tests/lib/android/specs/common/patch.rb
index a2fd17d6..9d96fa8d 100644
--- a/android_tests/lib/android/specs/common/patch.rb
+++ b/android_tests/lib/android/specs/common/patch.rb
@@ -20,6 +20,20 @@
class AndroidTest
class Common
class Patch < Minitest::Test
+ include AndroidTestNavigation
+
+ def setup
+ super
+ reset_test_app
+ wait_true { text_exact('API Demos').displayed? }
+ end
+
+ def teardown
+ reset_test_app
+ ensure
+ super
+ end
+
# Attributes are busted in Android.
# Blocked on https://github.com/appium/appium/issues/628
@@ -34,11 +48,11 @@ def test_01_element_method_name
# def test_01_tag_name' do; end # Doesn't work on And
- def test_02_element_method_location_rel
+ def test_02_element_method_rect
wait do
- loc = first_text.location_rel(AppiumTestSession.driver)
- assert_equal loc.x.class, String
- assert_equal loc.y.class, String
+ rect = first_text.rect
+ assert_kind_of Numeric, rect.x
+ assert_kind_of Numeric, rect.y
end
end
@@ -59,30 +73,23 @@ def test_03_common_patch_id_error_message
end
def test_04_id_common_patch_success
- if automation_name_is_uiautomator2?
- wait do
- el = text 'text' # TextText
- assert_equal el.text, 'Text'
- end
+ wait do
+ expected = find_element(:id, 'android:id/text1')
+ assert_equal expected, id('android:id/text1')
end
end
def test_05_find_many_elements_by_resource_id
- wait do
+ wait(ignored: [Minitest::Assertion, Selenium::WebDriver::Error::NoSuchElementError]) do
value = find_elements(:id, 'android:id/text1').length
- assert_equal value, 12
+ assert_equal 12, value
end
end
def test_06_find_single_element_by_resource_id
- wait do
+ wait(ignored: [Minitest::Assertion, Selenium::WebDriver::Error::NoSuchElementError]) do
value = id('android:id/text1').text
- assert_equal value, "Access'ibility"
+ assert_equal "Access'ibility", value
end
end
end
diff --git a/android_tests/lib/android/specs/common/web_context.rb b/android_tests/lib/android/specs/common/web_context.rb
index 80b933a1..e252df59 100644
--- a/android_tests/lib/android/specs/common/web_context.rb
+++ b/android_tests/lib/android/specs/common/web_context.rb
@@ -17,46 +17,43 @@
class AndroidTest
class Common
class WebContext < Minitest::Test
- # appium's context support is broken on android
+ include AndroidTestNavigation
+
+ def setup
+ super
+ reset_test_app
+ end
+
+ def teardown
+ reset_test_app
+ ensure
+ super
+ end
def test_01_available_contexts
wait_true { available_contexts.include? 'NATIVE_APP' }
end
def test_02_current_context
- wait { assert_equal current_context, 'NATIVE_APP' }
- end
-
- def undo_setcontext_nav
- back
- wait { find('WebView') }
- back
- wait { find 'Views' }
+ assert_equal 'NATIVE_APP', current_context
end
def test_03_set_context
- wait { scroll_to('Views').click }
- wait { scroll_to('WebView').click }
-
- wait_true { !available_contexts.detect { |e| e.start_with?('WEBVIEW') }.nil? }
+ wait { scroll_to_exact('Views') }.click
+ wait { scroll_to_exact('WebView') }.click
- webview_context = available_contexts.detect { |e| e.start_with?('WEBVIEW') }
-
- if webview_context.nil?
- undo_setcontext_nav
- raise "No webview context found. contexts are: #{contexts}"
+ webview_context = wait_true do
+ available_contexts.find { |context| context.start_with?('WEBVIEW') }
end
- wait { set_context webview_context }
- wait { assert_equal current_context, webview_context }
+ set_context webview_context
+ wait_true { current_context == webview_context }
# verify inspect within webview works
assert get_android_inspect.split("\n").length >= 3
- wait { set_context 'NATIVE_APP' }
- wait { assert_equal current_context, 'NATIVE_APP' }
-
- undo_setcontext_nav
+ set_context 'NATIVE_APP'
+ wait_true { current_context == 'NATIVE_APP' }
end
end
end
diff --git a/android_tests/lib/run.rb b/android_tests/lib/run.rb
index 4634c016..eaeac329 100644
--- a/android_tests/lib/run.rb
+++ b/android_tests/lib/run.rb
@@ -80,6 +80,7 @@ def start_driver(caps)
caps[:caps][:app] = ENV['IOS_APP'] if ENV['IOS_APP']
caps[:caps][:platformVersion] = ENV['IOS_VERSION'] if ENV['IOS_VERSION']
caps[:caps][:deviceName] = ENV['IOS_DEVICE_NAME'] if ENV['IOS_DEVICE_NAME']
+ caps[:caps][:udid] = ENV['IOS_UDID'] if ENV['IOS_UDID']
end
if ENV['LOCAL_PREBUILT_WDA']
diff --git a/appium_lib.gemspec b/appium_lib.gemspec
index bfefb0ed..0d54334e 100644
--- a/appium_lib.gemspec
+++ b/appium_lib.gemspec
@@ -16,7 +16,7 @@ Gem::Specification.new do |s|
s.homepage = 'https://github.com/appium/ruby_lib' # published as appium_lib
s.require_paths = ['lib']
- s.add_dependency 'appium_lib_core', '>= 13.0.0', '< 14.0'
+ s.add_dependency 'appium_lib_core', '>= 14.0.0', '< 15.0'
s.add_dependency 'nokogiri', '~> 1.8', '>= 1.8.1'
s.add_dependency 'ostruct', '~> 0.6'
s.add_dependency 'tomlrb', '>= 1.1', '< 4.0'
diff --git a/docs/docs.md b/docs/docs.md
index a9477c99..e9d8c61c 100644
--- a/docs/docs.md
+++ b/docs/docs.md
@@ -71,7 +71,7 @@ e.tag_name # calls .type (patch.rb)
e.text
e.size
e.location
-e.location_rel
+e.rect # position and size; location_rel was removed in core 14
e.click
e.send_keys 'keys to send'
e.displayed? # true or false depending if the element is visible
diff --git a/ios_tests/lib/ios/specs/common/helper.rb b/ios_tests/lib/ios/specs/common/helper.rb
index 0377624a..5634013e 100644
--- a/ios_tests/lib/ios/specs/common/helper.rb
+++ b/ios_tests/lib/ios/specs/common/helper.rb
@@ -40,17 +40,16 @@ def test_02_wait
wait(@wait_opts) { nil }
# failed wait should error
- assert_raises ::Appium::Core::Wait::TimeoutError do
- wait(@wait_opts) { raise }
+ assert_raises RuntimeError do
+ wait(@wait_opts) { raise 'wait condition failed' }
end
- # regular rescue will not handle exceptions outside of StandardError hierarchy
- # must rescue Exception explicitly to rescue everything
- assert_raises ::Appium::Core::Wait::TimeoutError do
+ # Wait helpers propagate errors outside their default retry list.
+ assert_raises NoMemoryError do
wait(@wait_opts) { raise NoMemoryError }
end
- assert_raises ::Appium::Core::Wait::TimeoutError do
+ assert_raises NoMemoryError do
wait(timeout: 0.2, interval: 0.0) { raise NoMemoryError }
end
e = assert_raises ArgumentError do
@@ -82,16 +81,15 @@ def test_04_wait_true
end
# raise should error
- assert_raises ::Appium::Core::Wait::TimeoutError do
- wait_true(@wait_opts) { raise }
+ assert_raises RuntimeError do
+ wait_true(@wait_opts) { raise 'wait condition failed' }
end
- # regular rescue will not handle exceptions outside of StandardError hierarchy
- # must rescue Exception explicitly to rescue everything
- assert_raises ::Appium::Core::Wait::TimeoutError do
+ # Wait helpers propagate errors outside their default retry list.
+ assert_raises NoMemoryError do
wait_true(@wait_opts) { raise NoMemoryError }
end
- assert_raises ::Appium::Core::Wait::TimeoutError do
+ assert_raises NoMemoryError do
wait_true(timeout: 0.2, interval: 0.0) { raise NoMemoryError }
end
diff --git a/ios_tests/lib/ios/specs/common/patch.rb b/ios_tests/lib/ios/specs/common/patch.rb
index 5ee0e284..3178b17d 100644
--- a/ios_tests/lib/ios/specs/common/patch.rb
+++ b/ios_tests/lib/ios/specs/common/patch.rb
@@ -31,10 +31,10 @@ def test_02_appium_core_element_method_name
assert_equal first_text.name, 'UICatalog'
end
- def test_03_appium_core_element_method_location_rel
- loc = first_text.location_rel(AppiumTestSession.driver)
- assert_equal loc.x.class, String
- assert_equal loc.y.class, String
+ def test_03_appium_core_element_method_rect
+ rect = first_text.rect
+ assert_kind_of Numeric, rect.x
+ assert_kind_of Numeric, rect.y
end
end
end
diff --git a/ios_tests/lib/ios/specs/device/device.rb b/ios_tests/lib/ios/specs/device/device.rb
index 18c22fb1..b6b5b70b 100644
--- a/ios_tests/lib/ios/specs/device/device.rb
+++ b/ios_tests/lib/ios/specs/device/device.rb
@@ -17,6 +17,8 @@
class IosTest
class Device
class Device < Minitest::Test
+ include IosTestNavigation
+
# go back to the main page
def go_back
back
@@ -40,10 +42,10 @@ def test_03_background_app_homescreen
background_app(-1) # background_app(nil) should work as same.
# The app goes to background and never come back
- wait do
- assert_equal driver.app_state(bundle_id), :running_in_background_suspended
+ wait_true do
+ %i[running_in_background running_in_background_suspended].include?(driver.app_state(bundle_id))
end
-
+ ensure
driver.activate_app bundle_id
end
@@ -54,9 +56,13 @@ def test_04_app_strings
def test_05_action_chain
element = text('Buttons')
- one_finger_tap x: 0, y: 0, element: element
+ rect = element.rect
+ one_finger_tap x: rect.width / 2, y: rect.height / 2, element: element
- wait { button 'UICatalog' } # successfully transitioned to buttons page
+ wait_true(ignored: [Selenium::WebDriver::Error::NoSuchElementError,
+ Selenium::WebDriver::Error::StaleElementReferenceError]) do
+ screen == 'Buttons' && button('UICatalog').displayed?
+ end
go_back
end
diff --git a/ios_tests/lib/ios/specs/ios/command/multi_app_handler.rb b/ios_tests/lib/ios/specs/ios/command/multi_app_handler.rb
index e395c67a..68a389fd 100644
--- a/ios_tests/lib/ios/specs/ios/command/multi_app_handler.rb
+++ b/ios_tests/lib/ios/specs/ios/command/multi_app_handler.rb
@@ -31,15 +31,16 @@ def test_multi_app_handler
assert_equal :running_in_foreground, xcuitest_query_app_status(bundle_id: test_app_bundle)
assert xcuitest_activate_app(bundle_id: 'com.apple.Preferences').nil?
- wait(timeout: 5) do
+ wait_true(timeout: 5) do
# iOS may suspend the background app before we observe its state.
- assert_includes %i[running_in_background running_in_background_suspended],
- xcuitest_query_app_status(bundle_id: test_app_bundle)
+ %i[running_in_background running_in_background_suspended].include?(
+ xcuitest_query_app_status(bundle_id: test_app_bundle)
+ )
end
assert xcuitest_activate_app(bundle_id: test_app_bundle).nil?
- wait(timeout: 5) do
- assert_equal :running_in_foreground, xcuitest_query_app_status(bundle_id: test_app_bundle)
+ wait_true(timeout: 5) do
+ xcuitest_query_app_status(bundle_id: test_app_bundle) == :running_in_foreground
end
end
end
diff --git a/ios_tests/lib/ios/specs/ios/command/pasteboard.rb b/ios_tests/lib/ios/specs/ios/command/pasteboard.rb
index ef2fb430..15f2b3dd 100644
--- a/ios_tests/lib/ios/specs/ios/command/pasteboard.rb
+++ b/ios_tests/lib/ios/specs/ios/command/pasteboard.rb
@@ -21,13 +21,13 @@ def test_pasteboard
driver.terminate_app target_bundle_id
driver.activate_app target_bundle_id
- # set blank before testing because pasteboard is remaining during launching simulators
+ # Replace any content left by an earlier Simulator session and wait for it to be readable.
set_pasteboard content: 'before'
- assert_equal get_pasteboard, 'before'
+ wait_true { get_pasteboard == 'before' }
set_pasteboard content: 'sample content'
- assert_equal get_pasteboard, 'sample content'
+ wait_true { get_pasteboard == 'sample content' }
end
end
end
diff --git a/ios_tests/lib/ios/specs/ios/element/button.rb b/ios_tests/lib/ios/specs/ios/element/button.rb
index cd7c7d8b..bd5e9f88 100644
--- a/ios_tests/lib/ios/specs/ios/element/button.rb
+++ b/ios_tests/lib/ios/specs/ios/element/button.rb
@@ -23,6 +23,10 @@ def before_first
assert_equal screen, catalog
# nav to buttons activity
wait { find_element(:name, 'Buttons').click }
+ wait_true(ignored: [Selenium::WebDriver::Error::NoSuchElementError,
+ Selenium::WebDriver::Error::StaleElementReferenceError]) do
+ screen == 'Buttons' && button_exact('UIAccessoryButtonPlus').displayed?
+ end
end
def after_last
@@ -38,19 +42,26 @@ def test_01_before_first
end
def test_02_button
- # by index
- assert_equal button(3).name, 'UIAccessoryButtonPlus'
+ wait(ignored: [Minitest::Assertion, Selenium::WebDriver::Error::NoSuchElementError,
+ Selenium::WebDriver::Error::StaleElementReferenceError]) do
+ # Reacquire the elements on every attempt while the view settles.
+ # by index
+ assert_equal 'UIAccessoryButtonPlus', button(3).name
- # by name contains
- assert_equal button('Plus').name, 'UIAccessoryButtonPlus'
+ # by name contains
+ assert_equal 'UIAccessoryButtonPlus', button('Plus').name
+ end
end
def test_03_buttons
exp = %w(UICatalog UIAccessoryButtonPlus)
- target_buttons = buttons('a')
- assert_equal target_buttons.map(&:name), exp
- assert_equal target_buttons.length, exp.length
+ wait(ignored: [Minitest::Assertion, Selenium::WebDriver::Error::NoSuchElementError,
+ Selenium::WebDriver::Error::StaleElementReferenceError]) do
+ target_buttons = buttons('a')
+ assert_equal exp, target_buttons.map(&:name)
+ assert_equal exp.length, target_buttons.length
+ end
end
def test_04_first_button
diff --git a/ios_tests/lib/ios/specs/ios/xcuitest_gestures.rb b/ios_tests/lib/ios/specs/ios/xcuitest_gestures.rb
index 9ed58561..b0364454 100644
--- a/ios_tests/lib/ios/specs/ios/xcuitest_gestures.rb
+++ b/ios_tests/lib/ios/specs/ios/xcuitest_gestures.rb
@@ -45,19 +45,28 @@ def test_double_tap
def test_touch_and_hold
open_screen 'Buttons'
- element = button_exact('Button')
+ retryable_errors = [Selenium::WebDriver::Error::NoSuchElementError,
+ Selenium::WebDriver::Error::StaleElementReferenceError]
+ element = wait_true(ignored: retryable_errors) do
+ candidate = button_exact('Button')
+ candidate if candidate.displayed?
+ end
touch_and_hold(element: element, duration: 1.0)
- rect = element.rect
+ rect = wait_true(ignored: retryable_errors) do
+ candidate = button_exact('Button')
+ candidate.rect if candidate.displayed?
+ end
touch_and_hold(x: rect.x + rect.width / 2, y: rect.y + rect.height / 2)
assert_equal 'Buttons', screen
end
def test_swipe
- table = find_element(:class_name, ui_ios.table)
- 2.times { swipe direction: 'up', element: table }
- wait_true { find_element(:accessibility_id, 'Toolbars').displayed? }
- 2.times { swipe direction: 'down', element: table }
- wait_true { find_element(:accessibility_id, 'Activity Indicators').displayed? }
+ [['up', 'Toolbars'], ['down', 'Activity Indicators']].each do |direction, target|
+ wait_true do
+ swipe direction: direction, element: find_element(:class_name, ui_ios.table)
+ find_element(:accessibility_id, target).displayed?
+ end
+ end
end
def test_drag_from_to_for_duration
diff --git a/lib/appium_lib/common/wait.rb b/lib/appium_lib/common/wait.rb
index 9ac43924..8a1bf825 100644
--- a/lib/appium_lib/common/wait.rb
+++ b/lib/appium_lib/common/wait.rb
@@ -34,13 +34,22 @@ class Wait
# @option opts [Numeric] :timeout Seconds to wait before timing out. Set default by `appium_wait_timeout` (30).
# @option opts [Numeric] :interval Seconds to sleep between polls. Set default by `appium_wait_interval` (0.5).
# @option opts [String] :message Exception message if timed out.
- # @option opts [Array, Exception] :ignore Exceptions to ignore while polling (default: Exception)
+ # @option opts [Array, Class] :ignored Exceptions to retry (default: Selenium::WebDriver::Error::NoSuchElementError)
#
# @example
#
# wait_true(timeout: 20, interval: 0.2, message: 'custom message') { button_exact('Back') }.click
# wait_true(20) { button_exact('Back') }.click
#
+ # @example Retrying Minitest assertions with core 14+
+ #
+ # # Assertion failures propagate immediately by default.
+ # # ignored replaces the default list; include NoSuchElementError to keep retrying missing elements.
+ # wait_true(ignored: [Minitest::Assertion, Selenium::WebDriver::Error::NoSuchElementError]) do
+ # assert_equal 'Ready', find_element(:accessibility_id, 'status').text
+ # true # wait_true requires a truthy result after the assertion succeeds.
+ # end
+ #
def wait_true(opts = {})
opts = { timeout: opts } if opts.is_a? Numeric
@@ -63,13 +72,23 @@ def wait_true(opts = {})
# @option opts [Numeric] :timeout Seconds to wait before timing out. Set default by `appium_wait_timeout` (30).
# @option opts [Numeric] :interval Seconds to sleep between polls. Set default by `appium_wait_interval` (0.5).
# @option opts [String] :message Exception message if timed out.
- # @option opts [Array, Exception] :ignore Exceptions to ignore while polling (default: Exception)
+ # @option opts [Array, Class] :ignored Exceptions to retry (default: Selenium::WebDriver::Error::NoSuchElementError)
#
# @example
#
# wait(timeout: 20, interval: 0.2, message: 'custom message') { button_exact('Back') }.click
# wait(20) { button_exact('Back') }.click
#
+ # @example Retrying Minitest assertions with core 14+
+ #
+ # # This fails immediately if the assertion fails; it no longer retries automatically.
+ # wait { assert_equal 'Ready', find_element(:accessibility_id, 'status').text }
+ #
+ # # ignored replaces the default list; include NoSuchElementError to keep retrying missing elements.
+ # wait(ignored: [Minitest::Assertion, Selenium::WebDriver::Error::NoSuchElementError]) do
+ # assert_equal 'Ready', find_element(:accessibility_id, 'status').text
+ # end
+ #
def wait(opts = {})
opts = { timeout: opts } if opts.is_a? Numeric
if opts.is_a? Hash
diff --git a/lib/appium_lib/driver.rb b/lib/appium_lib/driver.rb
index 62363b0f..78f9f7fd 100644
--- a/lib/appium_lib/driver.rb
+++ b/lib/appium_lib/driver.rb
@@ -48,7 +48,7 @@ class Driver
# `ruby_lib_core` (see appium/ruby_lib_core#97). Defining them here lets
# `ruby_lib_core` eventually drop that list.
CORE_BRIDGE_METHODS = %i[
- take_element_screenshot save_viewport_screenshot
+ save_element_screenshot save_viewport_screenshot
lock device_locked? unlock
hide_keyboard is_keyboard_shown
ime_activate ime_available_engines ime_active_engine ime_activated ime_deactivate
@@ -208,15 +208,17 @@ def initialize(opts = {}, global_driver = nil)
$driver&.driver_quit if global_driver
+ opts = opts.transform_keys { |key| key.is_a?(String) ? key.to_sym : key }
+ appium_lib_opts = (opts[:appium_lib] || {}).transform_keys { |key| key.is_a?(String) ? key.to_sym : key }
+ opts[:appium_lib] = appium_lib_opts
@core = ::Appium::Core.for(opts)
extend ::Appium::Core::Device
- opts = Appium.symbolize_keys opts
- appium_lib_opts = opts[:appium_lib] || {}
-
@caps = @core.caps
@custom_url = @core.custom_url
- @default_wait = @core.default_wait || 0
+ # Core 14 no longer manages implicit waits; keep the wrapper's wait option.
+ @implicit_wait = appium_lib_opts[:wait]
+ @default_wait = @implicit_wait || 0
@appium_port = @core.port
@appium_wait_timeout = @core.wait_timeout
@appium_wait_interval = @core.wait_interval
@@ -490,10 +492,15 @@ def screenshot(png_save_path)
# @param [String] png_save_path the full path to save the png
# @return [File]
def element_screenshot(element, png_save_path)
- @driver&.take_element_screenshot element, png_save_path
+ @driver&.save_element_screenshot element, png_save_path
nil
end
+ # Compatibility name retained by appium_lib after its removal from core 14.
+ def take_element_screenshot(element, png_save_path)
+ save_element_screenshot(element, png_save_path)
+ end
+
# Quits the driver
# @return [void]
def driver_quit
@@ -590,6 +597,7 @@ def start_driver(http_client_ops = { http_client: nil, open_timeout: 999_999, re
read_timeout: 999_999
})
@http_client = @core.http_client
+ set_implicit_wait(@implicit_wait) unless @implicit_wait.nil?
# if automation_name was nil before start_driver, then re-extend driver specific methods
# to be able to extend correctly.
@@ -600,14 +608,15 @@ def start_driver(http_client_ops = { http_client: nil, open_timeout: 999_999, re
@driver
end
- # To ignore error for Espresso Driver
+ # Preserve core 13's handling of drivers without implicit-wait support.
def set_implicit_wait(wait)
@driver.manage.timeouts.implicit_wait = wait
rescue Selenium::WebDriver::Error::UnknownError => e
- unless e.message.include?('The operation requested is not yet implemented by Espresso driver')
- raise ::Appium::Core::Error::ServerError
+ unless e.message.include?('The operation requested is not yet implemented')
+ raise ::Appium::Core::Error::ServerError, e.message
end
+ ::Appium::Logger.debug(e.message)
{}
end
diff --git a/test/core_14_test.rb b/test/core_14_test.rb
new file mode 100644
index 00000000..5c97d492
--- /dev/null
+++ b/test/core_14_test.rb
@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require 'appium_lib'
+
+class Core14Test < Minitest::Test
+ class Session
+ attr_reader :waits, :screenshots
+
+ def initialize
+ @waits = []
+ @screenshots = []
+ end
+
+ def manage = self
+ def timeouts = self
+
+ def implicit_wait=(value)
+ @waits << value
+ end
+
+ def save_element_screenshot(element, path)
+ @screenshots << [element, path]
+ :saved
+ end
+
+ def quit; end
+ end
+
+ def build(options = {})
+ Appium::Driver.new({ caps: { platformName: 'Android', automationName: 'UiAutomator2' },
+ appium_lib: { debug: false }.merge(options) })
+ end
+
+ def attach_session(wrapper, session)
+ wrapper.core.define_singleton_method(:start_driver) { |**_options| session }
+ wrapper.define_singleton_method(:appium_server_version) { {} }
+ wrapper.start_driver
+ end
+
+ def test_string_options_without_converting_capabilities_or_mutating_input
+ caps = { 'platformName' => 'Android', 'appium:automationName' => 'UiAutomator2',
+ 'appium:settings' => { 'ignoreUnimportantViews' => true }.freeze }.freeze
+ options = { 'caps' => caps, 'appium_lib' => { 'debug' => false, 'wait' => 2 }.freeze }.freeze
+ wrapper = Appium::Driver.new(options)
+
+ assert_equal 2, wrapper.default_wait
+ assert_equal :android, wrapper.appium_device
+ assert_equal caps, wrapper.caps.as_json
+ assert_equal %w[caps appium_lib], options.keys
+ assert_equal %w[debug wait], options['appium_lib'].keys
+ end
+
+ def test_configured_implicit_wait_is_applied_to_each_new_session
+ wrapper = build(wait: 2)
+ first = Session.new
+ replacement = Session.new
+ assert_same first, attach_session(wrapper, first)
+ assert_same replacement, attach_session(wrapper, replacement)
+ assert_equal [2], first.waits
+ assert_equal [2], replacement.waits
+ assert_equal 2, wrapper.default_wait
+ wrapper.no_wait
+ wrapper.set_wait
+ assert_equal [2, 0, 2], replacement.waits
+ end
+
+ def test_explicit_zero_wait_is_applied
+ wrapper = build(wait: 0)
+ session = Session.new
+ attach_session(wrapper, session)
+ assert_equal [0], session.waits
+ end
+
+ def test_session_start_tolerates_unimplemented_implicit_wait
+ ['The operation requested is not yet implemented',
+ 'The operation requested is not yet implemented by Espresso driver'].each do |message|
+ wrapper = build(wait: 2)
+ session = Session.new
+ session.define_singleton_method(:implicit_wait=) do |_value|
+ raise Selenium::WebDriver::Error::UnknownError, message
+ end
+
+ assert_same session, attach_session(wrapper, session)
+ assert_same session, wrapper.driver
+ end
+ end
+
+ def test_session_start_preserves_other_implicit_wait_errors
+ wrapper = build(wait: 2)
+ session = Session.new
+ original = Selenium::WebDriver::Error::UnknownError.new('Timeout configuration failed')
+ session.define_singleton_method(:implicit_wait=) { |_value| raise original }
+
+ error = assert_raises(Appium::Core::Error::ServerError) { attach_session(wrapper, session) }
+ assert_equal original.message, error.message
+ assert_same original, error.cause
+ end
+
+ def test_absent_or_nil_wait_does_not_send_a_timeout_command
+ [{}, { wait: nil }].each do |options|
+ wrapper = build(options)
+ session = Session.new
+ attach_session(wrapper, session)
+ assert_empty session.waits
+ assert_equal 0, wrapper.default_wait
+ end
+ end
+
+ def test_screenshot_helpers_use_supported_core_method
+ wrapper = build
+ session = Session.new
+ attach_session(wrapper, session)
+ element = Object.new
+ assert_nil wrapper.element_screenshot(element, 'element.png')
+ assert_equal :saved, wrapper.take_element_screenshot(element, 'legacy.png')
+ assert_equal :saved, wrapper.save_element_screenshot(element, 'saved.png')
+ assert_equal [[element, 'element.png'], [element, 'legacy.png'], [element, 'saved.png']], session.screenshots
+ end
+
+ def test_wait_helpers_retry_missing_elements
+ wrapper = build
+ %i[wait wait_true].each do |method|
+ attempts = 0
+ result = wrapper.public_send(method, timeout: 1, interval: 0) do
+ attempts += 1
+ raise Selenium::WebDriver::Error::NoSuchElementError if attempts == 1
+
+ :found
+ end
+ assert_equal :found, result
+ assert_equal 2, attempts
+ end
+ end
+
+ def test_wait_helpers_propagate_programming_errors_and_interruptions
+ wrapper = build
+ %i[wait wait_true].each do |method|
+ [NoMethodError, Interrupt, SystemExit].each do |error|
+ assert_raises(error) { wrapper.public_send(method, timeout: 1, interval: 0) { raise error } }
+ end
+ end
+ end
+
+ def test_wait_helpers_accept_explicit_retry_exceptions
+ wrapper = build
+ %i[wait wait_true].each do |method|
+ attempts = 0
+ result = wrapper.public_send(method, timeout: 1, interval: 0, ignored: [RuntimeError]) do
+ attempts += 1
+ raise 'transient failure' if attempts == 1
+
+ :ready
+ end
+ assert_equal :ready, result
+ assert_equal 2, attempts
+ assert_raises(Selenium::WebDriver::Error::NoSuchElementError) do
+ wrapper.public_send(method, timeout: 1, ignored: []) { raise Selenium::WebDriver::Error::NoSuchElementError }
+ end
+ end
+ end
+
+ def test_numeric_timeout_and_wait_success_semantics
+ wrapper = build
+ assert_equal false, wrapper.wait(1) { false }
+ assert_nil wrapper.wait(1) { nil }
+ assert_equal :ready, wrapper.wait_true(1) { :ready }
+ assert_raises(Appium::Core::Wait::TimeoutError) { wrapper.wait_true(timeout: 0.001, interval: 0) { false } }
+ end
+
+ def test_promoted_wait_helpers_propagate_explicit_errors_and_retry_assertions
+ target = Class.new(Minitest::Test)
+ Appium.promote_appium_methods(target, build)
+ page = target.new('promoted_wait')
+
+ %i[wait wait_true].each do |method|
+ error = assert_raises(RuntimeError) do
+ page.public_send(method, timeout: 1) { raise 'wait condition failed' }
+ end
+ assert_equal 'wait condition failed', error.message
+
+ attempts = 0
+ result = page.public_send(method, timeout: 1, interval: 0, ignored: [Minitest::Assertion]) do
+ attempts += 1
+ raise Minitest::Assertion, 'not ready' if attempts == 1
+
+ true
+ end
+ assert result
+ assert_equal 2, attempts
+ end
+ end
+end