Class: Koala::Facebook::TestUsers

Inherits:
Object
  • Object
show all
Defined in:
lib/koala/test_users.rb

Overview

Note:

the test user API is fairly slow compared to other interfaces (which makes sense – it’s creating whole new user accounts!).

Create and manage test users for your application. A test user is a user account associated with an app created for the purpose of testing the functionality of that app. You can use test users for manual or automated testing – Koala’s live test suite uses test users to verify the library works with Facebook.

See developers.facebook.com/docs/test_users/.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ TestUsers

Create a new TestUsers instance. If you don’t have your app’s access token, provide the app’s secret and Koala will make a request to Facebook for the appropriate token.

Parameters:

  • options (defaults to: {}) —

    initialization options.

Options Hash (options):

  • :app_id (Object) —

    the application’s ID.

  • :app_access_token (Object) —

    an application access token, if known.

  • :secret (Object) —

    the application’s secret.

Raises:

  • ArgumentError if the application ID and one of the app access token or the secret are not provided.



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/koala/test_users.rb', line 32

def initialize(options = {})
  @app_id = options[:app_id] || Koala.config.app_id
  @app_access_token = options[:app_access_token] || Koala.config.app_access_token
  @secret = options[:secret] || Koala.config.app_secret

  unless @app_id && (@app_access_token || @secret) # make sure we have what we need
    raise ArgumentError, "Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})"
  end

  # fetch the access token if we're provided a secret
  if @secret && !@app_access_token
    oauth = Koala::Facebook::OAuth.new(@app_id, @secret)
    @app_access_token = oauth.get_app_access_token
  end

  @api = API.new(@app_access_token)
end

Instance Attribute Details

#api ⇒ Koala::Facebook::API (readonly)

The application API interface used to communicate with Facebook.

Returns:



19
20
21
 
# File 'lib/koala/test_users.rb', line 19

def api
  @api
end

#app_access_token ⇒ Object (readonly)

Returns the value of attribute app_access_token.



20
21
22
 
# File 'lib/koala/test_users.rb', line 20

def app_access_token
  @app_access_token
end

#app_id ⇒ Object (readonly)

Returns the value of attribute app_id.



20
21
22
 
# File 'lib/koala/test_users.rb', line 20

def app_id
  @app_id
end

#secret ⇒ Object (readonly)

Returns the value of attribute secret.



20
21
22
 
# File 'lib/koala/test_users.rb', line 20

def secret
  @secret
end

Instance Method Details

#befriend(user1_hash, user2_hash, options = {}) ⇒ Object

Note:

there’s no way to unfriend test users; you can always just create a new one.

Make two test users friends.

