Migrate an Appium 2 Framework to Appium 3

TL;DR

Upgrade Node and npm first, isolate the existing extension state, install Appium 3 locally, update compatible drivers, replace removed endpoints and unscoped feature flags, then run a small Android smoke suite locally and in CI. Keep Appium 2 available until the same test set passes in both lanes.

Key Takeaways

• Upgrade to a Node release accepted by Appium 3 and npm 10 or newer before changing Appium.
• Inventory the Appium server, drivers, plugins, clients, flags, endpoints, and CI images before migration.
• Use a project-local Appium installation and isolated APPIUM_HOME to make upgrades reproducible and rollback simple.
• Update drivers separately because Appium core does not bundle platform drivers.
• Replace removed JSONWP endpoints and parameters with W3C endpoints or driver execute methods.
• Prefix every allow-insecure feature with a driver scope or the wildcard scope in Appium 3.
• Prove the migration with server, session, behavior, and CI checks before removing the Appium 2 lane.

To migrate appium 2 framework to appium 3 safely, treat the server, drivers, client library, custom commands, and CI image as separate upgrade surfaces. Appium 3 is a smaller architectural change than Appium 2, but it deliberately removes old protocol behavior and raises the Node.js baseline.

This tutorial gives you a reversible migration path and a runnable JavaScript smoke test. For the wider architecture, platform setup, and scaling guidance, keep the Appium 3 mobile automation complete guide open beside this tutorial.

You will first capture the Appium 2 baseline. Then you will install Appium 3 in an isolated project, restore compatible extensions, update server flags and protocol calls, and prove the result on Android and CI. The same inventory and verification sequence applies to Java, Python, and C# clients even though the sample framework uses WebdriverIO.

What You Will Build

By the end, you will have:

• A project-local Appium 3 server that uses a dedicated extension directory.
• An explicit UiAutomator2 driver installation instead of hidden machine state.
• A WebdriverIO and Mocha smoke test using W3C capabilities.
• Scoped Appium 3 security flags and an optional session-discovery check.
• A dual-lane CI migration with a documented rollback point.

The target layout is small enough to understand but follows production-friendly boundaries:

appium-migration/
├── .appium3/
├── apps/
├── test/
│   └── smoke.spec.js
├── .appiumrc.json
├── package.json
└── package-lock.json

Do not copy the .appium3 directory into source control. Recreate it from declared commands, just as you recreate node_modules.

Prerequisites

Use Node 22.12.0 or newer in the Node 22 line, or another version accepted by Appium 3: ^20.19.0 || ^22.12.0 || >=24.0.0. Use npm 10 or newer. Node 20.19.0 is the minimum in the Node 20 line, not a recommendation to remain on the oldest allowed runtime.

You also need:

• An existing Appium 2 framework and a clean Git branch.
• Android Studio command-line tools, a working JDK, and ANDROID_HOME configured.
• One booted Android emulator or connected device visible to ADB.
• The APK your existing smoke test automates, available at a stable path.
• Shell access on the developer machine and CI runner.

Run these checks before editing the framework:

node --version
npm --version
adb devices
java -version

node --version must satisfy Appium's range, npm --version must start with 10 or later, and adb devices must show one target in the device state. If your team needs detailed extension installation patterns, read install Appium 3 drivers and plugins with the CLI.

Step 1: Audit Before You Migrate Appium 2 Framework to Appium 3

Create evidence before changing anything. Appium core, platform drivers, plugins, and language clients have independent versions. A global appium binary can also differ from the binary CI actually resolves.

From the existing Appium 2 environment, save the following output in your migration ticket or build artifact, not in the new article or application repository:

which appium
appium --version
appium driver list --installed --updates
appium plugin list --installed --updates
npm ls --depth=0
node --version
npm --version

Search the framework for upgrade-sensitive behavior:

rg "/sessions|desiredCapabilities|requiredCapabilities|allow-insecure|relaxed-security|touch/perform|appium/app/(launch|close|reset)|accept_alert|alert_text" . \
  --glob '!node_modules/**' --glob '!dist/**'

Record the server URL and base path too. Appium 2 and 3 normally listen at http://127.0.0.1:4723/, while frameworks inherited from Appium 1 sometimes still append /wd/hub. Keep /wd/hub only if the server is explicitly started with --base-path=/wd/hub or a grid proxy requires it.

Verify the step: confirm the audit states one exact Appium 2 version, every installed driver and plugin, the client dependency version, all server arguments, and every direct HTTP endpoint. Run the existing smoke test once and retain its passing log. That log is your behavioral baseline and rollback proof.

Step 2: Upgrade Node and Isolate Appium 3

