launchpad developmentContents |
This page provides a guide to writing tests for Launchpad API clients.
Techniques for Testing API Clients
Point your application at the staging.launchpad.net web service
By writing data to the staging.launchpad.net web service you can observe how the application will behave against a copy of real, live data. You can also observe the application going over the network.
The data on staging.launchpad.net is copied from the production database every night. Copying overwrites any changes made to the staging data from the previous day.
Pros
- Your application gets to write real data to a live site over the network.
- The changes you make to the site data are not permanent
Cons
If your application reads and writes data to Launchpad, and you want to do multiple test runs against staging between the nightly database resets, then you will have to write your application to reset the data for you, or you must reset it manually. Depending on the problem you are trying to solve, you may also have the option to have your application ignore and overwrite any data already present on the server. You may also consider having your application generate its own test data.
Because the staging server is only updated nightly, you can not test your application against data on the same data that that data was entered into production. You may be able to work around by providing your users with a read-only switch.
An Example
You will want to provide an easy way to switch the service for developers and for operators, too. Command-line switches are one standard Unix way to accomplish this:
1 import sys
2 from launchpadlib.launchpad import Launchpad
3 from optparse import OptionParser
4
5 client_name = 'just testing'
6
7
8 def main(argv):
9 parser = OptionParser()
10 parser.add_option('-S', '--service', default='production',
11 help="Set the Launchpad web service instance this script will "
12 "read and write to [default: %default]")
13
14 options, args = parse_args(argv)
15
16 print "Connecting to the Launchpad API {0} service.".format(options.service)
17 launchpad = Launchpad.login_anonymously(client_name, options.service)
18
19
20 if __name__ == '__main__':
21 main(sys.argv)
An example usage:
$ myscript --service=staging Connecting to the Launchpad API staging service.
Notes
The staging database always runs code that is released or soon-to-be released on the Launchpad production servers. The API version will be equal to or greater than the production API version.
The staging server goes down for approximately two hours on the weekend for automated database updates.
Give your application read-only access to the server
By giving your application read-only access to the server you can allow developers and users to test your application against live data without fear of it destroying data. By only reading data it also becomes possible to run the tests multiple times in a row.
Pros
- Both developers and users can test your application without fear of it destroying data
- You can run the tests as many times as desired
- Your application gets to read real data from a production server
Cons
- Some application tests are not possible without writing data. You may not get 100% test coverage with this technique.
- You must modify your code so that it gracefully handles the inability to write data to the server, and you must do so at every point where data writes happen. This can be tedious to retrofit into an existing script and complicates your code.
An Example
A convenient trick to enforce read-only access for your script is to log in to the API anonymously. Anonymous users are not allowed to write data to Launchpad. If you do this, any point in your code that tries to write to the web service will raise an error: you can then modify the code to handle the read-only mode gracefully.
As before, we will use a command-line switch to make the functionality accessible to both developers and operators.
1 import sys
2 from launchpadlib.launchpad import Launchpad
3 from optparse import OptionParser
4
5 client_name = 'just testing'
6 service = 'production'
7
8
9 def main(argv):
10 parser = OptionParser()
11 parser.add_option('-d', '--dry-run', default=False, dest='readonly'
12 help="Only pretend to write data to the server.")
13
14 options, args = parse_args(argv)
15
16 print "Connecting to the Launchpad API {0} service.".format(service)
17
18 if options.readonly:
19 api_login = Launchpad.login_anonymously
20 else:
21 api_login = Launchpad.login_with
22
23 launchpad = api_login(client_name, service)
24
25 me = launchpad.people['my-user-name']
26 me.display_name = 'A user who edits through the Launchpad web service.'
27
28 # This would raise a ServerError if we are logged in anonymously
29 # me.lp_save()
30
31 # This is the correct way to do it:
32 if not options.readonly:
33 me.lp_save()
34 else:
35 print "Skipped saving display name: {0.display_name}".format(me)
36
37
38 if __name__ == '__main__':
39 main(sys.argv)
Notes
Have your application generate its own test data on the staging server
This is an advanced technique that builds upon 'test your application against staging'. You can have your application generate its own test data on the staging server, then run its tests against said data.
Pros
- Your application can read and write test data to a live server
- You are not limited by how many times in a row you can run the tests
- The changes you make to the site data are not permanent
Cons
- Not all of data creation functions in Launchpad are available through the API (working with SSH keys and Project Groups are two notable examples). You may be able to work around this by employing a mix of well-known existing data and generated sample data.
An Example
