Class: Calabash::Cucumber::DeviceAgent

Inherits:
BasicObject
Defined in:
lib/calabash-cucumber/device_agent.rb

Overview

An interface to the DeviceAgent Query and Gesture API.

Unlike Calabash or UIA gestures, all DeviceAgent gestures wait for the uiquery to match a view. This behavior match the Calabash 2.0 and Calabash 0.x Android behavior.

This API is work in progress. There are several methods that are experimental and several methods that will probably removed soon.

Wherever possible use Core#query and the gestures defined in Core.

TODO Screenshots

Instance Method Summary collapse

Instance Method Details

#app_alert ⇒ Array<Hash>

EXPERIMENTAL: This API may change.

Queries for an alert generate by your Application.

This does not detect SpringBoard alerts.

Returns:

  • (Array<Hash>) —

    The view that was touched.

See Also:

  • #spring_board_alert


352
353
354
 
# File 'lib/calabash-cucumber/device_agent.rb', line 352

def app_alert
  client.alert
end

#app_alert_visible? ⇒ Boolean

EXPERIMENTAL: This API may change.

Is an alert generated by your Application visible?

This does not detect SpringBoard alerts.

Returns:

  • (Boolean)

See Also:



339
340
341
 
# File 'lib/calabash-cucumber/device_agent.rb', line 339

def app_alert_visible?
  client.alert_visible?
end

#clear_text ⇒ Object

Perform a clear text on the active view



141
142
143
 
# File 'lib/calabash-cucumber/device_agent.rb', line 141

def clear_text
  client.clear_text
end

#dismiss_springboard_alert(button_title) ⇒ Object

EXPERIMENTAL: This API may change.

Please pay attention to non-ASCII characters in button titles.

“Don’t Allow” => UTF-8 single quote in Don’t “Don’t Allow” => ASCII single quote in Don’t

Only UTF-8 string will match the button title.

Parameters:

  • button_title (String) —

    The title of the button to touch.

Returns:

  • true if a SpringBoard alert is dismissed.

Raises:

  • RuntimeError If there is no SpringBoard alert visible

  • RuntimeError If the SpringBoard alert does not have a button matching button_title.

  • RuntimeError If there is an error dismissing the SpringBoard alert.



454
455
456
 
# File 'lib/calabash-cucumber/device_agent.rb', line 454

def dismiss_springboard_alert(button_title)
   client.dismiss_springboard_alert(button_title)
end

#dismiss_springboard_alerts_automatically! ⇒ Object

EXPERIMENTAL: This API may change.

Disables Calabash’s ability to dismiss SpringBoard alerts automatically.



393
394
395
 
# File 'lib/calabash-cucumber/device_agent.rb', line 393

def dismiss_springboard_alerts_automatically!
  client.set_dismiss_springboard_alerts_automatically(true)
end

#dismiss_springboard_alerts_manually! ⇒ Object

EXPERIMENTAL: This API may change.

Enables Calabash’s ability to dismiss SpringBoard alerts automatically.



400
401
402
 
# File 'lib/calabash-cucumber/device_agent.rb', line 400

def dismiss_springboard_alerts_manually!
  client.set_dismiss_springboard_alerts_automatically(false)
end

#double_tap(uiquery) ⇒ Array<Hash>

Perform a double tap on the center of the first view matched the uiquery.

This method waits for the query to match at least one element.

Parameters:

  • uiquery —

    See #query

Returns:

  • (Array<Hash>) —

    The view that was touched.

Raises:

  • (RuntimeError) —

    if no view matches the uiquery after waiting.

See Also:



202
203
204
 
# File 'lib/calabash-cucumber/device_agent.rb', line 202

def double_tap(uiquery)
  with_screenshot_on_failure { client.double_tap(uiquery) }
end

#enter_text(text) ⇒ Object

Deprecated.

0.21.0 Use Core#enter_text

Enter text into the UITextInput view that is the first responder.

The first responder is the view that is attached to the keyboard.

Scheduled for removal in 0.21.0. Use Core#enter_text. If you find an example where Core#enter_text does not work, please report it.

