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_alertArray<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


276
277
278
# File 'lib/calabash-cucumber/device_agent.rb', line 276

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:



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

def app_alert_visible?
  client.alert_visible?
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:



175
176
177
# File 'lib/calabash-cucumber/device_agent.rb', line 175

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.



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

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.



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

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)


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

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:



204
205
206
# File 'lib/calabash-cucumber/device_agent.rb', line 204

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:



114
115
116
# File 'lib/calabash-cucumber/device_agent.rb', line 114

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:



128
129
130
# File 'lib/calabash-cucumber/device_agent.rb', line 128

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

#springboard_alertObject

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


310
311
312
# File 'lib/calabash-cucumber/device_agent.rb', line 310

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


293
294
295
# File 'lib/calabash-cucumber/device_agent.rb', line 293

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:



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

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.



151
152
153
# File 'lib/calabash-cucumber/device_agent.rb', line 151

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



161
162
163
# File 'lib/calabash-cucumber/device_agent.rb', line 161

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:



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

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