Skip to content

Commit 727f986

Browse files
authored
feat!: upgrade appium_lib_core to 14 (#1151)
* feat: bump the core version to 14 * add exmaples for wait * docs: move core 14 migration guide to changelog * docs: keep unreleased migration notes outside release headings * test: adapt functional waits and isolate UI state for core 14 * test: wait for alerts and pasteboard and pin booted iOS simulator * test: restore Android context after failures and correct swipe navigation * test: use pixel swipe coordinates and wait for stable iOS buttons * fix: preserve implicit wait compatibility and retry iOS element lookup
1 parent 0b1fa03 commit 727f986

21 files changed

Lines changed: 416 additions & 121 deletions

File tree

‎.github/workflows/functional-test.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,12 @@ jobs:
4444
- run: defaults write com.apple.iphonesimulator PasteboardAutomaticSync -bool false
4545

4646
- uses: futureware-tech/simulator-action@v6
47+
id: simulator
4748
with:
4849
# https://github.com/actions/runner-images/blob/main/images/macos/macos-14-arm64-Readme.md
4950
model: ${{ env.IOS_DEVICE_NAME }}
5051
os_version: ${{ env.IOS_VERSION }}
52+
wait_for_boot: true
5153

5254
- name: Preparing other environment
5355
run: |
@@ -79,6 +81,7 @@ jobs:
7981
timeout-minutes: 60
8082
working-directory: ios_tests
8183
env:
84+
IOS_UDID: ${{ steps.simulator.outputs.udid }}
8285
LOCAL_PREBUILT_WDA: ${{ github.workspace }}/wda/WebDriverAgentRunner-Runner.app
8386
8487
- name: Save server output

‎CHANGELOG.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,34 @@ New entries are maintained by Release Please.
44

55
Release tags are https://github.com/appium/ruby_lib/releases .
66

7+
### Upgrading to core 14 (unreleased)
8+
9+
This library requires `appium_lib_core >= 14.0.0, < 15.0`.
10+
11+
- `wait` and `wait_true` now retry only `Selenium::WebDriver::Error::NoSuchElementError`
12+
by default. Other errors, including assertion failures and interruptions, propagate
13+
immediately. Use `ignored: [SomeTransientError]` to choose retryable exceptions;
14+
this replaces the default list. Use `ignored: []` to disable exception retries.
15+
`wait` still accepts false or nil results, while `wait_true` requires a truthy result.
16+
- `Appium::Driver` continues to support `appium_lib: { wait: seconds }`, `default_wait`,
17+
`no_wait`, and `set_wait`. The wrapper applies a configured implicit wait after each
18+
session starts. Without that option, it sends no implicit-timeout command.
19+
Direct `Appium::Core` users must configure `driver.manage.timeouts.implicit_wait`
20+
themselves. `wait_timeout` controls explicit waits, not implicit waits.
21+
- `element_screenshot` and `take_element_screenshot` remain available on
22+
`Appium::Driver`; they now use core's `save_element_screenshot`.
23+
- Replace `element.location_rel(driver)` with `element.rect`. To calculate the
24+
center relative to the window, use `(rect.x + rect.width / 2.0) / window.width`
25+
and `(rect.y + rect.height / 2.0) / window.height`.
26+
- `Appium.symbolize_keys` is removed. Use symbol keys for client options or Ruby's
27+
`transform_keys(&:to_sym)` where appropriate. The wrapper accepts string client
28+
option keys without converting capability keys or nested capability values.
29+
- Custom server responses must use the W3C element key
30+
`element-6066-11e4-a52e-4f735466cecf`; legacy `ELEMENT` references are no longer supported.
31+
32+
See the [core 14 migration notes](https://github.com/appium/ruby_lib_core/blob/v14.0.0/CHANGELOG.md)
33+
for changes affecting direct core API usage.
34+
735
## [16.5.1](https://github.com/appium/ruby_lib/compare/v16.5.0...v16.5.1) (2026-11-06)
836

937

‎android_tests/lib/android/navigation.rb‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ def start_test_activity(component)
1212
end
1313

1414
def reset_test_app
15+
AppiumTestSession.driver.set_context 'NATIVE_APP'
1516
start_test_activity('io.appium.android.apis/.ApiDemos')
17+
AppiumTestSession.driver.wait_true do
18+
AppiumTestSession.driver.text_exact('NFC').displayed?
19+
end
1620
end
1721
end

‎android_tests/lib/android/specs/android/element/alert.rb‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -32,41 +32,44 @@ def teardown
3232
end
3333

3434
def open_alert
35-
# trigger the alert
35+
# Click once, then wait for the dialog rather than matching its launch button again.
3636
wait { button('OK Cancel dialog with a message').click }
37+
wait_true do
38+
button_exact('OK').displayed? && button_exact('Cancel').displayed?
39+
end
3740
end
3841

3942
def test_01_alert_click
4043
# test
41-
wait { open_alert }
44+
open_alert
4245
wait { alert_click('OK') }
4346
end
4447

4548
def test_02_alert_accept
46-
wait { open_alert }
49+
open_alert
4750
wait { alert_accept }
4851
end
4952

5053
def test_03_alert_accept_text
51-
wait { open_alert }
52-
wait { assert_equal alert_accept_text, 'OK' }
54+
open_alert
55+
wait_true { alert_accept_text == 'OK' }
5356
wait { alert_accept }
5457
end
5558

5659
def test_04_alert_dismiss
57-
wait { open_alert }
60+
open_alert
5861
wait { alert_dismiss }
5962
end
6063

6164
def test_05_alert_dismiss_text
62-
wait { open_alert }
65+
open_alert
6366

6467
# alert dialog button placement changed:
6568
# 'OK Cancel dialog with a long message'
6669
# Android L: 'Something, Cancel, Ok'
6770
# Android 19: 'Cancel, Something, Ok'
6871

69-
wait { assert_equal alert_dismiss_text.downcase, 'cancel' }
72+
wait_true { alert_dismiss_text.downcase == 'cancel' }
7073
wait { alert_dismiss }
7174
end
7275
end

‎android_tests/lib/android/specs/common/device_touchaction.rb‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,12 +57,20 @@ def test_04_swipe
5757
wait { text('Animation').click }
5858
wait { text_exact('Bouncing Balls').click }
5959

60+
# W3C actions take pixels, not ratios; avoid swiping from the system status bar.
61+
size = driver.window_size
62+
x = (size.width * 0.75).to_i
63+
start_y = (size.height * 0.25).to_i
64+
end_y = (size.height * 0.5).to_i
6065
driver.action
61-
.move_to_location(0.75, 0.25).pointer_down(:left)
62-
.move_to_location(0.75, 50)
66+
.move_to_location(x, start_y).pointer_down(:left)
67+
.move_to_location(x, end_y)
6368
.release.perform
6469

65-
3.times { back }
70+
# Bouncing Balls -> Animation -> ApiDemos. A third Back exits the app.
71+
back
72+
wait { text_exact('Bouncing Balls') }
73+
back
6674
wait { text_exact 'NFC' }
6775
end
6876

‎android_tests/lib/android/specs/common/helper.rb‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -34,17 +34,16 @@ def test_01_wait
3434
wait(wait_opts) { nil }
3535

3636
# failed wait should error
37-
assert_raises ::Appium::Core::Wait::TimeoutError do
38-
wait(wait_opts) { raise }
37+
assert_raises RuntimeError do
38+
wait(wait_opts) { raise 'wait condition failed' }
3939
end
4040

41-
# regular rescue will not handle exceptions outside of StandardError hierarchy
42-
# must rescue Exception explicitly to rescue everything
43-
assert_raises ::Appium::Core::Wait::TimeoutError do
41+
# Wait helpers propagate errors outside their default retry list.
42+
assert_raises NoMemoryError do
4443
wait(wait_opts) { raise NoMemoryError }
4544
end
4645

47-
assert_raises ::Appium::Core::Wait::TimeoutError do
46+
assert_raises NoMemoryError do
4847
wait(timeout: 0.2, interval: 0.0) { raise NoMemoryError }
4948
end
5049

@@ -78,17 +77,16 @@ def test_03_wait_true
7877
end
7978

8079
# raise should error
81-
assert_raises ::Appium::Core::Wait::TimeoutError do
82-
wait_true(wait_opts) { raise }
80+
assert_raises RuntimeError do
81+
wait_true(wait_opts) { raise 'wait condition failed' }
8382
end
8483

85-
# regular rescue will not handle exceptions outside of StandardError hierarchy
86-
# must rescue Exception explicitly to rescue everything
87-
assert_raises ::Appium::Core::Wait::TimeoutError do
84+
# Wait helpers propagate errors outside their default retry list.
85+
assert_raises NoMemoryError do
8886
wait_true(wait_opts) { raise NoMemoryError }
8987
end
9088

91-
assert_raises ::Appium::Core::Wait::TimeoutError do
89+
assert_raises NoMemoryError do
9290
wait_true(timeout: 0.2, interval: 0.0) { raise NoMemoryError }
9391
end
9492

‎android_tests/lib/android/specs/common/patch.rb‎

Lines changed: 25 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,20 @@
2020
class AndroidTest
2121
class Common
2222
class Patch < Minitest::Test
23+
include AndroidTestNavigation
24+
25+
def setup
26+
super
27+
reset_test_app
28+
wait_true { text_exact('API Demos').displayed? }
29+
end
30+
31+
def teardown
32+
reset_test_app
33+
ensure
34+
super
35+
end
36+
2337
# Attributes are busted in Android.
2438
# Blocked on https://github.com/appium/appium/issues/628
2539

@@ -34,11 +48,11 @@ def test_01_element_method_name
3448

3549
# def test_01_tag_name' do; end # Doesn't work on And
3650

37-
def test_02_element_method_location_rel
51+
def test_02_element_method_rect
3852
wait do
39-
loc = first_text.location_rel(AppiumTestSession.driver)
40-
assert_equal loc.x.class, String
41-
assert_equal loc.y.class, String
53+
rect = first_text.rect
54+
assert_kind_of Numeric, rect.x
55+
assert_kind_of Numeric, rect.y
4256
end
4357
end
4458

@@ -59,30 +73,23 @@ def test_03_common_patch_id_error_message
5973
end
6074

6175
def test_04_id_common_patch_success
62-
if automation_name_is_uiautomator2?
63-
wait do
64-
el = text 'text' # <string name="autocomplete_3_button_7">Text</str
65-
assert_equal el.text, 'Text'
66-
end
67-
else
68-
wait do
69-
el = id 'autocomplete_3_button_7' # <string name="autocomplete_3_button_7">Text</string>
70-
assert_equal el.text, 'Text'
71-
end
76+
wait do
77+
expected = find_element(:id, 'android:id/text1')
78+
assert_equal expected, id('android:id/text1')
7279
end
7380
end
7481

7582
def test_05_find_many_elements_by_resource_id
76-
wait do
83+
wait(ignored: [Minitest::Assertion, Selenium::WebDriver::Error::NoSuchElementError]) do
7784
value = find_elements(:id, 'android:id/text1').length
78-
assert_equal value, 12
85+
assert_equal 12, value
7986
end
8087
end
8188

8289
def test_06_find_single_element_by_resource_id
83-
wait do
90+
wait(ignored: [Minitest::Assertion, Selenium::WebDriver::Error::NoSuchElementError]) do
8491
value = id('android:id/text1').text
85-
assert_equal value, "Access'ibility"
92+
assert_equal "Access'ibility", value
8693
end
8794
end
8895
end

‎android_tests/lib/android/specs/common/web_context.rb‎

Lines changed: 21 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -17,46 +17,43 @@
1717
class AndroidTest
1818
class Common
1919
class WebContext < Minitest::Test
20-
# appium's context support is broken on android
20+
include AndroidTestNavigation
21+
22+
def setup
23+
super
24+
reset_test_app
25+
end
26+
27+
def teardown
28+
reset_test_app
29+
ensure
30+
super
31+
end
2132

2233
def test_01_available_contexts
2334
wait_true { available_contexts.include? 'NATIVE_APP' }
2435
end
2536

2637
def test_02_current_context
27-
wait { assert_equal current_context, 'NATIVE_APP' }
28-
end
29-
30-
def undo_setcontext_nav
31-
back
32-
wait { find('WebView') }
33-
back
34-
wait { find 'Views' }
38+
assert_equal 'NATIVE_APP', current_context
3539
end
3640

3741
def test_03_set_context
38-
wait { scroll_to('Views').click }
39-
wait { scroll_to('WebView').click }
40-
41-
wait_true { !available_contexts.detect { |e| e.start_with?('WEBVIEW') }.nil? }
42+
wait { scroll_to_exact('Views') }.click
43+
wait { scroll_to_exact('WebView') }.click
4244

43-
webview_context = available_contexts.detect { |e| e.start_with?('WEBVIEW') }
44-
45-
if webview_context.nil?
46-
undo_setcontext_nav
47-
raise "No webview context found. contexts are: #{contexts}"
45+
webview_context = wait_true do
46+
available_contexts.find { |context| context.start_with?('WEBVIEW') }
4847
end
4948

50-
wait { set_context webview_context }
51-
wait { assert_equal current_context, webview_context }
49+
set_context webview_context
50+
wait_true { current_context == webview_context }
5251

5352
# verify inspect within webview works
5453
assert get_android_inspect.split("\n").length >= 3
5554

56-
wait { set_context 'NATIVE_APP' }
57-
wait { assert_equal current_context, 'NATIVE_APP' }
58-
59-
undo_setcontext_nav
55+
set_context 'NATIVE_APP'
56+
wait_true { current_context == 'NATIVE_APP' }
6057
end
6158
end
6259
end

‎android_tests/lib/run.rb‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@ def start_driver(caps)
8080
caps[:caps][:app] = ENV['IOS_APP'] if ENV['IOS_APP']
8181
caps[:caps][:platformVersion] = ENV['IOS_VERSION'] if ENV['IOS_VERSION']
8282
caps[:caps][:deviceName] = ENV['IOS_DEVICE_NAME'] if ENV['IOS_DEVICE_NAME']
83+
caps[:caps][:udid] = ENV['IOS_UDID'] if ENV['IOS_UDID']
8384
end
8485

8586
if ENV['LOCAL_PREBUILT_WDA']

‎appium_lib.gemspec‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Gem::Specification.new do |s|
1616
s.homepage = 'https://github.com/appium/ruby_lib' # published as appium_lib
1717
s.require_paths = ['lib']
1818

19-
s.add_dependency 'appium_lib_core', '>= 13.0.0', '< 14.0'
19+
s.add_dependency 'appium_lib_core', '>= 14.0.0', '< 15.0'
2020
s.add_dependency 'nokogiri', '~> 1.8', '>= 1.8.1'
2121
s.add_dependency 'ostruct', '~> 0.6'
2222
s.add_dependency 'tomlrb', '>= 1.1', '< 4.0'

0 commit comments

Comments
 (0)