o2sms - Action Files

o2sms works by utilizing action files which describe the interactions with the websites of the various service providers.

By passing various parameters to the action file (username, password, message, recipient), the HTTP dialog between client and server is produced.

The actual mechanism for replaying action files like this is provided by the TestGen4Web::Runner PERL module.

Developers of programs similar to o2sms (perhaps in another language) are welcome to re-use these action files.

If the website of a provider changes, or you want to add a new provider, then a new action file must be compiled. This goes something like this:

1. Download and install the TestGen4Web Extension for Firefox.
2. Start a new recording.
3. Go to the homepage of your mobile phone provider and log in.
4. Select some text that only appears on the page when you log in successfully and create an assertion for this (right click on the text, select 'Record', select 'Assert Text Exists'.
5. Click the 'Webtext' or equivalent link on this page, fill in the webtext form with a test message to yourself and click 'send'.
6. On the 'webtext sent' page, select the text that says 'you now have xxx messages remaining' and create an assertion for this.
7. Stop the recording and save the file.

For the recorded file to work with o2sms, you need to replace some of the strings with variable placeholders. Open the file and change the following:

• Your username (or whatever id you logged in with) with {username}
• Your password with {password}
• The message text with {message}
• The recipient's number with {recipient}
• Optional: {charsleft}
• Optional: {delay}

You'll also need to turn the final assertion into a regular expression to capture the number of messages remaining. E.g. "You now have 123 Free Messages remaining this month" changes to "You now have (\d+) Free Messages remaining this month".

1. Download a fresh copy of the source from the o2sms project page and unbundle it somewhere.
2. Replace the action file in lib/WWW/SMS/IE/[o2|voda|meteor]sms.action with the one you just recorded.
3. Run o2sms with the new action file with a command like this: PERL5LIB=lib ./bin/vodasms -d +353861234567 (the PERL5LIB bit ensures you're not accidentally using an installed version).
4. If you're lucky, your new action file will work out of the box, if not see Troubleshooting below.
5. Don't forget to send me the new action file :)

Chances are your new action file won't work straight-away. Blame HTML. The sheer number of crappy HTML and JavaScript code that have to be navigated means that the TestGen4Web recorder may miss something. The TestGen4Web Runner is also far from perfect, meaning your action file may need poking to work.

Some common problems are listed below. Most of these involve inspect the HTTP dialog and HTML source. Run o2sms with the -dd option to get full, nasty debugging so you can see exactly what's going on.

• If a fill or click is missing in the action file, just insert it manually. Remember to increment the step numbers of subsequent steps.
• Several XPath types aren't supported by TestGen4Web::Runner. So, for example FORM[@ID="TheForm"] will need to be replaced with the form number XPath FORM[1]. To find the form number, inspect the HTML source for the login/send page.
• When links are described in the action file, sometimes the full XPath is given, which may not be supported by TestGen4Web. Instead, replace with the HREF or CDATA value of the link.

A good idea in most cases is to look at the existing working action files to see what is the required syntax.

Good luck!