When Appium 2.0 finally dropped, most of the conversation centered on the driver model — how you now install appium-xcuitest-driver separately, how the monolithic Appium 1.x installation was being broken apart, and whether your existing test suites would survive the migration. The plugin system got a mention in the release notes and then mostly disappeared from team conversations.
That was a mistake. After spending the better part of a year building custom plugins for three different mobile testing setups — two React Native apps and one legacy hybrid — I'd argue the plugin system is the single most consequential architectural change in Appium 2.0. Not because it's flashy, but because it quietly solves problems that used to require forking Appium itself or wrapping it in increasingly fragile middleware.
This isn't a tutorial on installing the images plugin. You've read that. This is about what the plugin system actually enables when you push it, and where it still falls short.
What the Plugin System Actually Is (and Isn't)
Before getting into specifics, it's worth being precise about the architecture because the docs undersell the model. An Appium 2.0 plugin is a Node.js package that hooks into the Appium server's command lifecycle. Every command that flows through Appium — findElement, click, getPageSource, whatever — passes through a middleware chain. Plugins sit in that chain and can intercept, modify, or completely replace command behavior.
The key method is handle. Your plugin class extends BasePlugin, and you override handle to intercept any command by name:
async handle(next, driver, cmdName, ...args) {
if (cmdName === 'findElement') {
// do something before
const result = await next();
// do something after
return result;
}
return await next();
}
What this is not is a driver. Plugins don't talk to devices directly — that's still the driver's job. Plugins manipulate the command layer above the driver. This distinction matters because it defines what plugins are good for: cross-cutting concerns, observability, retry logic, selector transformation. Not device-specific protocol work.
Installing a plugin is straightforward enough:
appium plugin install --source npm appium-wait-plugin
appium --use-plugins=appium-wait-plugin
But building one is where things get interesting.
The Three Use Cases That Actually Justify Building Custom Plugins
I've seen teams reach for plugins for the wrong reasons — usually trying to work around something that should be fixed in their test code. Here are the three scenarios where a plugin genuinely earns its complexity.
1. Centralized retry and flakiness mitigation
Every mobile automation team eventually builds some version of a retry wrapper. Usually it lives in a base page object, or worse, scattered across individual test utilities. The problem is that this approach means your retry logic is client-side, which means it varies across test authors, it doesn't work when you're using generated code or third-party libraries, and it's invisible to your reporting.
A plugin that intercepts findElement and click with configurable retry-with-backoff behavior runs server-side, applies uniformly, and can emit structured logs that your reporting pipeline can actually consume. We built exactly this for one client whose iOS suite was running on a device farm with variable network conditions. The plugin added exponential backoff to element-finding commands, logged every retry with a correlation ID tied to the session, and dropped the flakiness rate from around 23% to under 6% without a single test file change.
The configuration looked like this in the capability:
"appium:pluginConfig": {
"retry": {
"maxAttempts": 3,
"backoffMs": 500,
"commands": ["findElement", "click"]
}
}
2. Selector transformation and abstraction
This one sounds academic until you've maintained a 2,000-test mobile suite across multiple app versions. Selectors break. Accessibility IDs change. XPath expressions that worked on one OS version fail on another. The conventional fix is a centralized element repository, but that still requires test code changes when something breaks.
A selector transformation plugin intercepts findElement calls and applies rules — regex replacements, fallback chains, platform-specific overrides — before the command reaches the driver. We maintained a JSON configuration file that the plugin loaded at startup:
{
"transformations": [
{
"match": "~login-button",
"ios": "~login-button",
"android": "id=com.example.app:id/loginBtn"
}
]
}
This let us update selectors for Android without touching a test file. It's not a silver bullet — you're adding a layer of indirection that makes debugging harder — but for teams running the same logical tests against both platforms, the trade-off is worth it.
3. Session telemetry and observability
Appium's built-in logging is functional but not designed for aggregation. If you're running sessions in parallel across multiple nodes and want to correlate command timings, error rates by command type, or session duration distributions, you're either parsing log files or building something custom.
A telemetry plugin that wraps every command, records timing, and pushes to whatever metrics backend you're using (we used OpenTelemetry with a Grafana backend) gives you observability that actually scales with your infrastructure. The overhead is minimal — we measured under 2ms added latency per command — and the visibility into which commands are slow, which sessions are failing at which steps, and how parallel execution affects timing is genuinely useful for capacity planning on self-hosted device farms.
Where the Plugin System Falls Short
I don't want to oversell this. There are real rough edges.
The plugin API documentation as of Appium 2.4 is still thin. The BasePlugin class has methods that aren't documented anywhere official — you find out about them by reading the source code or asking in the Appium Discord. onUnexpectedShutdown, for example, lets you do cleanup when a session dies unexpectedly, which is useful for telemetry but undocumented.
Plugin loading order matters and isn't always intuitive. If you have multiple plugins that intercept the same commands, they execute in the order specified in --use-plugins. We had a subtle bug where our retry plugin ran before our telemetry plugin, which meant retried commands were logged as single operations — exactly backwards from what we wanted. Swapping the order in the startup command fixed it, but finding the bug took longer than it should have.
Debugging plugins in a running Appium server is also painful. There's no hot reload. You change a plugin, you restart the server, you lose your device session. When you're iterating on plugin logic, this adds up fast. I've started keeping a Makefile target that restarts Appium and immediately re-runs a minimal smoke test just to keep the iteration loop manageable.
Finally, if you're running Appium in a Docker container on CI — which is increasingly common — distributing custom internal plugins requires either publishing them to npm (which you may not want for proprietary code) or volume-mounting the plugin directory and installing from a local path. Neither is as clean as it should be. GitHub Actions with a private npm registry works, but it's more infrastructure than most teams expect.
Making the Decision: Build a Plugin vs. Handle It Elsewhere
The honest answer is that most teams shouldn't build custom plugins immediately. The ecosystem has matured enough that community plugins cover a surprising amount of ground. The appium-wait-plugin, gestures plugin, and relaxed-caps plugin between them address a lot of common pain points. Start there.
Build a custom plugin when you have a cross-cutting behavior that you're currently implementing inconsistently across your test code, when you need server-side observability that client-side code can't provide, or when you're maintaining tests across multiple platforms and need a stable abstraction layer between your test logic and your driver configuration.
Don't build a plugin to work around bad test design, to compensate for elements that are genuinely broken in the app, or because the architecture seems elegant. The plugin system is powerful enough to help you build impressive-looking solutions to the wrong problems.
The teams I've seen get the most out of Appium 2.0's plugin system are the ones who treated it like any other infrastructure investment: defined a specific problem, built the minimum plugin that solves it, measured the outcome, and iterated. That's a less exciting story than "we built a custom plugin framework," but it's the one that actually improves test reliability.
Abdulkadir Akyurt is a QA Engineer and Test Automation Specialist.
Follow me on Medium for more articles · Connect on LinkedIn · Instagram · X / Twitter · Visit abdulkadirakyurt.com