Do not overwrite the working Appium 2 environment first. Create or use the framework branch, upgrade its runtime declaration, and install Appium 3 as a development dependency. A local dependency makes npm exec appium resolve the same major version on laptops and CI.

Initialize only if the framework does not already have package.json, then install the migration dependencies:

npm init -y
npm install --save-dev appium@3 webdriverio@9 mocha@11

Add runtime constraints and scripts to package.json. Merge these keys into the existing file rather than replacing its other dependencies:

{
  "engines": {
    "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
    "npm": ">=10"
  },
  "scripts": {
    "appium:version": "appium --version",
    "appium:start": "appium --config .appiumrc.json",
    "test:mobile:smoke": "mocha --timeout 120000 test/smoke.spec.js"
  }
}

Use an isolated Appium home during migration so the new server cannot silently reuse extensions installed for the old server:

export APPIUM_HOME="$PWD/.appium3"
npm exec appium -- --version

Add .appium3/ to the repository's existing ignore file if needed. Do not use appium setup reset against a shared default Appium home unless you intentionally want to remove every installed extension.

Verify the step: npm exec appium -- --version must print a version beginning with 3.. node --version and npm --version must meet the declared engines. Run npm exec appium -- --help to prove the local CLI starts without an engine error.

Step 3: Reinstall and Validate Drivers

Appium 3 still ships without platform drivers. Install only the drivers your framework needs into the isolated home. For this Android example, install UiAutomator2 explicitly:

export APPIUM_HOME="$PWD/.appium3"
npm exec appium -- driver install uiautomator2
npm exec appium -- driver list --installed --updates
npm exec appium -- driver doctor uiautomator2

Do not blindly copy the old Appium home directory. Extension manifests and dependency trees are managed state. Reinstalling makes compatibility failures visible and lets npm resolve the driver against Appium 3. If you also run iOS, perform the XCUITest install and doctor check on a supported macOS runner.

If your audited driver is already installed in an Appium 3 home, use the extension update workflow instead of reinstalling it. Review the candidate release and its peer requirements before changing a production lock point. The Appium 3 driver version management guide covers update policies, pinning, and CI drift controls.

Appium 3 moved application archive handling closer to relevant drivers. A current driver is therefore important when the server receives APK, IPA, or compressed application paths. Update the driver before diagnosing archive behavior as a core server regression.

Verify the step: driver list --installed must show uiautomator2, and the doctor command must complete without required dependency failures. Optional warnings can be evaluated against your use case, but missing ADB, Android SDK, Java, or platform tools must be fixed before proceeding.

Step 4: Migrate Server Flags and Configuration

Appium 3 requires a scope before every feature passed to --allow-insecure. Replace Appium 2 flags such as --allow-insecure=adb_shell with the narrow driver scope --allow-insecure=uiautomator2:adb_shell. Use *:feature_name only when a server feature requires the wildcard or when you intentionally enable a supported feature across drivers.

Put stable server options in .appiumrc.json:

{
  "server": {
    "address": "127.0.0.1",
    "port": 4723,
    "log-level": "info",
    "allow-insecure": [
      "*:session_discovery"
    ]
  }
}

Omit session_discovery if nothing attaches to running sessions. If tests require Android shell execution, add uiautomator2:adb_shell as a separate array item only for trusted local or isolated CI networks. Avoid --relaxed-security; it expands attack surface and hides which capability the suite actually needs.

Start the server:

export APPIUM_HOME="$PWD/.appium3"
npm run appium:start

CLI arguments override config-file values. This is useful for temporary diagnostics, but it can also make CI differ from local runs. The Appium 3 config file setup tutorial explains discovery order and driver-specific configuration.

Verify the step: in a second terminal, run curl --fail http://127.0.0.1:4723/status. Expect a JSON response whose value.ready is true. The server log must list UiAutomator2 and must not report an unscoped insecure feature.

Step 5: Replace Removed Endpoints and Legacy Parameters

Appium 3 removes deprecated JSON Wire Protocol routes and accepts W3C parameters for modified endpoints. Most maintained clients already send the right shape, which is why upgrading the client before rewriting wrappers reduces manual work. Direct HTTP helpers and old custom commands need deliberate review.

For an internal session monitor, migrate the request like this:

const response = await fetch('http://127.0.0.1:4723/appium/sessions');
if (!response.ok) {
  throw new Error(`Session discovery failed: ${response.status}`);
}
const payload = await response.json();
console.log(payload.value);

This endpoint is intentionally unavailable unless session discovery is enabled. Appium Inspector must be version 2025.3.1 or later for the Appium 3 attach-to-session workflow.

