# AppiumTestDistribution: running one Appium suite across many devices
> AppiumTestDistribution is an Appium plugin that distributes a single test run across several Android and iOS devices at once, and it can point the same tests at Sauce Labs, BrowserStack or LambdaTest. It suits a mobile team that has outgrown a single device and a single platform, and it depends on Appium 2 and a specific plugin setup.
**AppiumTestDistribution/AppiumTestDistribution** — A tool for running android and iOS appium tests in parallel across devices... U like it STAR it !
- Repository: https://github.com/AppiumTestDistribution/AppiumTestDistribution
- Website: https://saikrishna321.github.io/
- Stars: 1,042 · Forks: 366
- Language: Java
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/appiumtestdistribution-appiumtestdistribution
## The plugin layer, and why the coordinates are confusing
AppiumTestDistribution is a tool for running Android and iOS Appium tests in parallel across devices, and it is built as an Appium plugin rather than as a separate test runner. That is the key structural decision, and it explains the rest of the design.
Because it sits inside Appium, your existing test suite does not change. The same TestNG classes or the same Cucumber features run, and the plugin decides which device each one lands on. The README links separate wiki pages for configuring tests for TestNG and for Cucumber using teswiz, which tells you that both paths are supported and that the Cucumber path was added later.
The installation instructions are where the project is confusing, and the confusion is worth understanding before you start. There are two sets of Maven coordinates, and they are not the same artifact.
For the master branch, the dependency is:
```xml
com.github.AppiumTestDistribution
AppiumTestDistribution
latest_commit
```
which needs a JitPack repository declared:
```xml
jitpack.io
https://jitpack.io
```
And the released Maven Central version uses a different group id, com.github.saikrishna321, with version 13.1.0. So the coordinates track the repository rename, and the two lines have diverged. Pick the line you want deliberately rather than copying whichever snippet appears first.
## Appium 2 and the device farm plugin are prerequisites
The README states the requirement in one line, and it is not optional: make sure you have Appium v2.0 installed and the appium-device-farm plugin installed.
The package manifest confirms the shape of the dependency. The appium dependency is at 2.2.1 or newer, and the development dependencies include appium-device-farm at 8.4.7-rc.1, the uiautomator2 driver at 2.29.5 for Android, and the xcuitest driver at 5.8.2 for iOS. The uiautomator2 and xcuitest drivers are the two platform drivers Appium needs for real devices, and the device farm plugin is the part that does the distribution.
The manifest also shows that this is a Java project with a JavaScript documentation layer beside it. The main entry is lib/index.js with a typedoc configuration pointing at it, and the scripts are all about documentation: a build:docs script that runs appium-docs build, a publish:docs script that builds and pushes to a docs-site branch, and an install-docs-deps script. The package.json is not the runtime, it is the docs pipeline.
The repository layout follows the same split. There is src/ and lib/ for the Java and JavaScript code, caps/ for capabilities, configs/ for configuration, apps/ for the sample applications, docs/ for the documentation sources, a mkdocs.yml for the site build, an azure-pipelines.yml alongside a .circleci/ directory for continuous integration, and a .checkstyle/ directory with a checkstyle/ folder for the Java style rules.
## One suite, many devices, across both platforms
The capability the project advertises is running the same tests in parallel across multiple devices, and the README makes the cross-platform case explicitly. The sample test project is a Page Object pattern Appium framework, and the point made is that if your application is cross-platform and you build a Page Object pattern framework, you can run those tests across Android and iOS devices connected to the same Mac OS X host.
The example given is concrete: with 3 Android and 3 iOS devices connected to the same machine, the tests execute in parallel on both platforms. That is a meaningful saving when a mobile regression suite is measured in hours rather than minutes, and it is a saving that is hard to get any other way, since the alternative is six separate runs.
The two things that make it work are the page object structure on your side and the plugin on the tool side. The plugin takes the suite and assigns work to the connected devices, and the page object framework means the same test body can drive either platform, because the differences live in the page classes rather than in the test.
The FAQ adds a useful piece of colour about the iOS side. Running multiple iOS simulators is supported, with the caveat that this requires Appium 1.6.6.beta with Xcode 9 beta in the version the README was written against. That answer is old enough that it is better treated as a historical note than as current guidance, and the current supported path is the xcuitest driver listed in the manifest.
## Cloud providers, and how the configuration differs
Beyond local devices, the project documents configuration paths for three cloud device farms: Sauce Labs, BrowserStack and LambdaTest, each with its own wiki page.
That matters because the point of a device farm is access to a wide range of real hardware and OS versions, which is exactly what a local rack of phones cannot give you. The README also shows LambdaTest as a sponsor of the project, with the logo in the support section.
Video logging is switched on with an environment variable when you run the suite:
```
VIDEO_LOGS="true" mvn clean -Dtest=Runner test
```
Video logging is the feature worth understanding before you turn it on. The README states that videos will be logged for failure tests, and the video log prerequisites are ffmpeg installed on the host, with the macOS route given as a Homebrew install and the Windows route pointing at the ffmpeg download page. The mp4box tag in the repository topics points at the tool used to work with the recorded MP4 files afterwards.
There is also a ReportPortal integration, which is a single line: add LISTENERS=com.epam.reportportal.testng.ReportPortalTestNGListener to config.properties to send the data to ReportPortal. That is a TestNG listener, so it fits into the existing TestNG execution model rather than replacing it.
The repository carries a credentials.json file at the top level, which is the file where cloud provider keys and device configuration would live, and the.gitignore is what keeps it out of a shared checkout.
## Real device iOS testing has requirements the FAQ is honest about
The FAQ section is the most useful part of the README, because it covers the cases where Appium on real iOS devices is difficult, and the answers are specific rather than reassuring.
Automating an app that is already installed from the App Store is possible with the XCUITest framework, available from iOS 9.3, by using the application's bundle ID instead of the app capability. To find the bundle ID you connect the device, run ideviceinstaller -l, or with a udid argument when several devices are attached, and read the name and identifier from the list. The FAQ also notes the limitation of that approach: WebView content would not be reachable.
The catch is that Appium still needs WDA built and deployed on the real device, which means a valid certificate and a provisioning profile, and the answer links to the xcuitest driver documentation for that configuration. Where the tests need to interact with WebViews, or where the iOS version has no XCUITest support, Appium falls back to the instruments application, and the FAQ says plainly that it will not work with any application that is not in debug mode.
The other troubleshooting entries follow the same pattern. If an app or IPA is not in debug mode, instrumentation fails. An app targeted at the simulator will not work on a real device and vice versa, and the device's developer option in settings has to be checked. If installation during automation fails, the suggestion is to try installing with ideviceinstaller -i ipa_name and, failing that, check the provisioning profile.
For a project whose whole purpose is running against real hardware, having the failure modes written down like this is worth more than another feature.
## Conclusion
Adopt AppiumTestDistribution when you have several physical devices or simulators on one host and want a single test run to spread across them, because the distribution happens at the Appium plugin layer, so the same TestNG or Cucumber suite runs unchanged. Do not adopt it if you have one device, since the plugin adds setup without buying anything. Before you start, install Appium 2.0 and the appium-device-farm plugin, because the README makes both a prerequisite, and note that the released Maven artifact is 13.1.0 while the master branch coordinate uses a latest_commit version, so pin deliberately which one you build against.
## FAQ
### How do I add AppiumTestDistribution to a Maven project?
For the master branch add the dependency with groupId com.github.AppiumTestDistribution, artifactId AppiumTestDistribution and version latest_commit, together with a JitPack repository entry pointing at https://jitpack.io. The released Maven Central version uses groupId com.github.saikrishna321 with version 13.1.0. You also need Appium v2.0 and the appium-device-farm plugin installed.
### Can I run the same Appium tests on Android and iOS devices in parallel?
Yes. The README describes a Page Object pattern framework that can run across Android and iOS devices connected to the same Mac OS X host, and gives the example of 3 Android and 3 iOS devices executing the tests in parallel on both platforms.
### How do I enable video logging of failed tests in AppiumTestDistribution?
Set the flag and run the suite, for example `VIDEO_LOGS="true" mvn clean -Dtest=Runner test`. The README says videos are logged for failure tests, and ffmpeg must be installed on the host, through Homebrew on macOS or the Windows build.
### Can AppiumTestDistribution run against cloud device farms?
Yes, the project documents separate configuration guides for Sauce Labs, BrowserStack and LambdaTest. The same config.properties file also carries the ReportPortal listener, LISTENERS=com.epam.reportportal.testng.ReportPortalTestNGListener, for sending test data to ReportPortal.
## Sources
- [AppiumTestDistribution/AppiumTestDistribution on GitHub](https://github.com/AppiumTestDistribution/AppiumTestDistribution)
- [License: MIT](https://github.com/AppiumTestDistribution/AppiumTestDistribution/blob/main/LICENSE)
- [Project website](https://saikrishna321.github.io/)
- [README](https://github.com/AppiumTestDistribution/AppiumTestDistribution/blob/main/README.md)
- [Releases](https://github.com/AppiumTestDistribution/AppiumTestDistribution/releases)
---
Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/appiumtestdistribution-appiumtestdistribution