Parameters:

  • user1_hash —

    one of the users to friend; the hash must contain both ID and access token (as returned by #create)

  • user2_hash —

    the other user to friend

  • options (defaults to: {}) —

    request-related options for Koala and Faraday. See github.com/arsduo/koala/wiki/HTTP-Services for additional options.

Returns:

  • true if successful, false (or an APIError) if not



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/koala/test_users.rb', line 137

def befriend(user1_hash, user2_hash, options = {})
  user1_id = user1_hash["id"] || user1_hash[:id]
  user2_id = user2_hash["id"] || user2_hash[:id]
  user1_token = user1_hash["access_token"] || user1_hash[:access_token]
  user2_token = user2_hash["access_token"] || user2_hash[:access_token]
  unless user1_id && user2_id && user1_token && user2_token
    # we explicitly raise an error here to minimize the risk of confusing output
    # if you pass in a string (as was previously supported) no local exception would be raised
    # but the Facebook call would fail
    raise ArgumentError, "TestUsers#befriend requires hash arguments for both users with id and access_token"
  end

  u1_graph_api = API.new(user1_token, secret)
  u2_graph_api = API.new(user2_token, secret)

  # if we have a secret token, flag that we want the appsecret_proof to be generated
  u1_graph_api.graph_call("#{user1_id}/friends/#{user2_id}", {}, "post", options.merge(appsecret_proof: !!secret)) &&
    u2_graph_api.graph_call("#{user2_id}/friends/#{user1_id}", {}, "post", options.merge(appsecret_proof: !!secret))
end

#create(installed, permissions = nil, args = {}, options = {}) ⇒ Object

Create a new test user.

Parameters:

  • installed —

    whether the user has installed your app

  • permissions (defaults to: nil) —

    a comma-separated string or array of permissions the user has granted (if installed)

  • args (defaults to: {}) —

    any additional arguments for the create call (name, etc.)

  • options (defaults to: {}) —

    request-related options for Koala and Faraday. See github.com/arsduo/koala/wiki/HTTP-Services for additional options.

Returns:

  • a hash of information for the new user (id, access token, login URL, etc.)



58
59
60
61
62
63
 
# File 'lib/koala/test_users.rb', line 58

def create(installed, permissions = nil, args = {}, options = {})
  # Creates and returns a test user
  args['installed'] = installed
  args['permissions'] = (permissions.is_a?(Array) ? permissions.join(",") : permissions) if installed
  @api.graph_call(test_user_accounts_path, args, "post", options)
end

#create_network(network_size, installed = true, permissions = '', options = {}) ⇒ Object

Note:

this call slows down dramatically the more users you create (test user calls are slow, and more users => more 1-on-1 connections to be made). Use carefully.

Create a network of test users, all of whom are friends and have the same permissions.

Parameters:

  • network_size —

    how many users to create

  • installed (defaults to: true) —

    whether the users have installed your app (see #create)

  • permissions (defaults to: '') —

    what permissions the users have granted (see #create)

  • options (defaults to: {}) —

    request-related options for Koala and Faraday. See github.com/arsduo/koala/wiki/HTTP-Services for additional options.

Returns:

  • the list of users created



169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/koala/test_users.rb', line 169

def create_network(network_size, installed = true, permissions = '', options = {})
  users = (0...network_size).collect { create(installed, permissions, {}, options) }
  friends = users.clone
  users.each do |user|
    # Remove this user from list of friends
    friends.delete_at(0)
    # befriend all the others
    friends.each do |friend|
      befriend(user, friend, options)
    end
  end
  return users
end

#delete(test_user, options = {}) ⇒ Object

Delete a test user.

Parameters:

Returns:

  • true if successful, false (or an APIError) if not



80
81
82
83
 
# File 'lib/koala/test_users.rb', line 80

def delete(test_user, options = {})
  test_user = test_user["id"] if test_user.is_a?(Hash)
  @api.delete_object(test_user, options)
end

#delete_all(options = {}) ⇒ Object

Note:

if you have a lot of test users (> 20), this operation can take a long time.

Deletes all test users in batches of 50.

Parameters:

Returns:

  • a list of the test users that have been deleted



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/koala/test_users.rb', line 92

def delete_all(options = {})
  # ideally we'd save a call by checking next_page_params, but at the time of writing
  # Facebook isn't consistently returning full pages after the first one
  previous_list = nil
  while (test_user_list = list(options)).length > 0
    # avoid infinite loops if Facebook returns buggy users you can't delete
    # see http://developers.facebook.com/bugs/223629371047398
    # since the hashes may change across calls, even if the IDs don't,
    # we just compare the IDs.
    test_user_ids = test_user_list.map {|u| u['id']}
    previous_user_ids = (previous_list || []).map {|u| u['id']}
    break if (test_user_ids - previous_user_ids).empty?

    test_user_list.each_slice(50) do |users|
      self.api.batch(options) {|batch_api| users.each {|u| batch_api.delete_object(u["id"]) }}
    end

    previous_list = test_user_list
  end
end

#list(options = {}) ⇒ Object

List all test users for the app.

Parameters:

Returns:

  • an array of hashes of user information (id, access token, etc.)



70
71
72
 
# File 'lib/koala/test_users.rb', line 70

def list(options = {})
  @api.graph_call(test_user_accounts_path, {}, "get", options)
end

#test_user_accounts_path ⇒ Object

The Facebook test users management URL for your application.



184
185
186
 
# File 'lib/koala/test_users.rb', line 184

def test_user_accounts_path
  @test_user_accounts_path ||= "/#{@app_id}/accounts/test-users"
end

#update(test_user, args = {}, options = {}) ⇒ Object

Note:

currently, only name and password can be changed; see / the Facebook documentation.

Updates a test user’s attributes.

Parameters:

  • test_user —

    the user to update; can be either a Facebook ID or the hash returned by #create

  • args (defaults to: {}) —

    the updates to make

  • options (defaults to: {}) —

    request-related options for Koala and Faraday. See github.com/arsduo/koala/wiki/HTTP-Services for additional options.

Returns:

  • true if successful, false (or an APIError) if not



123
124
125
126
 
# File 'lib/koala/test_users.rb', line 123

def update(test_user, args = {}, options = {})
  test_user = test_user["id"] if test_user.is_a?(Hash)
  @api.graph_call(test_user, args, "post", options)
end