Skip to content

From Appium

This guide ports upstream’s docs/migrate/appium.mdx (tester-army/e2e at e83fdf9, from tester-army/e2e#1597, #1579, #1602, and #1651). Upstream’s examples are WebdriverIO and its target is TypeScript. The port’s target is a .NET test project with a MobileAppTest base class, and the source examples use the Appium .NET client (Appium.WebDriver). The tables name the WebdriverIO calls and the mobile: commands every client sends. A .NET call maps the same way: driver.FindElement(AppiumBy.AccessibilityId("x")).Click() is $('~x').click(), SendKeys is setValue, driver.ActivateApp(id) is driver.activateApp(id), and driver.ExecuteScript("mobile: ...") is driver.execute('mobile: ...').

e2e replaces the Appium server, its drivers, and the client library with the E2E.Mobile.NUnit, E2E.Mobile.XUnit.V3, or E2E.Mobile.TUnit package. It drives iOS simulators, Android emulators, and connected phones through agent-device, which it starts through npx, so Node 22.12 or newer must be on PATH. Capabilities become a target in e2e.config.json, and driver commands become the Device and App members. Your app build and its accessibility ids stay as they are.

The source examples use the Appium .NET client. A WebdriverIO, Java, or Python client maps the same way.

Migrate this project's Appium tests to e2e, one test at a time. Docs: the "From Appium" page of the e2e-dotnet docs site (docs-site/src/content/docs/migrate/appium.mdx).
1. Read the migration guide. It maps Appium capabilities, selectors, and commands to e2e, and lists what e2e doesn't have yet.
2. Ask me where the .NET test project should live and whether to use NUnit or xUnit v3. Run `e2e init <directory> --yes --engine mobile` (add `--framework xunit` for xUnit v3). It creates the project with E2E.Mobile.NUnit (or E2E.Mobile.XUnit.V3) and an example test. Rewrite the example for your app or delete it.
3. Read the e2e skill (`e2e guide` prints it, `e2e guide mobile` prints the mobile topic) and follow it for every step below.
4. If you ran init, ask me which model to use for agent steps. If it needs a sign-in, give me the `e2e login <provider>` command and wait until I confirm.
5. Port the capabilities into e2e.config.json with the guide's table: one target for the platform, with app.bundleId, app.appPath, app.launchArguments, and app.permissions. Keep passwords and tokens out of the config.
6. Run `e2e doctor` and fix what it reports.
7. List the Appium tests and ask me which one to move first. Suggest one with XPath selectors or explicit waits that often break.
8. Rewrite that test as a test class that derives from MobileAppTest, with the guide's tables. Follow "Rewrite selectors": XPath has no port, and e2e fails on several matches. Before you port a test, check the guide's "What e2e doesn't have yet" section for each capability and command the test uses. Use the "Use today" workaround, or leave that test in Appium and tell me why.
9. Keep the final assertions deterministic, with Expect.That. Where a run of scripted taps breaks often, propose an Agent.ActAsync goal for it instead.
10. Run the new class on a booted simulator or emulator with `dotnet test --filter` and fix it until it passes. Keep the Appium test until I confirm it can go.
11. Summarize which tests moved, which stayed in Appium, and why.

For a migration that spans several sessions, the migrate-to-e2e skill records what moved in a progress file and keeps the old suite running until you retire each test. See Coding agents.

Set up a target with the mobile guide and a model with the web guide. Only agent steps need a model.

Appium e2e
platformName, appium:automationName platform on the target (ios or android), or E2E_MOBILE_PLATFORM. The port runs one device target, so the variable switches it. Nothing to set for the automation name
appium:deviceName, appium:udid MobileOptions.Device, or E2E_MOBILE_DEVICE: a name, a simulator UDID, or an emulator-5554 serial. A phone goes by its name. MobileOptions.Devices is a pool, one worker per device
appium:app app.appPath on the target. MobileAppTest installs the build once per run with Device.InstallAppAsync(), see Point at your app
appium:bundleId, appium:appPackage app.bundleId on the target, the app App.OpenAsync() launches
appium:processArguments, appium:optionalIntentArguments app.launchArguments on the target, or OpenAppOptions.LaunchArguments for one launch, a list of strings
appium:permissions app.permissions on the target, { "camera": "grant" }, set before every fresh launch. Each DevicePermission name takes grant, deny, or reset
appium:noReset true is the default, so nothing clears the app’s data. For false, call App.ClearStateAsync() at the start of the test
appium:fullReset Device.InstallAppAsync(options: new InstallAppOptions { Reinstall = true })
appium:newCommandTimeout, WebDriverAgent timeouts Not needed. Actions use actionTimeout, assertions assertionTimeout, and the test its own timeout
appium:platformVersion, appium:language, appium:locale on a hosted device OsVersion, Language, and Locale on BrowserStackDevicesOptions; Android.OsVersion on LimrunSimulatorsOptions. E2E.TestMu.Mobile has none of them
bstack:options, lt:options A device provider: E2E.BrowserStack, see BrowserStack, or E2E.TestMu.Mobile
Several capability sets, maxInstances One target, switched with E2E_MOBILE_PLATFORM, and a MobileOptions.Devices list with one worker per device
e2e.config.json
{
"targets": [
{
"name": "ios",
"platform": "ios",
"app": {
"bundleId": "com.example.app",
"appPath": "ios/build/MyApp.app",
"launchArguments": ["-e2e", "YES"],
"permissions": { "notifications": "grant" }
}
}
]
}

Upstream’s config holds an ios and an android target at once. The port’s e2e.config.json holds one device target, and the two variables switch it, see MobileAppTest. Run the Android build with E2E_MOBILE_PLATFORM=android E2E_MOBILE_APP_PATH=android/app/build/outputs/apk/release/app-release.apk dotnet test, and give an Android run its own launchArguments, such as ["--ez", "e2e", "true"]. The target holds one bundleId: when the Android package differs from the iOS bundle id, set app.bundleId to the package for that run, or override MobileAppTest.AppId.

Start with a test whose XPath selectors or explicit waits often break.

Appium .NET client
[Test]
public void Signs_in()
{
driver.FindElement(AppiumBy.AccessibilityId("email")).SendKeys("ada@example.test");
driver.FindElement(AppiumBy.AccessibilityId("password")).SendKeys("hunter2");
driver.FindElement(By.XPath("//XCUIElementTypeButton[@name='Sign in']")).Click();
var wait = new WebDriverWait(driver, TimeSpan.FromSeconds(10));
wait.Until(d => d.FindElement(AppiumBy.AccessibilityId("welcome")).Displayed);
Assert.That(driver.FindElement(AppiumBy.AccessibilityId("welcome")).Text, Is.EqualTo("Welcome, Ada"));
}
e2e (NUnit)
using E2E.Mobile.NUnit;
public sealed class LoginTests : MobileAppTest
{
[Test]
public async Task Signs_in()
{
// iOS accessibility ids. On Android, content descriptions are labels: use GetByLabel("email").
await Screen.GetByTestId("email").FillAsync("ada@example.test");
await Screen.GetByTestId("password").FillAsync("hunter2");
await Screen.GetByRole("button", "Sign in").TapAsync();
var welcome = Screen.GetByTestId("welcome");
await Expect.That(welcome).ToBeVisibleAsync(timeout: TimeSpan.FromSeconds(10));
await Expect.That(welcome).ToHaveTextAsync("Welcome, Ada");
}
}
  • MobileAppTest installs the build and launches the app fresh before each test, so the test needs no App.OpenAsync().
  • Actions wait for their element and assertions retry, so the explicit wait goes away.

For xUnit v3, use E2E.Mobile.XUnit.V3 and [Fact].

Where a run of scripted taps breaks often, one Agent.ActAsync goal can replace it. The replay cache records its actions once a later check passes, and the next run replays them without a model call. A password belongs in configured credentials, which the model never sees:

var ada = Credentials.User("ada");
await Agent.ActAsync("sign in as {username}", new ActOptions
{
Params = new Dictionary<string, object?> { ["username"] = ada.Username, ["password"] = ada.Password },
});
Appium e2e
$('~login') on iOS, AppiumBy.AccessibilityId("login"): an accessibility identifier or React Native testID Screen.GetByTestId("login")
$('~Log in') on Android, AppiumBy.AccessibilityId("Log in"): a content description or React Native accessibilityLabel Screen.GetByLabel("Log in")
$('id=com.example:id/email'), AppiumBy.Id, resourceId Screen.GetByTestId("email"); the com.example:id/ prefix is optional
-ios predicate string:label == "Sign in", android=new UiSelector().text("Sign in") Screen.GetByText("Sign in") or GetByLabel("Sign in")
-ios class chain, class names (XCUIElementTypeButton, android.widget.Button) Screen.GetByRole("button", "Sign in")
$$(selector)[2], FindElements(...)[2] .Nth(2); AllAsync() returns every match
A selector the queries can’t express Device.Locator("role=text label=\"Total\""), agent-device’s selector syntax
  • GetByText, GetByLabel, and GetByTestId match the whole string, case included. Pass a Regex, or exact: false for a case-insensitive substring of text or label.
  • Appium’s $() and FindElement return the first match. An e2e action needs exactly one and fails with LOCATOR_AMBIGUOUS on several. Narrow it with Filter(...), First(), or Nth(n).
  • Roles such as button, textbox, and switch are the same on iOS and Android, so one test runs on both. See Roles.

Calls on Device run only on a device. Calls on Screen, App, Agent, and Expect.That(locator) run on every target.

Appium e2e
.click(), .doubleClick() .TapAsync(), .DoubleTapAsync()
mobile: longClickGesture, mobile: touchAndHold on an element .LongPressAsync(new LongPressOptions { Duration = ... })
.setValue(t), .clearValue() .FillAsync(t), which replaces the content, and .ClearAsync()
.addValue(t) .PressSequentiallyAsync(t), which types key by key at the cursor
driver.keys('Enter'), pressKeyCode(66) .PressAsync("Enter") on the field
.getText(), .getValue(), .getAttribute('value') .TextContentAsync(), .InputValueAsync()
.isDisplayed(), .isEnabled(), .getAttribute('checked') .IsVisibleAsync(), .IsEnabledAsync(), .IsCheckedAsync()
.isExisting() await locator.CountAsync() > 0
.getLocation(), .getSize() .BoundingBoxAsync()
.waitForDisplayed({ timeout }) await Expect.That(locator).ToBeVisibleAsync(timeout: ...), or locator.WaitForAsync()
.waitForDisplayed({ reverse: true }) await Expect.That(locator).ToBeHiddenAsync()
mobile: swipeGesture, mobile: swipe, driver.swipe({ direction: 'up' }) locator.SwipeAsync(new SwipeOptions { Direction = ScrollDirection.Down }) or Screen.SwipeAsync(new SwipeOptions { ... }). e2e names the content’s direction, not the finger’s
mobile: scrollGesture, mobile: scroll to an element, .scrollIntoView() Screen.ScrollUntilVisibleAsync(locator), or list.ScrollUntilVisibleAsync(locator) on the scroll view
.dragAndDrop(target), a drag that ends on an element locator.DragToAsync(target)
A performActions swipe between two points Screen.SwipeAsync(new SwipePathOptions { From = new Point(x1, y1), To = new Point(x2, y2) })
A tap at coordinates Screen.TapAtAsync(new Point(x, y)); inside an element, .TapAsync(new TapOptions { Position = new Point(x, y) })
Appium e2e
The launch at session start MobileAppTest launches the target’s app fresh before each test; App.OpenAsync() launches it again
driver.activateApp(id) Device.OpenAppAsync(id); new OpenAppOptions { Relaunch = true } restarts it
driver.terminateApp(id) on the app under test Device.CloseAppAsync(). It ends the session, so open an app next
terminateApp, then activateApp App.RestartAsync()
mobile: clearApp, driver.installApp(path) App.ClearStateAsync(), Device.InstallAppAsync(path)
driver.background(seconds) Device.HomeAsync(), await Task.Delay(TimeSpan.FromSeconds(seconds)) for a positive seconds, then Device.OpenAppAsync(id)
driver.url('myapp://x'), mobile: deepLink Device.OpenLinkAsync("myapp://x")
driver.back(), driver.hideKeyboard(), pressKeyCode for Home App.BackAsync(), Device.DismissKeyboardAsync(), Device.HomeAsync()
driver.getPageSource() Screen.TreeAsync(), or Screen.DebugAsync() to print it
driver.takeScreenshot() App.ScreenshotAsync("label"), secure fields masked
startRecordingScreen(), stopRecordingScreen() App.StartRecordingAsync(), App.StopRecordingAsync(), or E2E_VIDEO=on dotnet test
mobile: setPermission, mobile: changePermissions Device.SetPermissionAsync(DevicePermission.Camera, PermissionState.Grant), one per call, on the target’s app, which need not be running; call it before the app launches
driver.acceptAlert(), driver.dismissAlert() Device.AlertAsync(AlertAction.Accept), Device.AlertAsync(AlertAction.Dismiss)
driver.setGeoLocation({ latitude, longitude }) Device.SetLocationAsync(new Coordinates(latitude, longitude))
driver.setOrientation('LANDSCAPE'), mobile: setAppearance Device.SetOrientationAsync(DeviceOrientation.LandscapeLeft), Device.SetAppearanceAsync(Appearance.Dark)
driver.setClipboard(t), driver.getClipboard() Device.SetClipboardAsync(t), Device.ClipboardAsync(), plain text where Appium uses base64
driver.toggleWiFi(false), mobile: setConnectivity with wifi: false Device.SetNetworkAsync(NetworkState.Offline), Wi-Fi only; Android only
driver.toggleAirplaneMode(), mobile: setConnectivity with airplaneMode: true Device.SetAirplaneModeAsync(true), Wi-Fi and cellular; Android 11 or later
mobile: enrollBiometric, mobile: sendBiometricMatch, driver.fingerPrint(1) Device.EnrollBiometricsAsync(BiometricSensor.FaceId, true), Device.SetBiometricsAsync(BiometricSensor.FaceId, BiometricResult.Match), or BiometricSensor.Fingerprint
mobile: clearKeychains Device.ClearKeychainAsync(); iOS simulator only
driver.isIOS, driver.isAndroid the Platform property of MobileAppTest, MobilePlatform.Ios or Android, with Assume.That (NUnit)
Appium e2e
toBeDisplayed(), not.toBeDisplayed() ToBeVisibleAsync(), ToBeHiddenAsync()
toExist(), toBeElementsArrayOfSize(n) ToBeAttachedAsync(), ToHaveCountAsync(n)
toHaveText(t), toHaveText(t, { containing: true }) ToHaveTextAsync(t), ToContainTextAsync(t)
toHaveValue, toBeEnabled, toBeDisabled, toBeSelected, toBeChecked The same, with the Async suffix
@wdio/visual-service screen comparison Expect.That(Screen).ToHaveScreenshotAsync("name.png"). The port documents it for the web engine only and has no device run of it, so keep the comparison until you have checked it on your device
remote(), deleteSession(), new AndroidDriver(...), Quit() Nothing to call. MobileAppTest opens and closes one device session per worker
specs in wdio.conf.ts the test project’s own tests; dotnet test collects the classes in the project
specFileRetries, Mocha retries NUnit [Retry(n)], where n counts total attempts (two Mocha retries are [Retry(3)]) and a retry reruns the method, not the file; xUnit v3 has no retry attribute
Mocha --grep, tags in titles dotnet test --filter "FullyQualifiedName~Name", or [Category("smoke")] (NUnit) and --filter "TestCategory=smoke"
before, beforeEach hooks [OneTimeSetUp], [SetUp] (NUnit); the constructor and InitializeAsync (xUnit v3)
JUnit, Allure, spec reporters the dotnet test loggers, such as --logger trx (--report-trx on Microsoft.Testing.Platform; see Testing frameworks), or a JUnit logger package

Appium grants permissions through capabilities or mobile: commands, and opens links through driver.Url or mobile: deepLink:

Appium .NET client
driver.ExecuteScript("mobile: setPermission", new Dictionary<string, object>
{
["bundleId"] = "com.example.app",
["access"] = new Dictionary<string, string> { ["location"] = "yes" },
});
driver.ActivateApp("com.example.app");
driver.ExecuteScript("mobile: deepLink", new Dictionary<string, object> { ["url"] = "myapp://orders/42", ["bundleId"] = "com.example.app" });
Assert.That(driver.FindElement(AppiumBy.AccessibilityId("order-title")).Text, Is.EqualTo("Order #42"));
e2e (NUnit)
using E2E.Mobile.NUnit;
public sealed class OrderLinkTests : MobileAppTest
{
[Test]
public async Task Opens_an_order_from_a_link()
{
await Device.SetPermissionAsync(DevicePermission.Location, PermissionState.Grant);
await App.OpenAsync();
await Device.OpenLinkAsync("myapp://orders/42");
await Expect.That(Screen.GetByText("Order #42")).ToBeVisibleAsync();
}
}

Set a permission before App.OpenAsync(), since a change stops a running app on iOS. Permissions every test needs go in app.permissions, and so do those the app reads at startup, since MobileAppTest has launched the app before the test body runs.

With no server to start, an e2e job lets MobileAppTest install the build from app.appPath, and dotnet test runs the suite on the booted simulator or emulator:

Terminal window
xcrun simctl boot "iPhone 17"
cd MyApp.E2ETests
dotnet test

Each platform needs its own job: iOS on macOS, Android on Linux with KVM. Boot exactly one device, or name it with E2E_MOBILE_DEVICE, see Mobile.

Planned rows are on the roadmap, and Not yet rows have no date. Not planned rows are left out on purpose. A call through Device.UnstableRaw is not a step, so it skips the report and secret redaction, and it takes only the calls the engine makes, see what the raw client takes.

Appium Use today
appium:autoGrantPermissions, Android permissions off the list, iOS location always List each permission in app.permissions, or run adb shell pm grant before the run. For iOS location always, tap the prompt’s button
Device settings and alerts on a BrowserStack or TestMu device Tap the prompt as UI. Run those tests on a local device
bstack:options.local, lt:options.tunnel Point the app at a backend the hosted device can reach
appium:appActivity, appWaitActivity, startActivity() Device.OpenLinkAsync(url), or DeviceMethods.AppsOpen through Device.UnstableRaw
appium:processArguments.env Pass a launch argument and read it in the app
appium:language, appium:locale on a local device On iOS, LaunchArguments = ["-AppleLanguages", "(fr)", "-AppleLocale", "fr_FR"], see Run the app in another language. On Android, set the device language before the run
appium:disableWindowAnimation, reduceMotion On Android, DeviceMethods.SettingsUpdate with setting animations through Device.UnstableRaw, see what the raw client takes
Appium Use today
.getAttribute() for a label, id, or class, .isSelected(), .getTagName() ToHaveAccessibleNameAsync for a label, ToBeSelectedAsync for the selected state. No read for an id, class, or tag name
pressKeyCode(code), driver.keys('Backspace'), isKeyboardShown() .PressAsync() takes Enter, Space, or one character. Use .ClearAsync() and .FillAsync()
driver.getWindowRect(), getWindowSize(), mobile: deviceInfo Swipe by direction, or read .BoundingBoxAsync() of a full-screen element
UiScrollable scrollToEnd(), scrollToBeginning() Loop locator.SwipeAsync(new SwipeOptions { Direction = ScrollDirection.Down }) until AllTextContentsAsync() stops changing; Up for the beginning
mobile: selectPickerWheelValue, date and time pickers, slider values Swipe the wheel and read .InputValueAsync(), or use an Agent.ActAsync goal
mobile: dragGesture to coordinates, mobile: dragFromToForDuration DeviceMethods.InteractionsDrag through Device.UnstableRaw, see what the raw client takes
Appium Use today
driver.getLogs('logcat'), 'syslog', 'crashlog' Run adb logcat or xcrun simctl spawn <udid> log stream from a [SetUp] with System.Diagnostics.Process
driver.removeApp(id), isAppInstalled(id) DeviceMethods.AppsUninstall or AppsList through Device.UnstableRaw, see what the raw client takes. Device.InstallAppAsync(options: new InstallAppOptions { Reinstall = true }) removes the app first and installs it with no data (not on TestMu)
queryAppState(id) On Android, Device.ForegroundAppAsync() names the app on screen
driver.lock(), unlock(), power and volume buttons DeviceMethods.CommandHardwareButton through Device.UnstableRaw with button set to "power", "volume-up", or "volume-down"; on iOS only the volume keys, on a physical device, not a simulator. Not on TestMu
driver.openNotifications(), mobile: pushNotification Screen.SwipeAsync(new SwipePathOptions { From = ..., To = ... }) from the top edge; xcrun simctl push from .NET
driver.pushFile(), pullFile(), pullFolder() adb push, adb pull, or xcrun simctl addmedia from .NET; local devices only
driver.getAlertText() Screen.GetByRole("alert").TextContentAsync() on iOS, GetByText on Android
wdio.conf.ts hooks such as onPrepare and afterTest [OneTimeSetUp], [TearDown] (NUnit); the constructor and DisposeAsync (xUnit v3)
Appium Use today
appium:autoAcceptAlerts, appium:autoDismissAlerts Set app.permissions, or call Device.AlertAsync(AlertAction.Accept)
Webview contexts: getContexts(), switchContext(), CSS selectors, execute(js) Query the webview’s accessibility nodes with GetByText and GetByRole
Mobile web: browserName: 'Safari' or 'Chrome' A WebEngine target with a phone WebEngineOptions.Viewport, layout only
appium:unlockType, unlockKey Keep the device unlocked
driver.getPageSource() as XML No XML export. Screen.TreeAsync() returns the tree as text, and DeviceMethods.CaptureSnapshot through Device.UnstableRaw returns its nodes. Keep XML consumers in Appium
mobile: pinchOpenGesture, mobile: pinch, performActions() with several fingers or waypoints Single gestures. The raw client takes no pinch or gesture call. Keep the test in Appium
mobile: shell, getPerformanceData() Run adb or simctl from .NET with Device.DeviceId; local devices only
mobile: setSimulatedLocation, mobile: setAppearance, mobile: setPasteboard on an iPhone Run those tests on a simulator
Other bstack:options keys, such as gpsLocation and uploadMedia -
appium:platformVersion on a local device, a phone’s appium:udid Name a simulator or emulator that runs the version. Put the phone’s name in MobileOptions.Device
appium:avd, avdArgs, isHeadless Boot the emulator before the run and name its serial
An HTML report Use a dotnet test logger such as --logger html. The port has no htmlReporter()
Tests in Java, Python, Ruby, or JavaScript e2e tests are C#. Rewrite them in a test project beside the app
Appium Use instead
XPath Chain queries (Screen.GetByTestId("row").GetByText("Delete")) or use Filter(has: ..., hasText: ...). XPath ties a test to one platform’s tree
-image selectors, findImage Screen.TapAtAsync(new Point(x, y)), or an Agent.ActAsync goal
$(selector) acting on the first of several matches .First(), see Rewrite selectors
WebDriverAgent capabilities such as usePrebuiltWDA Nothing to set. agent-device builds and signs its own runner
Compound -ios predicate string logic, UiSelector flags and fromParent() A GetBy* query with Filter(has: ...) or a Regex
Gherkin feature files One test per scenario. A step can be an Agent.ActAsync goal
Saved sessions on a device Sign in per test or in [SetUp], or seed the app. A device has no session to save
A device grid or hub, other device clouds A hosted provider, or an IDeviceProvider you write, see Hosted devices
sauce:options Write an IDeviceProvider
Appium Inspector Screen.DebugAsync(), or e2e mcp for a coding agent’s live session, see Coding agents
driver.updateSettings(), appium:settings[...] Snapshot, Settle, and Transition on MobileOptions
.getAttribute('clickable'), .isClickable() Act on the element. The action waits until it is actionable
A remote Appium server (hostname, port) Run e2e on the machine that has the devices
Allure Feed it the dotnet test logger’s output
  • Mobile: configure your app, devices, and hosted devices.
  • Core concepts: goals, assertions, and locators instead of scripted selectors.