class Koala::Facebook::TestUsers
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
.
@note the test user API
is fairly slow compared to other interfaces
(which makes sense -- it's creating whole new user accounts!).
Attributes
Public Class Methods
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.
@param options initialization options. @option options :app_id the application's ID. @option options :app_access_token an application access token, if known. @option options :secret the application's secret.
@raise ArgumentError if the application ID and one of the app access token or the secret are not provided.
# File lib/koala/test_users.rb 32 def initialize(options = {}) 33 @app_id = options[:app_id] || Koala.config.app_id 34 @app_access_token = options[:app_access_token] || Koala.config.app_access_token 35 @secret = options[:secret] || Koala.config.app_secret 36 37 unless @app_id && (@app_access_token || @secret) # make sure we have what we need 38 raise ArgumentError, "Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})" 39 end 40 41 # fetch the access token if we're provided a secret 42 if @secret && !@app_access_token 43 oauth = Koala::Facebook::OAuth.new(@app_id, @secret) 44 @app_access_token = oauth.get_app_access_token 45 end 46 47 @api = API.new(@app_access_token) 48 end
Public Instance Methods
Make two test users friends.
@note there's no way to unfriend test users; you can always just create a new one.
@param user1_hash one of the users to friend; the hash must contain both ID and access token (as returned by {#create}) @param user2_hash the other user to friend @param options (see Koala::Facebook::API#api
)
@return true if successful, false (or an {Koala::Facebook::APIError APIError}) if not
# File lib/koala/test_users.rb 137 def befriend(user1_hash, user2_hash, options = {}) 138 user1_id = user1_hash["id"] || user1_hash[:id] 139 user2_id = user2_hash["id"] || user2_hash[:id] 140 user1_token = user1_hash["access_token"] || user1_hash[:access_token] 141 user2_token = user2_hash["access_token"] || user2_hash[:access_token] 142 unless user1_id && user2_id && user1_token && user2_token 143 # we explicitly raise an error here to minimize the risk of confusing output 144 # if you pass in a string (as was previously supported) no local exception would be raised 145 # but the Facebook call would fail 146 raise ArgumentError, "TestUsers#befriend requires hash arguments for both users with id and access_token" 147 end 148 149 u1_graph_api = API.new(user1_token, secret) 150 u2_graph_api = API.new(user2_token, secret) 151 152 # if we have a secret token, flag that we want the appsecret_proof to be generated 153 u1_graph_api.graph_call("#{user1_id}/friends/#{user2_id}", {}, "post", options.merge(appsecret_proof: !!secret)) && 154 u2_graph_api.graph_call("#{user2_id}/friends/#{user1_id}", {}, "post", options.merge(appsecret_proof: !!secret)) 155 end
Create a new test user.
@param installed whether the user has installed your app @param permissions a comma-separated string or array of permissions the user has granted (if installed) @param args any additional arguments for the create call (name, etc.) @param options (see Koala::Facebook::API#api
)
@return a hash of information for the new user (id, access token, login URL, etc.)
# File lib/koala/test_users.rb 58 def create(installed, permissions = nil, args = {}, options = {}) 59 # Creates and returns a test user 60 args['installed'] = installed 61 args['permissions'] = (permissions.is_a?(Array) ? permissions.join(",") : permissions) if installed 62 @api.graph_call(test_user_accounts_path, args, "post", options) 63 end
Create a network of test users, all of whom are friends and have the same permissions.
@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.
@param network_size how many users to create @param installed whether the users have installed your app (see {#create}) @param permissions what permissions the users have granted (see {#create}) @param options (see Koala::Facebook::API#api
)
@return the list of users created
# File lib/koala/test_users.rb 169 def create_network(network_size, installed = true, permissions = '', options = {}) 170 users = (0...network_size).collect { create(installed, permissions, {}, options) } 171 friends = users.clone 172 users.each do |user| 173 # Remove this user from list of friends 174 friends.delete_at(0) 175 # befriend all the others 176 friends.each do |friend| 177 befriend(user, friend, options) 178 end 179 end 180 return users 181 end
Delete a test user.
@param test_user the user to delete; can be either a Facebook
ID or the hash returned by {#create} @param options (see Koala::Facebook::API#api
)
@return true if successful, false (or an {Koala::Facebook::APIError APIError}) if not
# File lib/koala/test_users.rb 80 def delete(test_user, options = {}) 81 test_user = test_user["id"] if test_user.is_a?(Hash) 82 @api.delete_object(test_user, options) 83 end
Deletes all test users in batches of 50.
@note if you have a lot of test users (> 20), this operation can take a long time.
@param options (see Koala::Facebook::API#api
)
@return a list of the test users that have been deleted
# File lib/koala/test_users.rb 92 def delete_all(options = {}) 93 # ideally we'd save a call by checking next_page_params, but at the time of writing 94 # Facebook isn't consistently returning full pages after the first one 95 previous_list = nil 96 while (test_user_list = list(options)).length > 0 97 # avoid infinite loops if Facebook returns buggy users you can't delete 98 # see http://developers.facebook.com/bugs/223629371047398 99 # since the hashes may change across calls, even if the IDs don't, 100 # we just compare the IDs. 101 test_user_ids = test_user_list.map {|u| u['id']} 102 previous_user_ids = (previous_list || []).map {|u| u['id']} 103 break if (test_user_ids - previous_user_ids).empty? 104 105 test_user_list.each_slice(50) do |users| 106 self.api.batch(options) {|batch_api| users.each {|u| batch_api.delete_object(u["id"]) }} 107 end 108 109 previous_list = test_user_list 110 end 111 end
List all test users for the app.
@param options (see Koala::Facebook::API#api
)
@return an array of hashes of user information (id, access token, etc.)
# File lib/koala/test_users.rb 70 def list(options = {}) 71 @api.graph_call(test_user_accounts_path, {}, "get", options) 72 end
The Facebook
test users management URL for your application.
# File lib/koala/test_users.rb 184 def test_user_accounts_path 185 @test_user_accounts_path ||= "/#{@app_id}/accounts/test-users" 186 end
Updates a test user's attributes.
@note currently, only name and password can be changed;
see {http://developers.facebook.com/docs/test_users/ the Facebook documentation}.
@param test_user the user to update; can be either a Facebook
ID or the hash returned by {#create} @param args the updates to make @param options (see Koala::Facebook::API#api
)
@return true if successful, false (or an {Koala::Facebook::APIError APIError}) if not
# File lib/koala/test_users.rb 123 def update(test_user, args = {}, options = {}) 124 test_user = test_user["id"] if test_user.is_a?(Hash) 125 @api.graph_call(test_user, args, "post", options) 126 end