NOTE: this course uses sample code. You can download this sample code from GitHub at the following url: https://github.com/appium-pro/intro-workshop. (From that site you can either git clone the repo, or download it as a zip file. Either one is fine for this course).
Hello everyone and welcome back to the Appium Pro Intro Workshop. In this module, we are going to explore getting set up with Appium. How do you install Appium? How do you make sure all of its dependencies are working correctly for both iOS and Android? And we'll also look at downloading and setting up the sample code that we'll be using in this workshop. So let's get started.
First of all, let's talk about the requirements for using Appium for the main mobile platforms we care about, iOS and Android. On the iOS side, there are a few requirements. First of all, we need to have Xcode and the Xcode command line tools installed. These are required for launching iOS simulators and in fact launching the test sessions that we rely on via XCUITest. There's another bit of software called Carthage that we also need. Carthage is a dependency manager for Mac OS and iOS applications, and the tools that Appium relies on for automating iOS are built using Carthage as their dependency management system. So that's why we need to make sure we have Carthage installed on our machine as well.
So how do we do this setup exactly? I should point out before we get started that all of the iOS related setup is Mac only. Unfortunately, if you're running on Windows, you won't be able to take advantage of iOS testing with Appium. Apple only supports iOS automation and iOS development on Mac hardware. So, if you don't have your own Mac hardware that you're running, you'll be out of luck for this portion of setup and also for running some of the iOS specific samples that we're going to be looking at later on. Thankfully, I'm basing most of the sample code on Android because Android tests can be run on both Mac and Windows platforms as well as Linux of course too.
Okay, so if you are on a Mac, please follow along with these iOS set up instructions. First of all, you need Xcode. You can get Xcode via the app store, so just download the latest version of Xcode.
If you already have a version of Xcode that's relatively recent, it's probably fine to use with this workshop, so you don't need to update it. But if you do run into problems, it's always a good idea to update to the latest. When you do open Xcode for the first time, it will also prompt you to install additional components. I don't know why these aren't installed already because you have to install them basically to use Xcode anyway, but all that to say make sure you open up Xcode and then allow the installation of these additional components if they haven't already been installed. We also need the Xcode command line tools. Sometimes it's a bit unclear whether these have already been installed in the past. You can always go to a terminal and run the command xcode-select --install, and it will tell you if you've already installed these or not. So I'll demonstrate this command here. xcode select --install, and it tells me "error, command line tools are already installed. Use software update to install updates". Okay, so that means I'm good to go there.
To install Carthage, it's easiest using the Homebrew macOS package installer. So you can get Homebrew if you don't already have it by going to brew.sh, following the instructions there. Most people who do development on Mac already have Homebrew installed, so if you already have it installed or once you have it installed, just run brew, install, Carthage, and Homebrew will update and download a list of all the available packages and then eventually get you the Carthage dependency.
For running our tests in this workshop, we are going to use iOS simulators; these are basically virtual iOS devices like iPhones and iPads and so on that we can run on our computer. Again, this is Mac only, but if you do have a Mac, let's make sure that your iOS simulators are set up and ready to go. iOS simulators come with Xcode. It's just important to make sure that we have the simulators that we're going to need in this training. So, as you can see here on the slide, the latest iOS SDK comes with the latest Xcode by default.
So, whenever you download Xcode, it will come with the most recent version of iOS, which was released at the time that that Xcode was released. This workshop, we're going to be using iOS 13.3. So, if you're using a version of Xcode which is newer than mine when I recorded this training, you might need to proactively download the iOS 13.3 SDK. To do this, we can use the components preferences tab in Xcode. So, let's give a small demonstration of that. I have Xcode already open, and if I go to preferences and then components, you can see these are all the simulators which are available for download. Now, I have iOS 13.3 but it's not shown here. That's because it's sort of built in. So, it's not an available component that I could download because it's already there.
So, it doesn't show up for me. But that's because I already have it. So, if you have a newer version of Xcode, maybe one that comes with iOS 13.4 by default, then you would see iOS 13.3 show up here. So, for this training, it's probably easiest to just download iOS 13.3, which you can do by clicking on the little arrow here. If you don't want to do that, you can also just update the code samples that we're going to be using. That's a pretty easy thing to do as well. So if you don't want to wait for a long time to download simulators or if you don't want to take up quite a lot of disk space, it looks like almost three and a half gigabytes of disk space for each of these SDK versions, you don't have to. You can change the version in your sample code once you have it downloaded later. I will say that you should be using a relatively recent version of iOS 13.2 or three or four for this training. It might not be totally guaranteed to work on much older versions of iOS. Okay.
Oh yes. We should also verify that this simulator actually works. So again, we can do that by going into Xcode. And if you click on the Xcode menu icon and go down to open developer tool, there's a menu item for simulator. And if you click that, then you'll see that we have a simulator booting. Mine is here, but it is invisible for some reason. So I'll go ahead and show you what you can do if you run into this issue as well. You can always go up to hardware and then device, and then you can make sure to pick the specific kind of simulator that you want to open.
So as I said, we're going to be using iOS 13.3 in this training, but whichever version of iOS you're planning on using, you can look inside and see all the different devices which are available for that version of iOS. So I've got a bunch here, including some that were generated automatically by Appium a long time ago. So I think in this training we're going to use the iPhone 11 device configuration. So I'll go ahead and click on that. And then we can see that the simulator is beginning to boot, so go ahead and boot your simulator as well. We can just leave it open for the rest of this training, that way it will be used whenever we come to run our tests. So again, this is a simulator. I can use it just like I could a physical device sitting here, but it is a virtual device that I can use for development and indeed for testing.
Okay, so this is basically what we did. We guaranteed that we had the right kind of iOS SDK, and then we launched an iPhone 11 simulator at that SDK version as well. One other thing we can talk about, if you for some reason don't have the iPhone 11 configuration in your list of devices, you can actually create one. Again, this would be in Xcode, so we can go back to Xcode. This is under the window menu if you go to devices and simulators.
We'll see if we click on the simulators tab, these are all the simulators we have available. I can always create a new simulator by clicking the little plus button down here and give it a name and the type, we can choose iPhone 11, and the iOS version. So if for whatever reason you didn't have your iPhone 11 simulator in the device list in the simulator app. This is where you can go to create one.
Okay. Now let's move on to talk about Android requirements. What you need for Android testing with Appium is first of all, Android Studio. Android Studio is the development environment for Android applications. Android Studio is a where you get the Android SDK Manager, which contains a lot of the different binaries and libraries that Appium relies on to do its thing. So we will need the Android SDK and various of the build tools, all of which you can download using Android Studio. And we will also need Java because a lot of the Android specific software that Appium runs is written in Java.
It's important to note that we need the Java development kit or the JDK, not just the Java runtime environment or JRE. The JDK actually contains the Java compiler and other tools that Appium uses. So we don't just need the ability to run Java, we need the ability to do Java development. I've been using Java 1.8. It's quite ancient, but it works with everything I've done with Appium. 1.8 is a known good version of Java, but newer versions of Java should also work as well.
Okay, let's move on into Android setup. First of all, to get Android Studio, if you don't have it already, you can install it from the Android developer portal at that URL. Then we need to install the SDK platform, tools, build tools, platform tools and emulator images. These are all inside something called the SDK manager, which you would find in Android Studio. There is some documentation there on how to update things. We'll walk through some specific screenshots here so you can see exactly what we need to do.
For Android, the first thing we want to do is get our SDK configured. So when you first open Android Studio, you get this little splash window. And there's a little icon and text that says, configure, down at the bottom. If you click that, you can see SDK manager as an option. So click on that. Then you'll be taken to the preferences for Android Studio to the particular part of the preferences where we can mess with the SDK settings.
There are three tabs here, platforms, tools and update sites. We'll start out on platforms. We want to make sure that we have at least Android 9 or 10. We don't necessarily need all of the other ones, but if you want to be able to test on a given version of Android, you will need the SDK platform for that version of Android. But if you're just starting out fresh, I would say just make sure you have the latest or Android 10 that should work.
Then going over to the tools tab, there are a couple of things we want here. We want the build tools, we want the Android emulator, we want the platform tools and the SDK tools. Importantly, we also want something called the Intel X86 emulator accelerator that is called HAXM for short. We want that because that will help make our emulator run quite a bit faster. Contrary to iOS, our Android test devices are emulators and not simulators, which means that they actually run a emulated Android hardware and not just a kind of software that lives on top of the Mac OS host system or the Windows host system. This emulator accelerator from Intel basically helps all of that virtual machine stuff go a lot faster. It's definitely a requirement for keeping your sanity while doing Android testing.
So how do we set up HAXM? There's some additional stuff that needs to happen here. When you click okay on this screen here, once you've chosen to download HAXM it will download and it will try and install, but it might not work the first time.
Go ahead and go through the install process, but then once you have gone through that process, you'll want to run this command in a terminal. It's kernel extension status basically, is what it stands for. Kextstat. If you pipe that to grep you can look for the phrase Intel. If you get anything that shows up there, that means that the HAXM kernel extension is installed. If you don't get anything showing up there, that means it's not installed. Then you should probably head to the wiki-page that I have linked here in the slide for instructions on installing on Mac OS. You might need to go into your system preferences and allow the kernel extension and then try and reinstall it. That's what you have to do basically, starting with more recent versions of Mac OS because of Apple's security model. I think things should just work via the normal installation on Windows, but if not, this Intel wiki is a great place to go for making sure that HAXM is configured correctly.
Okay. Next we to work on setting certain environment variables. So what are environment variables? Environment variables are just arbitrary variables that we can set in our shell. We're going to be running Appium from the shell and Appium needs to know some things about our system, for example, where all these different pieces that we've downloaded are. So we need to tell Appium where they are by using environment variables.
Here's how we work with environment variables on Mac and Windows. First of all on Mac and also Linux, the place to put environment variables that we want to be around every time we open up a new terminal is in our shell profile or a startup script. If you're using the default bash shell on Mac, then you could put environment variable definitions in your bashrc file in the home directory, or in your bash_profile file.
If you're using a different shell, like I use Z shell, so I've got my environment variables set in a different file. You might be using sh instead of bash, so it all depends on the way your system is set up. If this is a bit confusing, then I would recommend doing a little bit of a terminal and shell tutorial so that you understand a little bit about how to use a terminal, if you've never done that before.
Basically what we want to do ultimately is define these variables, so that Appium knows where some things live on our system. The way we define these variables on Mac and Linux is using the export command. We can export a variable called FOO and set its value to the string, bar. That's what that command would do. If we have this export command in our shell startup script, then every time we open up terminal, the FOO environment variable will be available to us.
The way we verify that environment variables are set is we can use the echo command and then put a $ in front of the variable name and then the shell will print out to us the value of that environment variable. That's a little bit about environment variables on Mac and Linux.
On Windows it's a bit different. You don't manage it in the command prompt itself, you manage it in a control panel. So you go to control panel and then do advanced system settings. And then environment variables. And then you can either edit existing variables or you can click, new system variable. So depending on what we're doing, you might need to create a new variable or you might need to edit an existing one. Once you click on that you'll be able to fill out the new value and OK out and apply, and close control panel, and all of that.
Then you need to open up a new command prompt. You can use the echo command, but with a bit of a different syntax on Windows. On windows you put % around the name of the variable and then the shell, the command prompt, will print that out for you. So on Windows, that's how you do things.
Now let's look at exactly what we need to set.
For Android, that's really what we need all these environment variables for. Here's what we need to set. First of all, we need to set the ANDROID_HOME variable. We want to set this to the location of the Android SDK on our system. So how do we find this location? Well, we can find it in Android Studios SDK manager. So let's have a little look.
If I go to Android Studio and to the SDK manager, up here there's a little box that says Android SDK location. I can look at the path that's here and copy this path. This is going to be my Android home value. You can copy and paste this in as the value of defining the ANDROID_HOME environment variable
We also need to define JAVA_HOME. This is basically set to a directory that's inside the Java development kit. So that Appium knows where to find all the Java compiler tools and so on. On Mac, there's an easy way to get this path. We can run this command /usr/libexec/java_home, and that will print out the path for us. Let's give that a whirl. So, usr/libexec/java_home. You can see that this prints out along path on my system. This is what I should set as the value
On Windows, I don't know of any trick to get it globally, but when you install Java on Windows, it's usually found in C:\Program Files\Java.
Finally, it's useful to add a few things to our path. So Java binaries, for example, that we might want to use or Android binaries that we might want to use. So I'll show you how to update path as well because the path usually has some values in it already.
So here's our paths setup that we want. On Mac and Linux, it looks like this because we're using the export command, to set an environment variable. Now, the PATH is a special environment variable that basically tells our shell which commands we can run without using their fully qualified path. So for example, if I come back here, I just ran this /usr/libexec/java_home command. I can also run it without the /usr/libexec in front because java_home is in my path. So if I echo out my own path environment variable, this is a very, very long thing. But somewhere in there we would see /usr/libexec.
To find out, incidentally, on Mac or Linux where a command is being called from if it's on your path, you can use the which command, e.g., which java_home. And indeed, that tells me that I have been running Java home from /usr/libexec. Okay. Little gratuitous shell tutorial there. So the way that we set the path environment variable on Mac and Linux is to first of all not destroy any information that might already be in the path. So the first thing we do is we re include the path variable that might currently exist and then we add new path elements and we separate these path elements by colons. So the things that we want to add to our path are everything inside $JAVA_HOME/bin. So you can see here that we're actually using an environment variable that we've defined above this, the $JAVA_HOME environment variable. And we're adding its bin sub directory and we're saying make all the commands under $JAVA_HOME/bin available to us. And we do the same thing with $ANDROID_HOME/platform-tools, $ANDROID_HOME/emulator, $ANDROID_HOME/tools, and $ANDROID_HOME/tools/ bin.
So we may not need everything that's in all these different directories to be accessible to us on our shell. But over my years of working with Appium, at some point I've needed some command that's been inside of each of these directories. And so this is the path string that I've found to be most useful. Importantly, if you add this path to the end of your bash profile or wherever you put it, which is a good idea, you'll need to save that and then restart your terminal so that it picks up the new path.
On Windows, it's basically the same idea. It's just we have different syntax. Of course, we have backwards slashes instead of forward slashes. We have semi colons instead of colons. And instead of dollar signs for the environment variables, we have percents around the variable name. So on Windows, where we go to update the path is the same place we went to update the environment variables. So PATH is one of the environment variables, so it might already exist on your system, in which case you just edit it and then add this stuff to the end. And if you do add this stuff to the end, of course you need to make sure to add a semi-colon before all this stuff so that it's appropriately separated from everything that's there before.
If it's not there before, then you can just paste this in as the value of the PATH variable. So I'm just going to show you what it looks like to test that the environment variables are working. If you've done all of this correctly, you should be able to open up a new command prompt or a terminal window and using those syntax that's appropriate for your platform, you should be able to echo out these environment variables and see something there. So I'm first of all going to echo out Java home. We can see that that set and we can also echo out Android home and we can see that that's set for me. And I could echo out my path, I've already done that. But when you echo out path, you should make sure that you can see your Android home and Java home stuff in there that you added.
So if you got something empty, like if I try and echo out a variable which doesn't exist and I just get a blank line, that means that your environment variables not set correctly. So either you put the export command in a file that's not actually being read on your shell startup or you didn't open up a new terminal window after you saved that file. There are a couple of different things that could go wrong, but again, looking up a shell tutorial on profiles and environment variables is useful. If you're not sure what shell you have, you can always echo out the shell environment variable and it will tell you the shell interpreter that you're using. So mine is called Z shell. So that means that for me I need to be using my Z shell profile startup scripts and things like that. Not the batch ones, because the batch ones won't be read by my shell. You're probably using batch if you're on Mac and haven't done any customizations. So putting the environment variables in your bashrc or bash_profile should be sufficient.
Now we need to create our Android virtual device, also known as an AVD or an Android emulator. And we do that by going into Android studio and configuring, just like we did for the SDK manager. But this time we can click on the AVD manager and here's what we want. Basically, we want to click create virtual device. We want to choose a reasonable device definition. It doesn't really matter so much for this training, but Pixel 2 is the one that I've kind of arbitrarily chosen. Select the system image. In my case, Android 10 is reasonably new, API level 29, so that's what I'm recommending you create here. And then you give the AVD a name. You can call it Appium, just for ease of recognition. You can call it anything you want and then you can complete the wizard and finally launch the AVD.
So let me just walk through some of this as well so you can see what it's like. I go to Configure, then AVD manager. Now I already have an Appium AVD here, but if I wanted, I could click create virtual device, click add a Pixel 2 device definition, hit next, use the Android Q API level. Now, we could be using any of these other API levels as well. If you don't have the API system image downloaded, then you can click download and that will download it and then hit next. Now here's where you could call your AVD Appium or whatever. And at this point you don't really need to mess with any of the advanced settings. You can just hit finish. That will create your AVD. I already have one, so I don't need to do that. And then once it's created, you can go over to the right and click the green launch, this AVD button, and then what you will see is an emulator pop up. And the first time it boots, it will go through the whole boot sequence just as if it were a real device that was starting up.
But subsequently when you quit it, it will just save the state. And then the next time you open the emulator, it will launch up in exactly the same state that it saved, which is quite a bit faster. So right now, my emulator is loading its state from the last time that it launched. So once it's up, you can play around with it, check out apps and other things like that. That's a pretty useful thing to do. So I'm not going to wait for my emulator to keep loading here, but you want to just leave it open basically for the Android test that will be running in this workshop. The Android tests we're running, we'll just use whatever emulator is open. So if it's already up and running, then that will save time later. So feel free to go ahead and leave that running.
Okay, now we are ready to talk about Appium itself. So up until this point, everything that we've done is actually not related to Appium at all. It's related to iOS development or Android development. So we just need all of these tools because Appium relies on them for its own operation, but they don't really have anything to do with Appium specifically. We didn't install them because they're unique to Appium. We installed them because they're the kind of general tools that you need for doing iOS and Android development.
So there's actually two ways to install Appium itself. One is using a graphical version of Appium called Appium desktop. You can get the latest version of Appium desktop from gethub.com/appium/appium-desktop. If you go to the releases page, you'll see the most recent one that you can download. So to install it, you basically just
Download the appropriate installer for your platform and install it the way you install any other application and then you launch it. So it can take a little while to open. It's not the most performant application, but it does open after a while and you should see it pop up. So what we want to do is once it pops up, we can just hit start server to verify it works. Let me demonstrate that. Oh, here's my Android Emulator. It finally decided to boot up here. Okay, so right Appium. So when you launch Appium, it looks like this. We can set the host and port that it runs on. Of course, our hosts should be local host or all interfaces here and as default port is 4723 and we can hit start server. Now we can see, okay, great, the Appium server is running. So this is the Appium log and we can, if we want, run our Appium tests on this server. We can then stop the server and close the the log window. The next thing we want to do is we want to edit configurations for the Appium server. If we're going to be running this graphical version of the Appium server, we need to actually put the same Java home and Android home information into the graphical version of Appium because this won't be running from within our shell. So it won't be able to pick up those environment variables appropriately. So when you click edit configurations, you'll be able to just paste in the Android home and Java home values. So do that and hit save and restart. And then Appium desktop will be good to go.
The other way to install Appium, which I recommend you also do, for this tutorial, is using the command line. So Appium is written in Node.js so to run Appium, you need Node.js. You can download it from the Node.js website. Node.js comes with something called NPM, which is for installing Node.js packages. So you can run npm install -g appium, and that will install Appium globally, meaning making the command Appium available to your user. And you can then run the Appium command from any terminal window and you'll see a message pop up that says, welcome to Appium. And it'll tell you the version. Of course this won't work if you already have Appium running from Appium desktop because then they would try and run on the same ports and conflict. So make sure you stop the Appium desktop server before you try this. I'll show you what it looks like on my system.
I already have Appium installed so I can just run Appium and then I get a little message saying that I'm running Appium 1.17 in this case. Okay, I'm just going to go ahead and leave the Appium server running because we're going to use it shortly in some of the more hands on sessions. Something else that's useful when making sure that our configuration is all correct is to run a program called Appium Doctor. Appium doctor is another NPM package which you can install using npm install -g appium-doctor, and then you can run the command just with appium-doctor itself.
So let's give that a try. Got another window here, and I already have Appium doctor installed so I can just run Appium doctor command. And what will happen is that we'll get a bunch of diagnostic output including a bunch of checks if Appium doctors discovered that our system is set up correctly, or maybe some Xs if we discovered that it's not. So depending on what it's doing, it might take a little bit of time to go through all of its different checks. Ultimately what you care about is that all of the necessary dependencies are installed.
So there are two diagnostics that it runs. It runs a diagnostic for unnecessary dependencies and a diagnostic for optional dependencies. So if you have any failures or warnings in your optional dependencies list, don't worry about it. So I have some failures there too, but we don't need them for this tutorial. All we care about is that everything here under necessary dependencies had a nice checkmark by it. Okay.
So at this point we verified that Appium itself is installed correctly, so now we need to get the code set up for this workshop that we're going to be running, which includes the Appium client library and the test samples themselves. So first thing we need to do is get that on your machine.
There's two ways to do that. You can use git if you like using git and clone the repository for this workshop at the URL shown here or you can take advantage of the fact that git hub, where this code is hosted also lets you download a zip file of the latest version of any git repository. So you can just download master.zip from the archives for this workshop's code and unzip it somewhere on your system.
If I go into the intro workshop directory and list out the contents, you can see that there's a couple of things inside here which we're going to look at in more detail later. The thing that we care about right now is downloading the sample apps, the sample iOS app and sample Android app. Of course for Windows we're only going to download the sample Android app, but there is a download helper script here for Mac and Linux or for Windows. So if you are on Mac and Linux, you can run ./download_apps.sh and that will download the apps into the apps directory. On Windows, you can just run download_apps and it will execute the batch file there and do basically the same thing. If that's all working correctly, then you should be able to look inside the apps directory inside your sample code and find a .apk file and a .app.zip file. The .apk file is the Android application and the .app.zip file is the iOS application.
Next thing we want to do is verify that the code compiles. So there are a couple of ways to do this. First of all, on any platform, we can use a Java IDE like Eclipse or IntelliJ to import the sample code and to make sure that it doesn't have any errors. So I'll show us how to do this with IntelliJ. So here is IntelliJ. When you launch it, what you want to do is instead of creating a new project, you want to import a project and then navigate to the intro workshop directory that you've downloaded or cloned or unzipped. So that we have the source directory inside of it and then we can hit open.
And now we want to make sure to import the project from an external model. And this is a Gradle project. So we hit next, usually the default settings here are okay, we want to use the Gradle wrapper that's included with the project and the project JDK here. So we hit finish and at this point IntelliJ will import the project and build it and do everything that it needs to do. If you get a bunch of green check boxes, that means things are good. At this point, if you wanted you can start exploring the code packages here. So that's how you would import it into IntelliJ.
Alternatively, we can actually run Gradle from the command line to compile the Java code that's in the test package. So whether you're on Mac or Linux running ./gradlew compileTestJava will do this for you. So I will do that as well on my terminal.
So ./gradlew compileTestJava (and I had done this recently, so it completed very quickly for me). The first time you run this, a lot of dependencies will be downloaded so it won't complete so quickly. And the dependencies that are downloaded include things like the Appium client, which is how our tests will talk to the Appium server. Okay. At this point, our setup is complete. We have our iOS dependencies, our Android dependencies. We have Appium installed, we've run Appium doctor to make sure it's all working correctly and we've got our sample code up and ready to go. So at this point we're ready to move on into learning to actually use Appium.
.png)
