What is Appium Desktop? Appium Desktop is an open-source Graphical User Interface application used for automated mobile application testing. It is supported by Windows, Mac, and Linux. Appium Desktop has two main components: Appium Server; Appium Desktop Inspector; While the Appium Server is used to run the automation test scripts, Appium. Appium Server and Inspector in Desktop GUIs for Mac, Windows, and Linux - appium/appium-desktop Features 🇨🇳 Chinese localization #923 Fixes Fix bug causing search results to not be highlighted #922 Bump up no new command limit to 24 hours #902 updateSettings action call was not being prop. Appium Server and Inspector in Desktop GUIs for Mac, Windows, and Linux - appium/appium-desktop Features 🇨🇳 Chinese localization #923 Fixes Fix bug causing search results to not be highlighted #922 Bump up no new command limit to 24 hours #902 updateSettings action call was not being prop. 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 Desktop is an open source app for Mac, Windows, and Linux which givesyou the power of the Appium automation server ina beautiful and flexible UI. It is a combination of a few Appium-related tools:

• A graphical interface for the Appium Server. You can set options, start/stop the server, see logs, etc... You also don't need to use Node/NPM to install Appium, as the Node runtime comes bundled with Appium Desktop.
• An Inspector that you can use to look at your app's elements, get basic information about them, and perform basic interactions with them. This is useful as a way to learn about Appium or as a way to learn about your app so you can write tests for it.

Download Appium Desktop

You can always pick up the latest release at ourRelease page onGitHub.

If you're on Windows or macOS, Appium Desktop will automatically provide youwith updated versions of the app when they are released. If you encounter[a problem updating, simply delete or uninstall the app and re-download thelatest from the link above.

Note that Appium Desktop is not the same thing as Appium. Appium Desktop isa graphical frontend to Appium with additional tools. Appium Desktop isreleased on its own cadence and has its own versioning system. If you arereporting an issue with Appium Desktop, always be sure to include both theversion of Appium Desktop and the version of the Appium Server which is in use(see below).

If you're on macOS, you will need to install Appium Desktop by copying the appfrom the downloaded DMG file to your own file system (the best place is the'Applications' folder). Running Appium from in side the attached DMG itself isnot supported, and will not work.

Known Issues

• Auto updater is not working for versions < 1.4.1

Usage Instructions

These instructions assume you are already familiar with Appium andAppium-related concepts. If you are new to Appium, please visitappium.io and read our introductory material.

This app provides a convenient way to download and run the Appium automationserver, as well as a tool for inspecting your Android or iOS application. Itsvarious capabilities are described in the following sections.

The server start window

Starting a simple server

When you open Appium Desktop, you are greeted with the server start window. Thebasic option is to start an Appium server with all its defaults and the abilityto modify the host and port. The start button will also let you know whichversion of the Appium server you are running, which can be useful whenreporting issues to the Appium team.

Starting a server with advanced options

By clicking on the 'Advanced' tab, you have the ability to set all the serverflags that are available in Appium. This is for advanced users and should onlybe modified after consulting the Appium documentation.

Server presets

If you use the advanced server options, you have the ability to savea configuration for later use. Simply save the preset on the 'Advanced' tab,and you will subsequently be able to recall and start the server with thatconfiguration from the 'Preset' tab.

The server console output window

Once you start the server, it will launch on the host and port you specified,and open a new window displaying the server log output.

This is fairly straightforward and no real interaction is possible, beyondusing the button to stop the server. You can also copy-and-paste the logs fromthis window which is useful in reporting Appium issues.

One other button is available: 'Start New Session'. Clicking this will open upthe New Session window enabling you to start an Inspector session on thecurrently-running server.

The New Session window

The New Session window allows you to construct a set of Appium desiredcapabilities used to launch an Appium session. You can launch a session againstthe currently-running Appium Desktop server (which is the default), or you canlaunch a session against a variety of other endpoints.