Parameters:

  • text (String) —

    the text to enter

Raises:

  • (RuntimeError) —

    if there is no visible keyboard.



306
307
308
 
# File 'lib/calabash-cucumber/device_agent.rb', line 306

def enter_text(text)
  with_screenshot_on_failure { client.enter_text(text) }
end

#enter_text_in(uiquery, text) ⇒ Object

Deprecated.

0.21.0 Use Core#enter_text

Enter text into the first view matched by uiquery.

This method waits for the query to match at least one element and for the keyboard to appear.

Scheduled for removal in 0.21.0. Use Core#enter_text_in. If you find an example where Core#enter_text_in does not work, please report it.

Raises:

  • (RuntimeError) —

    if no view matches the uiquery after waiting.

  • (RuntimeError) —

    if the touch does not cause a keyboard to appear.



322
323
324
325
326
327
328
 
# File 'lib/calabash-cucumber/device_agent.rb', line 322

def enter_text_in(uiquery, text)
  with_screenshot_on_failure do
    client.touch(uiquery)
    client.wait_for_keyboard
    client.enter_text(text)
  end
end

#keyboard_visible? ⇒ Boolean

Deprecated.

0.21.0 Use Core#keyboard_visible?

Returns true if there is a keyboard visible.

Scheduled for removal in 0.21.0. Use Core#keyboard_visible?. If you find an example where Core#keyboard_visible? does not find visible keyboard, please report it.

Returns:

  • (Boolean) 


291
292
293
 
# File 'lib/calabash-cucumber/device_agent.rb', line 291

def keyboard_visible?
  client.keyboard_visible?
end

#long_press(uiquery, duration) ⇒ Array<Hash>

Perform a long press on the center of the first view matched the uiquery.

This method waits for the query to match at least one element.

Parameters:

  • uiquery —

    See #query

  • duration (Numeric) —

    How long to press.

Returns:

  • (Array<Hash>) —

    The view that was touched.

Raises:

  • (RuntimeError) —

    if no view matches the uiquery after waiting.

See Also:



231
232
233
 
# File 'lib/calabash-cucumber/device_agent.rb', line 231

def long_press(uiquery, duration)
  with_screenshot_on_failure { client.long_press(uiquery, {:duration => duration}) }
end

#query(uiquery) ⇒ Array<Hash>

Query the UI for elements.

Querying for text with newlines is not supported yet.

The query language supports the following keys:

  • :marked - accessibilityIdentifier, accessibilityLabel, text, and value

  • :id - accessibilityIdentifier

  • :type - an XCUIElementType shorthand, e.g. XCUIElementTypeButton => Button. See the link below for available types. Note, however that some XCUIElementTypes are not available on iOS.

  • :index - Applied after all other specifiers.

  • :all - Filter the result by visibility. Defaults to false. See the discussion below about visibility.

### Visibility

The rules for visibility are:

  1. If any part of the view is visible, the visible.

  2. If the view has alpha 0, it is not visible.

  3. If the view has a size (0,0) it is not visible.

  4. If the view is not within the bounds of the screen, it is not visible.

Visibility is determined using the “hitable” XCUIElement property. XCUITest, particularly under Xcode 7, is not consistent about setting the “hitable” property correctly. Views that are not “hitable” will still respond to gestures. For this reason, gestures use the element for computing the touch point.

Regarding rule #1 - this is different from the Calabash iOS and Android definition of visibility which requires the mid-point of the view to be visible.

Please report visibility problems.

### Results

Results are returned as an Array of Hashes. The key/value pairs are similar to those returned by the Calabash iOS Server, but not exactly the same.

“‘ [

{
  "enabled": true,
  "id": "mostly hidden button",
  "hitable": true,
  "rect": {
    "y": 459,
    "x": 24,
    "height": 25,
    "width": 100
  },
  "label": "Mostly Hidden",
  "type": "Button",
  "hit_point": {
    "x": 25,
    "y": 460
  },
}

] “‘

Examples:

query({id: "login", :type "Button"})

query({marked: "login"})

query({marked: "login", type: "TextField"})

query({type: "Button", index: 2})

query({text: "Log in"})

query({id: "hidden button", :all => true})

# Escaping single quote is not necessary, but supported.
query({text: "Karl's problem"})
query({text: "Karl\'s problem"})

# Escaping double quote is not necessary, but supported.
query({text: "\"To know is not enough.\""})
query({text: %Q["To know is not enough."]})

Parameters:

  • uiquery (Hash) —

    A hash describing the query.

Returns:

  • (Array<Hash>) —

    An array of elements matching the ‘uiquery`.

See Also:



136
137
138
 
# File 'lib/calabash-cucumber/device_agent.rb', line 136

def query(uiquery)
  client.query(uiquery)
end

#query_for_coordinate(uiquery) ⇒ Hash

Query for the center of a view.

This method waits for the query to match at least one element.

Parameters:

  • uiquery —

    See #query

Returns:

  • (Hash) —

    The center of first view matched by query.

Raises:

  • (RuntimeError) —

    if no view matches the uiquery after waiting.

See Also:



155
156
157
 
# File 'lib/calabash-cucumber/device_agent.rb', line 155

def query_for_coordinate(uiquery)
  with_screenshot_on_failure { client.query_for_coordinate(uiquery) }
end

#set_dismiss_springboard_alerts_automatically(true_or_false) ⇒ Object

EXPERIMENTAL: This API may change.

Enables or disables Calabash’s ability to dismiss SpringBoard alerts automatically.

Parameters:

  • true_or_false 


410
411
412
 
# File 'lib/calabash-cucumber/device_agent.rb', line 410

def set_dismiss_springboard_alerts_automatically(true_or_false)
  client.set_dismiss_springboard_alerts_automatically(true_or_false)
end

#springboard_alert ⇒ Object

EXPERIMENTAL: This API may change.

Queries for an alert generated by SpringBoard.

This does not detect alerts generated by your Application.

Examples of SpringBoard alerts are:

  • Privacy Alerts generated by requests for access to protected iOS services like Contacts and Location,

  • “No SIM card”

  • iOS Update available

See Also:

  • #alert


386
387
388
 
# File 'lib/calabash-cucumber/device_agent.rb', line 386

def springboard_alert
  client.springboard_alert
end

#springboard_alert_visible? ⇒ Boolean

EXPERIMENTAL: This API may change.

Is an alert generated by SpringBoard visible?

This does not detect alerts generated by your Application.

Examples of SpringBoard alerts are:

  • Privacy Alerts generated by requests for access to protected iOS services like Contacts and Location,

  • “No SIM card”

  • iOS Update available

Returns:

  • (Boolean)

See Also:

  • #alert


369
370
371
 
# File 'lib/calabash-cucumber/device_agent.rb', line 369

def springboard_alert_visible?
  client.springboard_alert_visible?
end

#touch(uiquery) ⇒ Array<Hash>

Perform a touch on the center of the first view matched the uiquery.

This method waits for the query to match at least one element.

Parameters:

  • uiquery (Hash) —

    See #query for examples.

Returns:

  • (Array<Hash>) —

    The view that was touched.

Raises:

  • (RuntimeError) —

    if no view matches the uiquery after waiting.

See Also:



169
170
171
 
# File 'lib/calabash-cucumber/device_agent.rb', line 169

def touch(uiquery)
  with_screenshot_on_failure { client.touch(uiquery) }
end

#touch_coordinate(coordinate) ⇒ Object

Perform a touch at a coordinate.

This method does not wait; the touch is performed immediately.

Parameters:

  • coordinate (Hash) —

    The coordinate to touch.



178
179
180
 
# File 'lib/calabash-cucumber/device_agent.rb', line 178

def touch_coordinate(coordinate)
  client.touch_coordinate(coordinate)
end

#touch_point(x, y) ⇒ Object

Perform a touch at a point.

This method does not wait; the touch is performed immediately.

Parameters:

  • x (Hash) —

    the x coordinate

  • y (Hash) —

    the y coordinate



188
189
190
 
# File 'lib/calabash-cucumber/device_agent.rb', line 188

def touch_point(x, y)
  client.touch_point(x, y)
end

#two_finger_tap(uiquery) ⇒ Array<Hash>

Perform a two finger tap on the center of the first view matched the uiquery.

This method waits for the query to match at least one element.

Parameters:

  • uiquery —

    See #query

Returns:

  • (Array<Hash>) —

    The view that was touched.

Raises:

  • (RuntimeError) —

    if no view matches the uiquery after waiting.

See Also:



216
217
218
 
# File 'lib/calabash-cucumber/device_agent.rb', line 216

def two_finger_tap(uiquery)
  with_screenshot_on_failure { client.two_finger_tap(uiquery) }
end

#wait_for_no_springboard_alert(timeout = nil) ⇒ Object

EXPERIMENTAL: This API may change.

Wait for a SpringBoard alert to disappear.



428
429
430
431
432
433
434
 
# File 'lib/calabash-cucumber/device_agent.rb', line 428

def wait_for_no_springboard_alert(timeout=nil)
  if timeout
    client.wait_for_no_springboard_alert(timeout)
  else
    client.wait_for_no_springboard_alert
  end
end

#wait_for_no_view(uiquery, options = {}) ⇒ Object

Wait for no view to match uiquery.

Parameters:

  • uiquery (Hash) —

    the query

  • options (Hash) (defaults to: {}) —

    control the timeout

Options Hash (options):

  • :timeout (Numeric) —

    How long to wait for the query to match a view and the text to appear in that view.

Raises:

  • (Timeout::Error) —

    when there is a view that matches uiquery



278
279
280
281
282
 
# File 'lib/calabash-cucumber/device_agent.rb', line 278

def wait_for_no_view(uiquery, options={})
  with_screenshot_on_failure do
    client.wait_for_no_view(uiquery, options)
  end
end

#wait_for_springboard_alert(timeout = nil) ⇒ Object

EXPERIMENTAL: This API may change.

Wait for a SpringBoard alert to appear.



417
418
419
420
421
422
423
 
# File 'lib/calabash-cucumber/device_agent.rb', line 417

def wait_for_springboard_alert(timeout=nil)
  if timeout
    client.wait_for_springboard_alert(timeout)
  else
    client.wait_for_springboard_alert
  end
end

#wait_for_text_in_view(text, uiquery, options = {}) ⇒ Object

Wait for text to appear in a view matched by uiquery.

Parameters:

  • text (Hash) —

    the text to wait for (exact match)

  • uiquery (Hash) —

    query for the view in which the text should appear

  • options (Hash) (defaults to: {}) —

    control the timeout

Options Hash (options):

  • :timeout (Numeric) —

    How long to wait for the query to match a view and the text to appear in that view.

Returns:

  • The first view that matches uiquery and contains text

Raises:

  • (Timeout::Error) —

    when no match appears before the timeout



245
246
247
248
249
250
251
 
# File 'lib/calabash-cucumber/device_agent.rb', line 245

def wait_for_text_in_view(text, uiquery, options={})
  value = nil
  with_screenshot_on_failure do
    value = client.wait_for_text_in_view(text, uiquery, options)
  end
  value
end

#wait_for_view(uiquery, options = {}) ⇒ Object

Wait for view to match uiquery.

Parameters:

  • uiquery (Hash) —

    the query

  • options (Hash) (defaults to: {}) —

    control the timeout

Options Hash (options):

  • :timeout (Numeric) —

    How long to wait for the query to match a view and the text to appear in that view.

Returns:

  • The first view that matches uiquery

Raises:

  • (Timeout::Error) —

    when no match appears before the timeout



262
263
264
265
266
267
268
 
# File 'lib/calabash-cucumber/device_agent.rb', line 262

def wait_for_view(uiquery, options={})
  value = nil
  with_screenshot_on_failure do
    value = client.wait_for_view(uiquery, options)
  end
  value
end