How to Run Parallel Visual Tests with Appium
Run Appium sessions concurrently, capture repeatable screenshots, and compare them against approved visual baselines across iOS and Android.
To run parallel visual tests with Appium, give each worker its own device or simulator and Appium session, isolate any ports or build paths required by its platform driver, then capture screenshots at repeatable checkpoints and compare them with approved baselines. Appium controls the app and captures the image; a visual regression tool or test library performs the comparison.
Appium supports parallel server processes as well as parallel driver sessions within one server process, according to the Appium parallel testing guide. The correct setup depends on your driver and test runner. Use the current guide for the installed driver version; capabilities and port requirements can change between versions.
1. Pin the Appium environment
Appium 2 separates server and driver versioning. Installing or updating the server does not necessarily install or update the platform driver. Keep the versions used by each CI run visible so a failed run can be reproduced against the same stack. See the Appium migration guide.
Record at least:
- Appium server version and platform driver version.
- Appium client library, test framework, and test runner versions.
- Operating system and device or simulator model and OS version.
- App version or build identifier, locale, and rendering configuration.
Install the Appium server and the driver for your platform using the Appium installation instructions, then consult that driver’s current documentation. Do not copy old Appium 1 setup instructions or assume that another driver’s port capabilities apply to yours.
2. Choose how to run sessions concurrently
There are two documented approaches: run multiple Appium server processes, or create parallel driver sessions through one server process. Choose according to the target driver’s guidance and how your runner starts, tracks, and cleans up sessions. In either model, treat every worker as the owner of one session and one device or simulator.
| Setup | Useful when | Plan for |
|---|---|---|
| Separate server processes | Your CI jobs or workers already manage isolated server processes. | A distinct server endpoint and isolated worker configuration for each process. |
| Multiple sessions on one server | Your driver supports the needed parallel sessions and the runner manages them centrally. | Unique device assignments and every driver-specific resource needed by concurrent sessions. |
Never share a live driver object between test workers. Keep each worker’s logs, screenshots, and session metadata in separate output paths. Include the test name, device or simulator, OS version, and build identifier in the artifact metadata so a failed comparison can be traced to its source.
3. Assign devices and isolate platform resources
iOS with XCUITest
Assign a distinct udid to every active real-device session. For simulators, the XCUITest parallel testing guide also describes identifying each simulator with a unique device name and platform version. Give each parallel session a unique wdaLocalPort and derivedDataPath. If your setup records a video stream, assign a distinct mjpegServerPort as well. See the versioned XCUITest parallel testing guide and the XCUITest capabilities reference.
Use a worker allocation table or equivalent configuration so assignments are explicit. The values below are placeholders: use actual device identifiers and distinct ports and paths available in your environment.
worker 0: device UDID_A, wdaLocalPort PORT_A, derivedDataPath PATH_A
worker 1: device UDID_B, wdaLocalPort PORT_B, derivedDataPath PATH_BTranslate these assignments into the capability format supported by the installed XCUITest driver and client. Do not reuse a port or derived-data directory across simultaneous sessions.
Android with UiAutomator2
The official UiAutomator2 driver documentation confirms support for parallel testing. Assign a distinct connected device to each worker. Check the parallel-testing and capability documentation for the exact installed driver version to identify any required port allocation; do not infer current Android capability names or defaults from old Appium 1 examples.
Before starting a run, confirm that the runner’s device assignment matches the device actually connected to each worker and that no device is assigned to two live sessions.
4. Capture repeatable visual checkpoints
A screenshot is an input to visual testing, not a comparison by itself. At each checkpoint, capture the same app state and send or save the image for comparison against an approved baseline.
- Use deterministic test data and navigate to a known screen state.
- Wait for the app state to settle. Avoid capturing during animations or while asynchronous content is still changing.
- Keep rendering conditions consistent, including locale, theme, device class, and OS version where they affect the image.
- Capture the screenshot through the Appium client or a platform-driver-supported screenshot mechanism.
- Store the raw screenshot and comparison result with the test, build, device, and OS metadata.
- Review differences against the approved baseline and decide whether to accept a changed baseline or fix a regression.
Baseline identity should reflect the app build and rendering conditions that materially affect output. A difference between device classes or OS versions may be expected; compare like with like or maintain separately approved baselines. These are test-design practices, not behavior Appium enforces.
Applitools documents an Appium integration for adding visual checkpoints to Appium scripts. Check its current platform support, pricing, and data handling before adopting it. AWS Device Farm’s Appium documentation covers collecting screenshots and making them available in test reports; that establishes screenshot collection, not that Device Farm itself performs baseline visual regression comparison.
5. Run tests on managed devices when useful
A self-managed lab gives you control over the devices and their state, but your team provisions and maintains them. A managed device service can run Appium tests on hosted devices. AWS Device Farm documents parallel Appium execution on managed devices; its service guide describes hosted Android and iOS devices. Check current device availability, regions, concurrency limits, artifact retention, and pricing before planning a run.
Device execution and visual analysis are separate workflow stages. Verify whether a chosen service only runs tests and collects screenshots, or also integrates with the visual comparison system your team uses. When comparing self-managed and hosted execution, consider OS and device coverage, setup work, control over device state, CI integration, artifact retention, region availability, concurrency limits, and total cost. The available documentation does not establish a universal cost or capacity winner.
6. Organize parallel artifacts and failures
Give every worker its own artifact directory or object-storage prefix. A practical artifact record includes:
- Test case and checkpoint name.
- Worker and Appium session identifiers.
- Device or simulator identifier, model, and OS version.
- App build, locale, theme, and relevant test data version.
- Raw screenshot, baseline identifier, and comparison output.
- Appium server and driver versions, plus worker logs.
Keep the original capture even when a comparison system produces a diff image. Raw captures help distinguish app defects from setup differences, stale baselines, or capture timing problems.
7. Troubleshooting parallel Appium visual tests
| Symptom | Likely cause | What to check |
|---|---|---|
| A session fails to start or attaches to the wrong device | Workers have duplicate, missing, or mismatched device assignments. | Confirm each worker’s device identifier and ensure no device is assigned to two active sessions. |
| iOS sessions fail during startup | Concurrent sessions are contending for WebDriverAgent or build resources. | Use unique wdaLocalPort and derivedDataPath values; if recording a stream, make mjpegServerPort unique too. |
| Android parallel sessions are unstable | The setup may not meet the installed UiAutomator2 driver’s current device or port requirements. | Check the installed driver’s parallel-testing documentation and verify per-worker device and port allocation. Avoid stale Appium 1 capability examples. |
| Visual diffs vary from run to run | The app state or rendering configuration changed before capture. | Inspect raw images; stabilize test data, locale, theme, device conditions, and checkpoint timing before treating a diff as a product defect. |
| Cloud screenshots do not appear in the report | The test may not be writing screenshots to the documented runtime path or may not reach the capture step. | Follow the service’s Appium screenshot instructions. For AWS Device Farm, see its Appium guide and confirm the test writes screenshots during execution. |
| A driver update changes behavior | Appium server and platform driver versions have independent release cadences. | Record and pin both versions, then reproduce with the same client, framework, and device setup. |
| Screenshot exists but no visual result is reported | Capture is configured, but no baseline comparison step is connected to the test. | Submit the capture to the selected comparison library or service and check that the checkpoint is included in its report. |
8. Performance, reliability, and cost considerations
Parallelism increases the number of sessions that can run at once, but the practical limit depends on available devices, driver support, CI capacity, and service concurrency. Adding workers without enough isolated devices or ports can create contention instead of useful throughput. Start with explicit worker-to-device assignments, then scale within the limits documented for your driver and execution environment.
For reliability, preserve per-worker logs and raw screenshots, pin the software stack, and make test checkpoints deterministic. When a run fails, separate session startup failures from app failures and image-comparison failures; they require different fixes.
For cost, account for device lab or hosted-device usage, CI time, visual comparison service pricing, and the effort needed to maintain baselines and test infrastructure. The available sources do not provide enough comparable current pricing or capacity data to recommend a hosted service over a self-managed lab. Check current vendor terms before committing.
Or skip the browser setup
Appium is for controlling mobile apps. If the visual check you also need is a screenshot of a website, ScreenshotNeo captures web pages with one GET request. See the ScreenshotNeo API docs.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers say which page verdict and billing result applied. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up free for 1,000 screenshots a month, with no card required.
FAQ
Does taking an Appium screenshot perform a visual regression check?
No. Appium captures the screenshot; a separate comparison step checks it against an approved baseline.
Can I run parallel sessions through one Appium server?
Appium documents multiple driver sessions in one server process as well as multiple server processes. Confirm that your installed driver supports the intended configuration.
Can I use the same visual baseline for every phone?
Only when the rendering conditions are equivalent for your test. Device class, OS, locale, and other display conditions can affect the expected image.
Does AWS Device Farm automatically compare screenshots to baselines?
The cited Appium documentation establishes screenshot collection and report availability. It does not establish built-in baseline visual regression comparison.
