As a lead maintainer of the Appium project, I was very excited to learn about TestProject building a test building and running tool on top of Appium and Selenium. Recently, I was even more excited to see that this tool was going free for public use! I’ve had a chance to play around with it quite a bit now, including putting together a webinar a while back on how to distribute your Appium tests using different TestProject agents.
But really, what I’m most interested in in this whole project is the fact that TestProject is trying to build a platform, not just a tool. The set of community addons is a great way to encourage lots of people to develop new functionality that plugs into TestProject, and to share their work with others. I recently built my first TestProject addon, and this post is all about the steps I took to do this!
The Idea
The basic idea I had for the addon was to implement a cross-platform method for triggering deep links across both iOS and Android apps. (If you’re not quite sure what deep links are, or how they are valuable for testing, check out this article on speeding up your tests with deep links from my newsletter and blog, Appium Pro). One of the downsides of the approach I used in that article was that it didn’t work on real physical iOS devices–only on simulators. Later on, Wim Selles contributed an article on a cross-platform method for opening deep links on all devices. It is this approach that I wanted to use in creating a TestProject addon.
(Want to skip all the words and check out the addon already? Just head over to the Deep Link Toolkit addon page.)
The addon looks like this:
Basically, all you do to use it is input the deep link URL you want to be activated, and you’re off to the races!
Developing the Addon
TestProject has a public SDK that you can use to develop addons. I chose to develop my addon in Java. As part of the TestProject Java SDK documentation, there is a section on addon development. This was an indispensable reference in developing the addon, as was the portion before on running TestProject tests from Java, which is necessary as part of the test process. I also found this very helpful tutorial by Petri Kainulainen, which filled in some of the gaps in my understanding based on the docs alone.
The first thing I did, of course, was to create an open source Git repo to host this addon (and potentially more addons I develop down the road), which you can find here.
The way creating addons work is by implementing a special interface for Web, iOS, or Android. This interface allows us to set parameters for the addon (that will show up in the TestProject recorder UI), and to define the behavior that will occur when the addon is run by the user, inside a method called execute, which gives us access to the Appium driver and potentially other things we might need. For me, implementing the execute function was pretty simple, especially for Android, since triggering a deep link on Android requires only two short Appium commands! Here’s the full Android class for the Android side of the deep link addon:
@Action(name = "Open Deep Link")
public class OpenDeepLinkAndroid implements AndroidAction {
@Parameter(description = "The deep link URL")
public String url = "";
@Parameter(description = "The package of the app for the URL (optional, will default to the currently-running app)")
public String pkg = "";
@Override
public ExecutionResult execute(AndroidAddonHelper helper) throws FailureException {
Helpers.validateURL(url);
AndroidDriver driver = helper.getDriver();
if (pkg.equals("")) {
pkg = driver.getCurrentPackage();
}
driver.terminateApp(pkg);
driver.executeScript("mobile: deepLink", ImmutableMap.of(
"url", url,
"package", pkg
));
return ExecutionResult.PASSED;
}
}
In the snippet above, you can see how we give the addon a name, and set its parameters. Then, we use those parameters as well as the Appium driver attached to the device to terminate the currently-running app and then call the mobile: deepLink command. That’s it! That’s all the code that powers this addon. You can, of course, check out the Android code on GitHub, as well as the iOS code, which is a bit more complex since we have to actually automate a bit of the mobile Safari UI.
Testing the Addon
Developing the addon is one thing, but I also needed to test it. For that, I used the test running portion of the TestProject SDK. Basically, I have access to a Runner class which allows me to start test sessions, as long as I have my TestProject developer key handy. This class handles all the Appium session start for me, so I don’t have to worry about setting capabilities or anything like that. I just get back an Appium driver, which I can use in a test method. Here’s the test method I wrote for the Android version of the addon:
@Test
void testOpenDeepLinkAction() throws Exception {
// Create Action
OpenDeepLinkAndroid action = new OpenDeepLinkAndroid();
action.url = "theapp://login/alice/mypassword";
// Run action
runner.run(action);
// Verify
WebDriverWait wait = new WebDriverWait(driver, 10);
wait.until(ExpectedConditions.presenceOfElementLocated(By.xpath("//*[contains(@text, \"You are logged in as alice\")]")));
}
I can directly instantiate my Android deep link class, and then I trigger it using runner.run(). Assuming the action completes as expected, I’ve tested that my addon works! (You can see the full test class for the Android version of the test as well as the iOS version on GitHub).
Submitting the Addon
Once I was ready to upload my addon to TestProject, I had to “Create” the addon in the web UI. This opens up a wizard which prompts for various information and any permissions my addon might need beyond the Appium driver (for example, filesystem access, etc…). The most important part of this process was saving the manifest file which was generated by the wizard. I had to download this and put it in the src/main/java/resources directory in my project. TestProject uses this file to get all the important metadata about the addon.
Finally, I had to actually compile, bundle, and upload the addon jarfile to TestProject. Luckily, the TestProject docs suggested a nice Gradle script I could drop into my project and use to zip the addon up into a distributable jarfile. To see the details, check out my project’s build.gradle file. Once I uploaded it to TestProject, I was able to immediately use it in my own projects (which I did, of course, to test out its integration with the TestProject UI). At that point, I also submitted the addon for review, so TestProject’s team could take a look at it and make sure I wasn’t some nefarious hacker! After that, it was available in the Addon directory.
All told, this was a pretty fun and easy way to encapsulate an interesting Appium technique, and make it available to others who can now use it without needing to understand any programming. I’ll definitely be dreaming up some more addons to contribute to the community. Happy testing! 😉