Contents
Integration testing is generally a pain. Stepford attempts to alleviate as much of that pain as possible for apps requiring integration with the Facebook Graph API. Stepford is a Python implementation of the Facebook test user API as defined at https://developers.facebook.com/docs/test_users.
App tokens are access tokens that are bound to your application. They allow you to make requests on behalf of your application. Your app access token is required to interact with Facebook’s test user API. There are two methods to get your app token:
from stepford import app_token
token = app_token([client_id], [client_secret])
Warning
App tokens expire the same as other tokens. So, while the Facebook tool is useful for retrieving them for immediate use, it will eventually break in an automated environment.
import stepford
users = stepford.get([client_id], [app_token])
This returns a list of dicts with test user details. The data is structured like so:
[
{
'access_token': [snip],
'login_url': [snip],
'id': [snip]
},
[...]
]
import stepford
user = stepford.create([client_id], [app_token])
Creates a single test user:
{
'access_token': [snip],
'login_url': [snip],
'id': [snip]
}
Facebook offers the ability to update two test user attributes: name and password.
import stepford
stepford.update(userid, [app_token], name='[name]', pwd='[pwd]')
Warning
Changing the user’s password will result in the expiry of the current token. The only resolution to this (AFAIK) is to do a full get of the user list (stepford.get()), filtering for that user ID.
import stepford
stepford.delete(userid, [app_token])
Note
Attempting to delete a user who has multiple apps installed will result in an exception being raised. Users must have all apps (short of the owner app) uninstalled prior to deletion (see stepford.uninstall()).
stepford.connect() takes an arbitrary length (langth <= 1 will result in a ValueError exception) list of users to connect to each other. Each user object is expected to be of the same format as returned by stepford.create().
import stepford
users = [stepford.create([client_id], [app_token]) for _ in range(10)]
stepford.connect(*users)
The above code creates 10 users and then creates friendships between each.
import stepford
stepford.install(user['id'], [install_to_app_token], [client_id],
[app_token], scope='read_stream')
Installing applications to test users is a little odd. You need the app access token of the app being installed, which makes you unable to install arbitrary applications. client_id and app_token are those of the application used to create the test user.
import stepford
stepford.uninstall(user['id'], [client_id], [app_token])
The above uninstalls an app for a test user. The client_id and app_token in this case are those of the install app (not the owner app).
All errors generated by the Facebook test user API are translated to stepford.FacebookError, which is a subclass of urllib2.HTTPError. In addition to the usual HTTP code attribute, this class also provides you with the api_code, which can be used to retrieve the specific Facebook client-facing error code. Additionally, it translates the JSON error message to HTTPError.msg.
There are a few constants defined in stepford.py that define either errors encountered during testing and/or errors defined in Facebook’s test user API docs.
Implementation of the Facebook test user API
Exposes Facebook-specific error attributes
Methods wrapped with stepford.translate_http_error() will raise a stepford.FacebookError whenever an urllib2.HTTPError is encountered. This helps expose more detailed information about the error than the simple HTTP error code and message.
In the event that stepford encounters an unexpected API error (i.e. one that doesn’t contain the usual error data payload), api_code and type will be set to None.
The Facebook client-facing error code
The error category as defined by Facebook
Gets the app token
The app token is used in all stepford transactions. It is provided by Facebook and only changes when your app secret has been changed.
| Parameters: |
|
|---|---|
| Returns: | A dict containing the app token |
Creates friendships between test user accounts
| Parameters: | users – A list of users to create friendships for. |
|---|
Creates a test user
| Parameters: |
|
|---|---|
| Returns: | A dict containing user details |
Deletes a test user
| Parameters: |
|
|---|---|
| Returns: | True on success |
Gets a list of available test users
| Parameters: |
|
|---|---|
| Returns: | A list of dict elements containing user details |
Installs an app for the given user
| Parameters: |
|
|---|---|
| Returns: | True on success |
HTTPError to FacebookError translation decorator
Decorates functions, handles urllib2.HTTPError exceptions and translates them into stepford.FacebookError
| Parameters: | func – The function to decorate with translation handling |
|---|
Uninstalls an app for the given user
| Parameters: |
|
|---|---|
| Returns: | True on success |
Updates the given user
| Parameters: |
|
|---|---|
| Returns: | True on success |