Do not replace every old route with a guessed mobile: command. Execute methods belong to drivers and differ by platform. Confirm that the installed driver's documentation supports the chosen method, then keep the call behind a platform adapter.

Verify the step: rerun the rg audit from Step 1. Every match must be removed, intentionally scoped, or documented as a false positive. If session discovery is enabled, the sample request must return an array, even when that array is empty.

Step 6: Run a W3C Android Smoke Test

Set APP_PATH to the APK used by your baseline test and ANDROID_DEVICE_NAME to the emulator or device label. The app path must be absolute so the server does not interpret it relative to a different working directory.

Create test/smoke.spec.js:

const assert = require('node:assert/strict');
const path = require('node:path');
const { remote } = require('webdriverio');

describe('Appium 3 Android smoke', function () {
  let driver;

  before(async function () {
    const appPath = process.env.APP_PATH;
    if (!appPath) throw new Error('Set APP_PATH to an Android APK');

    driver = await remote({
      protocol: 'http',
      hostname: '127.0.0.1',
      port: 4723,
      path: '/',
      capabilities: {
        platformName: 'Android',
        'appium:automationName': 'UiAutomator2',
        'appium:deviceName': process.env.ANDROID_DEVICE_NAME || 'Android',
        'appium:app': path.resolve(appPath),
        'appium:newCommandTimeout': 120
      }
    });
  });

  after(async function () {
    if (driver) await driver.deleteSession();
  });

  it('creates a W3C session and reads the current package', async function () {
    assert.ok(driver.sessionId);
    const currentPackage = await driver.getCurrentPackage();
    assert.equal(typeof currentPackage, 'string');
    assert.notEqual(currentPackage.length, 0);
  });
});

Run the server in one terminal. In another, run:

export APP_PATH="$PWD/apps/your-app.apk"
export ANDROID_DEVICE_NAME="Android"
npm run test:mobile:smoke

The vendor-prefixed appium: keys are W3C extension capabilities. The client wraps them inside the W3C new-session payload, so do not create desiredCapabilities manually. Replace this generic package assertion with one stable user journey from the old baseline once session creation works.

Verify the step: Mocha must report one passing test, the Appium log must show a UiAutomator2 session, and the session must be deleted during teardown. Also confirm the device has no orphaned test session after completion.

Step 7: Prove CI Compatibility and Keep a Rollback

Move the working local setup into CI without relying on a globally preinstalled Appium. Install from the lockfile, set a job-local Appium home, install the declared driver, boot the emulator, start Appium, and wait on /status. The following shell sequence is CI-provider neutral:

npm ci
export APPIUM_HOME="$PWD/.appium3"
npm exec appium -- driver install uiautomator2
npm run appium:start > appium.log 2>&1 &
APPIUM_PID=$!

for attempt in 1 2 3 4 5 6; do
  curl --fail --silent http://127.0.0.1:4723/status && break
  sleep 5
done

curl --fail http://127.0.0.1:4723/status
npm run test:mobile:smoke
TEST_EXIT=$?
kill "$APPIUM_PID" || true
exit "$TEST_EXIT"

Your CI platform still needs its normal Android emulator setup and APP_PATH. Preserve appium.log as an artifact on failure. For iOS, run the XCUITest lane on macOS and keep Android and iOS extension homes or installation steps explicit.

For one or two release cycles, keep an Appium 2 comparison job that runs the same high-value smoke set. Do not let both jobs mutate the same Appium home. Your rollback is the previous lockfile, runtime image, Appium 2 command, extension manifest, and green baseline commit.

Add migration gates that catch more than test assertions. Fail the lane if the server resolves from outside the project, if an extension is missing, or if the log contains an unknown command caused by a removed route. Track startup, session creation, teardown, and app behavior as separate checks. This separation tells you whether a failure belongs to infrastructure, protocol migration, the platform driver, or the application itself.

Also test the operating systems and device types that matter to the release. One passing emulator proves the basic wiring, but it does not validate USB-connected Android devices, macOS signing, real iOS devices, cloud-provider capabilities, or a grid's base-path routing. Add each environment after the core smoke lane is deterministic.

Verify the step: require green server health, session creation, smoke behavior, teardown, and artifact upload in CI. Compare failure categories, not just pass percentages. Once the Appium 3 lane is stable across the team's target devices, remove the temporary Appium 2 job and document the new runtime baseline.

Troubleshooting

Appium exits with an unsupported engine error -> Check the exact Node range. Node 20 must be at least 20.19.0, Node 22 must be at least 22.12.0, and npm must be 10 or newer. Make the CI image and local version manager use the same declared runtime.

