Module: Calabash::Cucumber::KeychainHelpers

Included in:
Operations
Defined in:
lib/calabash-cucumber/keychain_helpers.rb

Overview

KeychainHelpers provide a helpers to access the iOS keychain.

Simulator Note

When running on the simulator, the keychain is not sandboxed between applications like it is on a real device. These methods will return keychain records from all applications on the simulator, which may result in strange behavior if you aren’t expecting it.

See Also:

Instance Method Summary collapse

Instance Method Details

#_keychain_get(options = {}) ⇒ Array<Hash>

sends appropriately-configured GET request to the keychain server endpoint. do not call this function directly; use one of the helper functions provided.

Parameters:

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

Returns:

  • (Array<Hash>) —

    contents of the iOS keychain

Raises:

  • (RuntimeError) —

    if http request does not report success

See Also:



30
31
32
33
34
35
36
37
38
 
# File 'lib/calabash-cucumber/keychain_helpers.rb', line 30

def _keychain_get(options={})
  res = http({:method => :get, :raw => true, :path => 'keychain'}, options)
  res = JSON.parse(res)
  if res['outcome'] != 'SUCCESS'
    raise "get keychain with options '#{options}' failed because: '#{res['reason']}'\n'#{res['details']}'"
  end

  res['results']
end

#_keychain_post(options = {}) ⇒ nil

sends appropriately-configured POST request to the keychain server endpoint. do not call this function directly; use one of the helper functions provided.

Returns:

  • (nil)

Raises:

  • (RuntimeError) —

    if http request does not report success

See Also:



99
100
101
102
103
104
105
106
 
# File 'lib/calabash-cucumber/keychain_helpers.rb', line 99

def _keychain_post(options={})
  raw = http({:method => :post, :path => 'keychain'}, options)
  res = JSON.parse(raw)
  if res['outcome'] != 'SUCCESS'
    raise "post keychain with options '#{options}' failed because: #{res['reason']}\n#{res['details']}"
  end
  nil
end

#keychain_accounts ⇒ Array<Hash>

asks the keychain for all of the account records

The hash keys are defined by the SSKeychain library.

The following keys are the most commonly useful:

+svce+ #=> the service
+acct+ #=> the account (often a username)
+cdat+ #=> the creation date
+mdat+ #=> the last-modified date

Returns:

  • (Array<Hash>) —

    of all account records saved in the iOS keychain.

Raises:

  • (RuntimeError) —

    if http request does not report success

See Also:



55
56
57
 
# File 'lib/calabash-cucumber/keychain_helpers.rb', line 55

def keychain_accounts
  _keychain_get
end

#keychain_accounts_for_service(service) ⇒ Array<Hash>

filtered by service.

Returns:

  • (Array<Hash>) —

    of all account records saved in the iOS keychain

Raises:

  • (RuntimeError) —

    if http request does not report success

See Also:



65
66
67
 
# File 'lib/calabash-cucumber/keychain_helpers.rb', line 65

def keychain_accounts_for_service(service)
  _keychain_get({:service => service})
end

#keychain_clear ⇒ nil

On the iOS Simulator this clears all keychain entries for all applications.

On a physical device, this will clear all entries for the target application.

Returns:

  • (nil)

Raises:

  • (RuntimeError) —

    if http request does not report success



117
118
119
 
# File 'lib/calabash-cucumber/keychain_helpers.rb', line 117

def keychain_clear
  _keychain_post
end

#keychain_clear_accounts_for_service(service) ⇒ nil

Clear all entries in the keychain restricted to a single service.

Returns:

  • (nil)

Raises:

  • (RuntimeError) —

    if http request does not report success



126
127
128
 
# File 'lib/calabash-cucumber/keychain_helpers.rb', line 126

def keychain_clear_accounts_for_service(service)
  _keychain_post({:service => service})
end

#keychain_delete_password(service, account) ⇒ Object

Delete a single keychain record for the given service and account pair.

Raises:

  • (RuntimeError) —

    if http request does not report success



134
135
136
 
# File 'lib/calabash-cucumber/keychain_helpers.rb', line 134

def keychain_delete_password(service, )
  _keychain_post(:service => service, :account => )
end

#keychain_password(service, account) ⇒ String, Array<Hash>

ask the keychain for an account password

*IMPORTANT*
On the XTC, the password cannot returned as plain text.
When using this keychain_password in your steps you can condition on
the XTC environment using +xamarin_test_cloud?+

Returns:

  • (String, Array<Hash>) —

    password stored in keychain for service and account. NB on the XTC this returns an Array with one Hash

Raises:

  • (RuntimeError) —

    if http request does not report success

  • (RuntimeError) —

    if service and account pair does not contain a password

See Also:



84
85
86
 
# File 'lib/calabash-cucumber/keychain_helpers.rb', line 84

def keychain_password(service, )
  _keychain_get({:service => service, :account => }).first
end

#keychain_set_password(service, account, password) ⇒ Object

Set the password for a given service and account pair.

Returns:

  • nil

Raises:

  • (RuntimeError) —

    if http request does not report success



143
144
145
 
# File 'lib/calabash-cucumber/keychain_helpers.rb', line 143

def keychain_set_password(service, , password)
  _keychain_post(:service => service, :account => , :password => password)
end