Since it's not required to run against Appium Desktop's own server, you can getto the New Session window without starting an Appium Desktop server. Simply goto 'File' (Windows/Linux) or 'Appium' (Mac) and choose 'New Session...', whichwill open the New Session window without having to start a local server. Inthis case, attaching to the local server will be disabled.

Appium Endpoints

These are the options for launching a session against a non-local Appium server:

Appium Desktop Download

• A custom host/port configuration: this is useful if you want to launch an Inspector session against an Appium server running on another machine in your network, for example.
• Sauce Labs: if you don't have access to, say, iOS simulators on your machine, you can leverage your Sauce Labs account to start an Appium session in the cloud.
• TestObject: you can also utilize TestObject's cloud of real devices for a real device-based Inspector session.

It should be straightforward to get set up with any of these options. Simplyenter your details in the input fields provided.

Desired Capabilities

Desired capabilities are how you configure your Appium session. They tell theAppium server what kind of platform and app you want to automate. If you areunfamiliar with the concept of desired capabilities, or which desiredcapabilities are required to launch Appium sessions of various types, youshould consult the Appium documentation.

Appium Desktop does not restrict your creation of desired capabilities in anyway, nor will it validate them for you. It simply provides a nice UI forentering them in, and saving them for later use. Under the 'DesiredCapabilities' tab, you can use the form fields and '+' button to enter as manydesired capabilities as you need. You will also see a representation of theresulting JSON, which is what is actually sent to the Appium server. This canbe useful for verifying your capabilities, or for copy-and-pasting whenreporting issues.

Once you have set your desired capabilities, you might wish to save them so youcan run the same type of session later. Simply click the 'Save As...' button togive your capability set a name. You can then access it under the 'SavedCapability Sets' tab, for later editing or session launching.

Once your server type and capabilities are set, click 'Start Session' to launchthe Appium Desktop Inspector.

Attach to an Existing Session

If you click on the 'Attach to Session...' tab, you can select an existingsession from a list of currently running sessions on your selected server, or youcan input a session ID of a currently-running session. That session should berunning on the server details you specified in the server type section above.Attaching to an existing session is possible because the Inspector is just anAppium client. This could be useful if you want to debug the middle of a runningtest. When you quit the Inspector window of an existing session, Appium Desktopwill not quit the session as it does normally.

The Inspector

The Inspector is a visual representation of the state of your application alongwith the ability to perform certain interactions in your application throughAppium.

Appium sessions can take some time to load, especially on cloud services, soplease be patient. When the session loads, a screenshot of your app will appearon the left. You can mouse over various UI elements in your application, andsee them highlighted.

In the middle of the Inspector window is your app's hierarchy, represented asXML. You can navigate this tree by clicking through it, or by clicking onelements in the screenshot view. They will then be highlighted.

When an element is highlighted, its information will appear in the detail viewon the right side of the Inspector. This detail view consists of potentialactions to take against the element, and a table of the element's properties.These properties are valuable in determining how the element might accessedusing a particular Appium locator strategy. With an element selected, you canalso 'Tap' the element, or 'Send Keys' to the element (if it is a text field).

When you take such an action with an element, the Inspector will send thecommand to Appium, which will execute it. If the action is successful, a newscreenshot will be generated and you should see the updated state and XML ofyour app. If it's not successful, you'll have an opportunity to see the errormessage.

The top of the Inspector window contains a small toolbar with iconsrepresenting the ability to take certain actions in the Inspector:

• Back (call driver.back)
• Refresh (refresh the source and screenshot)
• Start Recording (open the recorder, see the next section for more information on the recorder)
• Quit the session (call driver.quit and close the Inspector)

The Recorder

Appium Desktop comes with a very basic action recorder, that watches foractions taken using Appium Desktop and displays language-and-framework-specificcode that represents those actions. The code can then be copied-and-pasted intothe appropriate Appium client code and used for tests.

