skip to content

In Appium, which capability names may be sent without the appium: prefix?

level: juniorimportance: should knowfreq 64%

answer

  1. two lists, not one
  2. W3C standard versus Appium core
  3. extension capabilities need a colon
  4. only platformName and webSocketUrl overlap

basics

~10 s

Only the twelve W3C standard capabilities may travel unprefixed in Appium, among them platformName, browserName, timeouts and webSocketUrl. Every other key, including automationName, app and udid, must be written as an appium: capability.

solid answer

~40 s

The Appium server accepts a bare capability name only when it is one of the W3C standard capabilities. That set is frozen in the base driver as `STANDARD_CAPS` and holds twelve names: `browserName`, `browserVersion`, `platformName`, `acceptInsecureCerts`, `pageLoadStrategy`, `proxy`, `setWindowRect`, `timeouts`, `strictFileInteractability`, `unhandledPromptBehavior`, `userAgent` and `webSocketUrl`. Anything outside that list is an extension capability, and the W3C protocol requires an extension capability's name to carry a namespace containing a colon. Appium's namespace is `appium:`, so `platformName` travels bare while `appium:automationName`, `appium:app`, `appium:udid` and `appium:newCommandTimeout` are all prefixed. The trap is that Appium's own base constraint list is longer and overlaps the standard list in only two names, `platformName` and `webSocketUrl` — being built into Appium does not make a capability standard.

code

json · 10 lines
json
{
  "capabilities": {
    "alwaysMatch": {
      "platformName": "Android",
      "appium:automationName": "UiAutomator2",
      "appium:appPackage": "org.example.gardenplots",
      "appium:newCommandTimeout": 120
    }
  }
}

go deeper

for a junior

Be ready to say that only the W3C standard capabilities go bare and everything Appium-specific carries appium:. Naming platformName as the bare one and automationName as a prefixed one is enough at this stage.

for a middle

Explain the mechanism: extension capabilities must be namespaced under the W3C rules, and Appium enforces that against a frozen twelve-name set rather than against its own constraint list.

for a senior

Show that you know the two lists overlap in only two names, and that a capability being core to Appium says nothing about whether it may go bare. That is the distinction that keeps a shared capability set from breaking.

for a principal

Own the convention across a suite: decide whether capability sets are hand-written JSON or built by typed helpers, since the choice determines whether prefix mistakes are caught at build time or at session start.

## Two kinds of capability, one wire format An Appium session is created by posting a capabilities object to the server, and every key in that object is one of exactly two kinds. **Standard capabilities** are the names the W3C WebDriver specification defines itself. They are written bare, and any conforming remote end is expected to understand them. **Extension capabilities** are everything a vendor adds on top of the standard, and the specification requires their names to carry a namespace containing a colon, so the owner of the name is visible on the wire. Appium's namespace is `appium:`. That is the whole rule: a name on the standard list may go bare, and every other name must be namespaced. Appium does not treat this as a matter of style. The server keeps the standard list as a frozen set, `STANDARD_CAPS`, in the base driver's `capabilities.ts`, and checks every incoming key against it. A key that is neither on that list nor namespaced is not a legal capability at all, and the session request is refused before any device is touched. ## The twelve names that may go bare The standard set is short and closed. In full: - `browserName` and `browserVersion` - `platformName` — the one standard name that starts essentially every Appium session - `acceptInsecureCerts` - `pageLoadStrategy` - `proxy` - `setWindowRect` - `timeouts` - `strictFileInteractability` - `unhandledPromptBehavior` - `userAgent` - `webSocketUrl` Twelve names, and nothing else. Notice what is missing: the automation engine, the application artifact, the device identity, the reset behaviour, the idle timeout. Everything a mobile suite actually configures sits outside this list, which is why a real Appium capability set is mostly prefixed keys with one or two bare names at the top. ## The list that looks standard and is not The confusing part is that Appium publishes a second list, and it is easy to mistake it for the first. The base driver declares `BASE_DESIRED_CAP_CONSTRAINTS`, the capabilities any Appium driver accepts: `platformName`, `app`, `platformVersion`, `webSocketUrl`, `newCommandTimeout`, `automationName`, `autoLaunch`, `udid`, `orientation`, `autoWebview`, `noReset`, `fullReset`, `language`, `locale`, `eventTimings` and `printPageSourceOnFindFailure`. Those are built into Appium's core rather than into one driver — and being built in has nothing to do with being standard. | List | What it describes | Prefix needed | |---|---|---| | `STANDARD_CAPS`, twelve W3C names | what the protocol itself defines | no | | `BASE_DESIRED_CAP_CONSTRAINTS`, sixteen Appium names | what a base Appium driver accepts | yes, except `platformName` and `webSocketUrl` | The two lists intersect in exactly two names. So `appium:app`, `appium:udid`, `appium:noReset`, `appium:fullReset`, `appium:newCommandTimeout`, `appium:language` and `appium:locale` are all prefixed despite being core Appium capabilities. And `appium:deviceName`, which older examples often show bare, is not even core: it is declared by the Android driver and by the XCUITest driver, which makes it doubly an extension capability. ## A capability set for a community-garden plot app Take a suite that drives a community-garden plot app — plot maps, watering rotas, harvest logs. An **Android** run sends `platformName` bare and prefixes the rest: `appium:automationName` naming UiAutomator2, Android's `appium:appPackage` for the plot app, and `appium:newCommandTimeout` so an idle session is not reaped between scenarios. An **Apple** run sends `platformName` bare in the same way, then `appium:automationName` naming XCUITest and Apple's `appium:bundleId`. The bare-versus-prefixed split is identical on the two platforms; only the prefixed key names differ. ## Where this bites in practice - Copying a capability map out of an Appium 1 era article, where nothing carried a namespace. - Assuming that a capability documented on Appium's own site is therefore a standard capability. - Hand-building request JSON instead of going through a client library that adds the prefix for you. - Reading the base driver's constraint list as though it were the list of names allowed to go bare. - Adding a driver-specific tuning key — an Android-only or an Apple-only one — with no namespace on it. ## How to keep it straight 1. Ask whether the name is one of the twelve W3C names. If it is not, it is an extension capability. 2. Give every extension capability the `appium:` namespace, or move the whole block under `appium:options`. 3. Remember that `platformName` and `webSocketUrl` are the only names on both lists, so they are the only Appium-relevant names that are also standard.

  • Why is platformName the usual example of a capability that goes bare?
    Because it is one of the twelve W3C standard names and also one of Appium's own base constraints — it appears on both lists. `webSocketUrl` is the only other name in that position. Every other capability a mobile suite sets, including `appium:automationName` and `appium:app`, exists only in Appium's world and therefore needs the namespace.
  • Does the appium: namespace change what the capability means to the driver?
    No. The namespace is addressing, not semantics: it tells a W3C remote end which vendor owns the name so unrelated vendors cannot collide on `app` or `udid`. Once the server has validated and routed the capabilities, the driver reads the same value it would have read from a bare key.

saying these in an interview costs you the question

  • Thinks any capability Appium documents can be sent without the prefix
  • Calls the appium: prefix optional formatting the server strips
  • Assumes deviceName is a W3C standard capability
  • Believes noReset and fullReset go bare because they are core
  • Reads the base driver constraint list as the unprefixed list