Edit this Doc Getting Started
This doc will get you up and running with a simple Appium test and introduceyou to some basic Appium ideas. For a more comprehensive introduction to Appium concepts,please check out the conceptual introduction.
Installing Appium
Appium can be installed in one of two ways: via NPM or bydownloading Appium Desktop, whichis a graphical, desktop-based way to launch the Appium server.
The Mac Driver (for Mac Desktop apps) Verifying the Installation. To verify that all of Appium's dependencies are met you can use appium-doctor. Install it with npm install -g appium-doctor, then run the appium-doctor command, supplying the -ios or -android flags to verify that all of the dependencies are set up correctly. Edit this Doc The Mac Driver for OS X. Appium has beta support for automation of OS X desktop applications. Development of this driver happens at the appium-mac-driver, and relies on a native OS X binary called AppiumForMac. Requirements and Support (In addition to Appium's general requirements) Mac OS X 10.7. Appium’s desktop app supports OS X, Windows and Linux Appium-Desktop for OSX, Windows and Linux We're open for discussion and would love to hear your voice in the conversation about the future of mobile apps testing!
- Appium Server and Inspector in Desktop GUIs for Mac, Windows, and Linux - appium/appium-desktop.
- Download our Appium ebook to learn best practices, tips & tricks, and more. Appium Desktop for Mac, Windows and Linux. Appium Desktop is an open-source application running on Mac OS X, Windows, and Linux operating systems. It combines two essential components of Appium: Appium Server: Server instance for enabling testing (and test automation.
Installation via NPM
If you want to run Appium via an
npm install
, hack with Appium, or contributeto Appium, you will need Node.js and NPM (usenvm,n, or brew install node
to installNode.js. Make sure you have not installed Node or Appium with sudo
, otherwiseyou'll run into problems). We recommend the latest stable version, thoughAppium supports Node 10+.The actual installation is as simple as:
Installation via Desktop App Download
Simply download the latest version of Appium Desktop from the releasespage.
Driver-Specific Setup
You probably want to use Appium to automate something specific, like an iOS orAndroid application. Support for the automation of a particular platform isprovided by an Appium 'driver'. There are a number of such drivers that giveyou access to different kinds of automation technologies, and each come withtheir own particular setup requirements. Most of these requirements are thesame requirements as for app development on a specific platform. For example,to automate Android applications using one of our Android drivers, you'll needthe Android SDK configured on your system.
At some point, make sure you review the driver documentation for the platformyou want to automate, so your system is set up correctly:
- The XCUITest Driver (for iOS and tvOS apps)
- The Espresso Driver (for Android apps)
- The UiAutomator2 Driver (for Android apps)
- The Windows Driver (for Windows Desktop apps)
- The Mac Driver (for Mac Desktop apps)
Verifying the Installation
To verify that all of Appium's dependencies are met you can use
appium-doctor
. Install it with npm install -g appium-doctor
, then run theappium-doctor
command, supplying the --ios
or --android
flags to verifythat all of the dependencies are set up correctly.Appium Clients
When all is said and done, Appium is just an HTTP server. It sits and waits forconnections from a client, which then instructs Appium what kind of session tostart and what kind of automation behaviors to enact once a session is started.This means that you never use Appium just by itself. You always have to use itwith a client library of some kind (or, if you're adventurous, cURL!).
Luckily, Appium speaks the same protocol asSelenium, called the WebDriver Protocol. You cando a lot of things with Appium just by using one of the standard Seleniumclients. You may even have one of these on your system already. It's enough toget started, especially if you're using Appium for the purpose of testing webbrowsers on mobile platforms.
Appium can do things that Selenium can't, though, just like mobile devices cando things that web browsers can't. For that reason, we have a set of Appiumclients in a variety of programming languages, that extend the regular oldSelenium clients with additional functionality. You can see the list of clientsand links to download instructions at the Appium clientslist.
Before moving forward, make sure you have a client downloaded in your favoritelanguage and ready to go.
Starting Appium
Now we can kick up an Appium server, either by running it from the command linelike so (assuming the NPM install was successful):
Or by clicking the huge Start Server button inside of Appium Desktop.
![Download Appium Desktop For Mac Download Appium Desktop For Mac](/uploads/1/2/7/5/127546805/995103132.png)
Appium will now show you a little welcome message showing the version of Appiumyou're running and what port it's listening on (the default is
4723
). Thisport information is vital since you will have to direct your test client tomake sure to connect to Appium on this port. If you want to change, the port,you can do so by using the -p
flag when starting Appium (be sure to check outthe full list of serverparameters).Running Your First Test
In this section we'll run a basic 'Hello World' Android test. We've chosenAndroid because it's available on all platforms. We'll be using theUiAutomator2 Driver so ensureyou've read through that doc and gotten your system set up appropriately. We'llalso be using JavaScript as the language so that we don't have to deal withadditional dependencies.
(Chances are, you'll eventually want to automate something other than Androidusing something other than JavaScript. In that case, check out oursample-code, which has codesamples for many languages and platforms.)
Prerequisites
- We'll assume you have an Android 8.0 emulator configured and running (the example will work on lower versions, just fix the version numbers accordingly)
- We'll assume you have this test APK downloaded and available on your local filesystem
Setting up the Appium Client
For this example, we'll use Webdriver.io as our Appiumclient. Create a directory for this example, then run:
Once the project has been initialized, install
webdriverio
:Session Initialization
Now we can create our test file, named
index.js
, and initialize theclient object:The next thing we need to do is to start an Appium session. We do this bydefining a set of server options and Desired Capabilities, and calling
wdio.remote()
with them. Desired Capabilities are just a set of keys andvalues that get sent to the Appium server during session initialization, thattell Appium what kind of thing we want to automate. The minimum set of requiredcapabilities for any Appium driver should include:platformName
: the name of the platform to automateplatformVersion
: the version of the platform to automatedeviceName
: the kind of device to automateapp
: the path to the app you want to automate (but use thebrowserName
capability instead in the case of automating a web browser)automationName
: the name of the driver you wish to use
For more information on Desired Capabilities and for a list of all theCapabilities you can use in Appium, see our Capabilitiesdoc.
So here is how we begin to construct a session in our test file:
Running Test Commands
You can see that we've specified our Appium port and also constructed ourDesired Capabilities to match our requirements (but don't forget to replace thepath with the actual download path for your system). We've registered this factwith
webdriverio
and now have a client object which will represent theconnection to the Appium server. From here, we can go ahead and start thesession, perform some test commands, and end the session. In our case, we willsimply type into a text field and check that the correct text was entered:What's going on here is that after creating a session and launching our app,we're instructing Appium to find an element in the app hierarchy and type intoit. The same field is then queried for its text, which is asserted to be what weexpect.
Putting it all together, the file should look like:
You can try and run this test on your own. Simply save it and execute it using
node
:If everything is set up correctly, you'll see Appium begin spitting outlots of logs and eventually the app will pop up on the screen and startbehaving as if an invisible user were tapping on it!
What's Next
We've only scratched the surface of what you can do with Appium. Check outthese resources to help you on your journey:
- The Appium command reference - learn about what commands are available, how to use them with specific client libraries, etc...
- The sample-code directory, where lots more code samples are available
- discuss.appium.io - this is the Appium community forum, which is a great first place to go for help getting started, or if you think you may have run into a bug
- The Appium issue tracker - let the Appium maintainers know here if you think you've found a bug
Edit this Doc Getting Started
This doc will get you up and running with a simple Appium test and introduceyou to some basic Appium ideas. For a more comprehensive introduction to Appium concepts,please check out the conceptual introduction.
Installing Appium
Appium can be installed in one of two ways: via NPM or bydownloading Appium Desktop, whichis a graphical, desktop-based way to launch the Appium server.
Installation via NPM
If you want to run Appium via an
npm install
, hack with Appium, or contributeto Appium, you will need Node.js and NPM (usenvm,n, or brew install node
to installNode.js. Make sure you have not installed Node or Appium with sudo
, otherwiseyou'll run into problems). We recommend the latest stable version, thoughAppium supports Node 10+.The actual installation is as simple as:
Installation via Desktop App Download
Appium Desktop Download
Simply download the latest version of Appium Desktop from the releasespage.
Driver-Specific Setup
You probably want to use Appium to automate something specific, like an iOS orAndroid application. Support for the automation of a particular platform isprovided by an Appium 'driver'. There are a number of such drivers that giveyou access to different kinds of automation technologies, and each come withtheir own particular setup requirements. Most of these requirements are thesame requirements as for app development on a specific platform. For example,to automate Android applications using one of our Android drivers, you'll needthe Android SDK configured on your system.
Download Appium Server
At some point, make sure you review the driver documentation for the platformyou want to automate, so your system is set up correctly:
- The XCUITest Driver (for iOS and tvOS apps)
- The Espresso Driver (for Android apps)
- The UiAutomator2 Driver (for Android apps)
- The Windows Driver (for Windows Desktop apps)
- The Mac Driver (for Mac Desktop apps)
Verifying the Installation
To verify that all of Appium's dependencies are met you can use
appium-doctor
. Install it with npm install -g appium-doctor
, then run theappium-doctor
command, supplying the --ios
or --android
flags to verifythat all of the dependencies are set up correctly.Appium Clients
When all is said and done, Appium is just an HTTP server. It sits and waits forconnections from a client, which then instructs Appium what kind of session tostart and what kind of automation behaviors to enact once a session is started.This means that you never use Appium just by itself. You always have to use itwith a client library of some kind (or, if you're adventurous, cURL!).
Luckily, Appium speaks the same protocol asSelenium, called the WebDriver Protocol. You cando a lot of things with Appium just by using one of the standard Seleniumclients. You may even have one of these on your system already. It's enough toget started, especially if you're using Appium for the purpose of testing webbrowsers on mobile platforms.
Appium can do things that Selenium can't, though, just like mobile devices cando things that web browsers can't. For that reason, we have a set of Appiumclients in a variety of programming languages, that extend the regular oldSelenium clients with additional functionality. You can see the list of clientsand links to download instructions at the Appium clientslist.
Before moving forward, make sure you have a client downloaded in your favoritelanguage and ready to go.
Starting Appium
![Download Appium Desktop For Mac Download Appium Desktop For Mac](/uploads/1/2/7/5/127546805/110464380.png)
Now we can kick up an Appium server, either by running it from the command linelike so (assuming the NPM install was successful):
Or by clicking the huge Start Server button inside of Appium Desktop.
Appium will now show you a little welcome message showing the version of Appiumyou're running and what port it's listening on (the default is
4723
). Thisport information is vital since you will have to direct your test client tomake sure to connect to Appium on this port. If you want to change, the port,you can do so by using the -p
flag when starting Appium (be sure to check outthe full list of serverparameters).Running Your First Test
In this section we'll run a basic 'Hello World' Android test. We've chosenAndroid because it's available on all platforms. We'll be using theUiAutomator2 Driver so ensureyou've read through that doc and gotten your system set up appropriately. We'llalso be using JavaScript as the language so that we don't have to deal withadditional dependencies.
(Chances are, you'll eventually want to automate something other than Androidusing something other than JavaScript. In that case, check out oursample-code, which has codesamples for many languages and platforms.)
Prerequisites
- We'll assume you have an Android 8.0 emulator configured and running (the example will work on lower versions, just fix the version numbers accordingly)
- We'll assume you have this test APK downloaded and available on your local filesystem
Setting up the Appium Client
For this example, we'll use Webdriver.io as our Appiumclient. Create a directory for this example, then run:
Once the project has been initialized, install
webdriverio
:Session Initialization
Now we can create our test file, named
index.js
, and initialize theclient object:The next thing we need to do is to start an Appium session. We do this bydefining a set of server options and Desired Capabilities, and calling
wdio.remote()
with them. Desired Capabilities are just a set of keys andvalues that get sent to the Appium server during session initialization, thattell Appium what kind of thing we want to automate. The minimum set of requiredcapabilities for any Appium driver should include:platformName
: the name of the platform to automateplatformVersion
: the version of the platform to automatedeviceName
: the kind of device to automateapp
: the path to the app you want to automate (but use thebrowserName
capability instead in the case of automating a web browser)automationName
: the name of the driver you wish to use
For more information on Desired Capabilities and for a list of all theCapabilities you can use in Appium, see our Capabilitiesdoc.
So here is how we begin to construct a session in our test file:
Running Test Commands
You can see that we've specified our Appium port and also constructed ourDesired Capabilities to match our requirements (but don't forget to replace thepath with the actual download path for your system). We've registered this factwith
webdriverio
and now have a client object which will represent theconnection to the Appium server. From here, we can go ahead and start thesession, perform some test commands, and end the session. In our case, we willsimply type into a text field and check that the correct text was entered:What's going on here is that after creating a session and launching our app,we're instructing Appium to find an element in the app hierarchy and type intoit. The same field is then queried for its text, which is asserted to be what weexpect.
Putting it all together, the file should look like:
You can try and run this test on your own. Simply save it and execute it using
node
:If everything is set up correctly, you'll see Appium begin spitting outlots of logs and eventually the app will pop up on the screen and startbehaving as if an invisible user were tapping on it!
What's Next
We've only scratched the surface of what you can do with Appium. Check outthese resources to help you on your journey:
- The Appium command reference - learn about what commands are available, how to use them with specific client libraries, etc...
- The sample-code directory, where lots more code samples are available
- discuss.appium.io - this is the Appium community forum, which is a great first place to go for help getting started, or if you think you may have run into a bug
- The Appium issue tracker - let the Appium maintainers know here if you think you've found a bug