NB: the goal of the Recorder is not to produce production-ready test code.It is designed as a tool to help explore the Appium API, and demonstrate howcertain automation behaviors correspond to method calls in a particularlanguage and Appium library. In sum, it is a learning tool, not a robust codegeneration feature, and should be used as such.

When you start recording, the Inspector will show an additional window:

At first, the Recorder will show no code. You will first have to take someaction, like finding an element in the hierarchy and tapping on it, or sendingkeystrokes to it. When you do this, code will appear in the recorder window,corresponding to the particular language and framework you have chosen (whichcan be adjusted in the drop-down menu at the top right of the Recorder):

This code can be copied to your clipboard using the appropriate button at thetop right of the Recorder pane. Note that by default what is shown are simplylines of code corresponding to the specific actions you have taken whilerecording---in general you cannot paste these lines into an empty text file andrun the code. To run Appium test scripts in code requires that variousdependencies (like the Appium client libraries) be installed, and that scriptboilerplate (like instantiating a driver and initializing a session) bepresent. To show this additional code, you can click the 'Show Boilerplate'button. With boilerplate code shown, it is possible to copy and paste the codeinto a new file and run it.

The power of the Recorder will continue to grow as we add more languages,frameworks, and actions to Appium Desktop.

Conclusion

This is everything you need to know to use Appium Desktop successfully!Remember, Appium Desktop is not a replacement for understanding Appiumitself---it is simply a convenient tool for working with Appium on yourdesktop, and an Inspector for exploring your app. Have fun!

Reporting Issues and Requesting Features

Appium Desktop is open source, and we use GitHub for issue tracking. Pleasesimply report issues at our issuetracker. We will endeavor todetermine whether the issue you are reporting is related to Appium Desktop orAppium Server. If it's not related to Appium Desktop specifically, we willclose the issue and ask you to open a general Appium issue at Appium's mainissue tracker. Please, saveyourselves and us valuable time by getting clear on whether the issue you'reexperiencing is related to Appium Desktop specifically or instead is a generalAppium issue. You can do this by seeing whether the issue reproduces with theAppium command line server as well. If it does, direct your report to Appium'sissue tracker.

Have a feature request? Follow the same process and submit an issue to theappropriate tracker! (Either here in this repo if the request is specificallyfor Appium Desktop, or Appium's main tracker if the request is for Appium moregenerally.)

Advanced Topics and Troubleshooting

Appium can't detect environment variables on Mac

Appium uses environment variables like ANDROID_HOME as well as relying onvarious binaries in your PATH and so on. When running from the command linein an environment where you have set these variables appropriately, Appium hasno problem in picking them up. However, Appium Desktop does not run in a shellor a command-line environment, and so by default it does not have access toenvironment variables you have set in your shell startup script or profile. Towork around this, we use theshell-env package to pick upenvironment variables defined in your shell. This package only looks in certaincommon init scripts, however, like ~/.bashrc, ~/.bash_profile, and~/.zshrc. If you set your Appium environment variables in some other way, youwill need to create one of these default init scripts and set your environmentvariables there as well, so that Appium Desktop will successfully pick them up.

Warnings about being on a read-only file system

This probably means you tried to launch Appium Desktop from the downloaded diskimage (.dmg file). This is not a supported mode of running Appium Desktop. Tocorrectly install Appium Desktop, copy the application from the disk image toyour local filesystem, to somewhere like /Applications. Then, run the appfrom that new location.

Developer Instructions

Want to hack on Appium Desktop? Awesome! Head on over to our ContributingDoc for information on how to get a dev environment set upand submit changes back to the project.

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

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 useappium-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):

Appium Desktop Download For Windows

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 callingwdio.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 automate
• platformVersion: the version of the platform to automate
• deviceName: the kind of device to automate
• app: the path to the app you want to automate (but use the browserName 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 usingnode:

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!

Install Appium Mac

What's Next

Appium Desktop App

We've only scratched the surface of what you can do with Appium. Check outthese resources to help you on your journey:

Appium Download

• 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