The server starts but reports that no driver matches the capabilities -> Run appium driver list --installed with the same APPIUM_HOME used to start the server. Install UiAutomator2 there and preserve appium:automationName with the correct spelling and case.

Appium rejects --allow-insecure -> Add a mandatory scope. Use uiautomator2:adb_shell for Android shell access and *:session_discovery for the server session feature. Do not remove the validation by switching to relaxed security.

A client receives 404 for /wd/hub/session -> The client and server base paths disagree. Use / with the default Appium 3 server, or explicitly start the server with --base-path=/wd/hub while a required proxy is being migrated.

Attach to session or GET /appium/sessions fails -> Enable *:session_discovery, restart Appium, and use GET /appium/sessions, not GET /sessions. Upgrade Appium Inspector to 2025.3.1 or later.

An app archive worked on Appium 2 but fails on Appium 3 -> Update the relevant platform driver, verify the file is a valid supported package, and test an absolute local path. Archive handling moved toward drivers, so inspect the driver log before blaming Appium core.

Where To Go Next After You Migrate Appium 2 Framework to Appium 3

Now that you can migrate appium 2 framework to appium 3, harden the result instead of immediately adding more test cases:

1. Use the complete Appium 3 mobile automation guide to align the framework architecture and platform strategy.
2. Make extension provisioning reproducible with the Appium 3 drivers and plugins CLI tutorial.
3. Centralize stable server behavior with the Appium 3 config file setup tutorial.
4. Define controlled upgrades with Appium 3 driver version management.
5. Improve the surrounding pipeline with a mobile test automation CI strategy.

Keep platform-specific execute methods inside adapters, keep capabilities close to the environment that owns them, and make server logs a standard failure artifact. Those choices turn the one-time upgrade into a maintainable Appium 3 framework.

Interview Questions and Answers

Q: What is the first dependency you check before an Appium 3 migration?

Check Node.js and npm before Appium itself. Appium 3 requires Node ^20.19.0 || ^22.12.0 || >=24.0.0 and npm 10 or newer, so an older runner can fail before the server loads a driver.

Q: Why can Appium 3 start but still fail to automate Android?

Appium core does not bundle platform drivers. UiAutomator2 must be installed in the same Appium home used by the running server, and the session must request it with a vendor-prefixed automation capability.

Q: What changed for insecure feature flags?

A scope prefix is mandatory in Appium 3. Prefer a narrow prefix such as uiautomator2:adb_shell; server features such as session discovery use the wildcard prefix, as in *:session_discovery.

Q: How did active session discovery change?

The deprecated GET /sessions route was replaced by GET /appium/sessions. The new route requires the session_discovery insecure feature, and Appium Inspector must support the new flow.

Q: Why should drivers be upgraded separately from Appium core?

Drivers are independent extensions with their own release cadence and platform dependencies. Appium 3 also delegates relevant archive behavior to drivers, so a compatible current driver is part of the migration, not an optional cleanup.

Q: How do you reduce rollback risk?

Use a project-local Appium dependency, a lockfile, an isolated APPIUM_HOME, a saved Appium 2 inventory, and parallel CI lanes. Roll back the runtime, lockfile, extension provisioning, and config together rather than downgrading only the server binary.

Best Practices and Common Mistakes

• Do pin the Appium major in project dependencies and commit the lockfile. Do not depend on whichever global binary happens to be first on PATH.
• Do provision drivers in the same Appium home used at runtime. Do not copy an old extension directory into a new environment.
• Do upgrade one layer at a time and verify it. Do not change Node, server, drivers, client, capabilities, and tests in one opaque commit.
• Do use W3C capabilities with appium: prefixes. Do not handcraft legacy desiredCapabilities payloads.
• Do scope insecure features narrowly and run Appium on trusted networks. Do not expose a relaxed-security server publicly.
• Do preserve server logs and a representative smoke suite. Do not declare success because /status responds while session creation fails.
• Do keep a time-limited Appium 2 rollback lane. Do not maintain two indefinite framework branches that drift apart.

Conclusion

A reliable Appium 3 migration is an environment and protocol migration, not just npm install -g appium. Upgrade the runtime, isolate extension state, install compatible drivers, scope security flags, replace removed JSONWP behavior, and prove a real session from test code.

Start with the audit and the one-test Android smoke lane in this guide. Once it passes locally and in CI, expand verification to your critical user journeys and platforms, then retire Appium 2 with a known rollback artifact and a documented Appium 3 baseline.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• How to Add CI to a test framework (2026)
• How to Add logging to a test framework (2026)
• How to Add parallel execution to a framework (2026)
• How to Add reporting to a test framework (2026)
• How to Scroll to an element in Cypress (2026)
• How to Scroll to an element in Playwright (2026)