Test Users

Test users on Facebook were, historically, a pain. At first we just created real user accounts and hoped they wouldn’t get discovered and deleted. Facebook then created a network for test users; accounts in that network were safe from deletion and unable to mess around in the real world. Still, you had to create and manage those accounts manually, through the web, authorizing and deauthorizing apps just like regular users. It was a clunky system, and Facebook promised better.

Our long wait came to an end with the announcement of Facebook’s Test User API. With the API, you can create up to 2000 test users for your application, with whatever permissions, install status, and friend networks you need. Because it’s a programmatic interface, your tests can run reliably and automatedly against clean users who you know will exactly match the test cases you want. And because it’s a Facebook API, we support it.

Using the TestUsers API

Creating test users requires an application’s access token, which you can either supply directly or can be fetched with application’s ID and secret:

@test_users = Koala::Facebook::TestUsers.new(:app_id => id, :secret => "secret")
@test_users = Koala::Facebook::TestUsers.new(:app_id => id, :app_access_token => access_token)

@test_users is now a TestUsers API, which we can use to set up our testing conditions.

Managing Test Users

The first thing you’ll probably do is to create a test user. #create takes two arguments — a boolean to say whether the test user has installed the app, and an array or comma-separated string containing any permissions you want.

@test_users.create(false)
# creates a user who hasn't installed your app
=> {"login_url"=>"https://www.facebook.com/platform/test_account_login.php?user_id=#{id}&n=#{value}", "id"=>#{id}, "access_token"=>nil}
@test_users.create(true, "offline_access,read_stream")
# creates a user of your app who's granted those permissions
# note the presence of access_token in the hash
=> {"login_url"=>"https://www.facebook.com/platform/test_account_login.php?user_id=#{id}&n=#{value}", "id"=>#{id}, "access_token"=>#{token}}

Side note: Facebook doesn’t have a method to update permissions or installed status on an existing user, though you can update name and password. If you need to a different configuration, you need to delete the user and create a new one.

Once you’ve started using the API, you may want to go back and see which test users are installed. (This is particularly important, since each application can only have 2000 test users.)

@test_users.list
=> [{"login_url"=>url2, "id"=>id2}, {"login_url"=>url3, "id"=>id3, "access_token"=>token3}]

Of course, you may want to delete a user. You can pass either the ID or the entire test user hash:

user = {"login_url"=>url, "id"=>id, "access_token"=>token}
@test_users.delete(user["id"])
@test_users.delete(user)
=> true

You can also delete_all if you want to start with a fresh slate.

Finally, just like life itself, no test scenario is complete without friends. With the Test User API, you can generate and confirm friend requests between users, which we encapsulate in a single befriend method:

@test_users.befriend(user1, user2) # can also take hashes
# the confirmation isn't very insightful
# but you can use regular API methods to look at the users' friends 
=> {"data"=>[]}

Sometimes, it may be convenient to use the same test users that you’ve already created for one application in a different application. To do that, you call the create method with the UID of the test user and the application access token of the application that you want the test user to be associated with.

other_app_access_token = @other_oauth.get_app_access_token
@test_users.create(true, "read_stream", {"uid" => id1, "owner_access_token" => other_app_access_token})

You can also update test user attributes (as of this writing, only name and password):

# available with 1.2beta
@test_users.update(user1, {:name => "new name", :password => "newpassword"})
# note that changing the password invalidates the access token
# you can get a new one through .list

Networks

Of course, all that’s time consuming. You want 10 users, all with friends, who all have similar permissions. Easy!

@test_users.create_network(10, installed_status, permissions)
=> hash_of_10_users

All those users will have the permissions you specify, and they will all be linked together as friends. Please note that this can be a very slow process, because of the number of API calls involved (somewhere on the order of 100 calls for a 10 person network — 10 creates, then 45 befriends, each of which requires two calls). Also note that the “create_network” method only works this way when installed_status is true.