White Paper

Posted September 2, 2021

How-to Guide: Getting Started with Appium - Java Edition

This comprehensive how-to guide was written by Appium project lead Jonathan Lipps. It explores everything you need to get started including issues specific to the Java client and resources to use once your tests are up and running.

Getting started with Appium can seem incredibly easy -- just follow a tutorial online. The online tutorial might explain how to download and install the tool, but it might not be your operating system … or it might be out of date. Once you have Appium installed, most tutorials are trivial; they'll show the testing equivalent for "hello, world." What to do next, what good tests look like, how to structure the tests, get them to run together, connect them to continuous integration, and all the hard work of getting the tests to be part of a software engineering process, all of that is left to the reader to figure out. The online documentation, written by an Open Source project, is likely to be sparse, while the few physical books on the topic are likely out of date before they are published.

Sauce Labs hired Jonathan Lipps, the project lead of the Appium Project and a Sauce employee, and asked him to help solve this problem. The result is our 62-page guide to getting started with Appium using the Java Programming language.

Here's a quick summary of what you'll learn, along with one of the examples.

What is Appium?

Appium is an open-source tool that lives on top of automation tools for Mobile devices, creating a single standard interface for programmers. That interface is extremely familiar to Selenium, creating a logical progression from Selenium to Appium, making the change easy. The interface between iOS and Android is the same, with perhaps a difference in locators. That means the programmers can write essentially the same code, with a lookup table for locators. Like Selenium, Appium has a driver to connect to the device and a client that contains code libraries for all modern programming languages. That means programmers can write code in Java, C#, Ruby, Python, or a host of other languages, likely including the same language they use for writing the production code.

The client for Appium can be a handheld device, an emulator on a local machine, or something in the cloud. The cloud device can be an emulator or Real Device in the Cloud. Switching between the devices is as easy as a config flag; it is common to debug locally and run under Continuous Integration in the cloud.

Getting set up

Appium is free and open, relying on a series of libraries, development toolkits, install tools, all of them free, all under continuous development. The eBook describes not only how to install the tool for Macintosh, Linux and Windows, but also what versions of the libraries are guaranteed to work together. The examples use the IntelliJ development environment, which runs on all major operating systems, and the Gradle Build tool, with a sample application in Github. That means there is nothing to buy and you have everything you need to build a real environment -- not just concepts.

Writing your first Appium test

The tutorial includes Appium Desktop, which provides the tools to both get a server and inspect the application to get locators. The tutorial does more than provide sample code in Java. it explains how to write that code along with a guiding design philosophy. For today, though, here's a simple test program in Appium. Note the core jUnit-like methods: setUp and tearDown with the core test of testLogin().

1
public class IOSLoginTest {
2
        IOSDriver driver;
3
        @Before
4
        public void setUp() throws MalformedURLException, URISyntaxException {
5
        URL appiumUrl = new URL("http://localhost:4723/wd/hub");
6
        URL resource = getClass().getClassLoader().getResource("apps/TheApp-v1.2.1.app.zip");
7
        File app = Paths.get(resource.toURI()).toFile();
8
        DesiredCapabilities caps = new DesiredCapabilities();
9
        caps.setCapability("platformName", "iOS");
10
        caps.setCapability("platformVersion", "11.2");
11
        caps.setCapability("deviceName", "iPhone 7");
12
        caps.setCapability("app", app);
13
driver = new IOSDriver(appiumUrl, caps);
14
}
15

16

17
        @After
18
        public void tearDown() {
19
                try {
20
                        driver.quit();
21
                } catch (Exception ignore) {}
22
        }
23
        @Test
24
        public void testLogin() {
25
        driver.findElement(MobileBy.AccessibilityId("Login Screen")).click();
26
        driver.findElement(By.xpath("//XCUIElementTypeTextField[@
27
        name=\"username\"]")).sendKeys("alice");
28
        driver.findElement(By.xpath("//XCUIElementTypeSecureTextField[@
29
        name=\"password\"]")).sendKeys("mypassword");
30
        driver.findElement(MobileBy.AccessibilityId("loginBtn")).click();
31
        driver.findElement(MobileBy.AccessibilityId("You are logged in as alice"));
32
        } 
33
}
34

After the hello world example, the book explains page objects as a way to structure tests based on re-usable elements of workflow, instead of hard-coded values and links. This separation from the abilities of the page (where the "page" is an object with methods and data) and the writing of the business logic test to exercise that page, creates easier-to-read, reusable tests that are less brittle. That results in a login test that looks like this, where setup and teardown are pushed into a "BaseTest" class.

1
public class IOSLoginTest extends BaseTest {
2
        @Test
3
        public void testLogin() {
4
                final String username = “alice”;
5
                final String password = “mypassword”;
6
               mainView.navToLogin();
7
                loginView.login(username, password);
8
                String loggedInUsername = loggedInView.getLoggedInUsername();
9
                Assert.assertEquals(loggedInUsername, username);
10
                } 
11
}

Gradle, the Cloud, and Continuous Integration

Once the code runs in an IDE, the next step is to push it to the command line, run it on a schedule as part of Continuous Integration (CI) and get the results back into CI. The eBook takes you how to do that step-by-step, along with tips about how to abstract the server into a factory, allowing you to switch between operating systems, devices, local and the cloud with parameters or environmental variables. The paper even includes advice on how to set up the test run under Jenkins, including either local or using the Jenkins plugin for Sauce Labs. The whitepaper ends on additional resources and where to go for support.

Get started!

This guide draws upon Jonathan’s unique insights and knowledge along with that of maintainers and contributors of the Appium Java client. It details out various software, versions used and common issues to help you reproduce code samples used in the guide. It also has links to handy resources you may need once your tests are up and running, like a reference card for Appium setup and commands.

Fill in the form at right and click 'Download' to access this comprehensive guide and get started on your Appium testing journey!

Published:

Sep 2, 2021

Download white paper