Driver: base-driver¶

`createSession`¶

POST /session

Historically the first two arguments were reserved for JSONWP capabilities. Appium 2 has dropped the support of these, so now we only accept capability objects in W3C format and thus allow any of the three arguments to represent the latter.

See

https://w3c.github.io/webdriver/#new-session

Parameters¶

Name	Type	Description
`desiredCapabilities?`	`W3CDriverCaps`<`C`>	the new session capabilities
`requiredCapabilities?`	`W3CDriverCaps`<`C`>	another place the new session capabilities could be sent (typically left undefined)
`capabilities?`	`W3CDriverCaps`<`C`>	another place the new session capabilities could be sent (typically left undefined)

Response¶

CreateResult

The capabilities object representing the created session

`deleteSession`¶

DELETE /session/:sessionId

Returns capabilities for the session and event history (if applicable)

Response¶

SingularSessionData<C, SessionData>

A session data object

`getSession`¶

GET /session/:sessionId

Returns capabilities for the session and event history (if applicable)

Response¶

SingularSessionData<C, SessionData>

A session data object

`findElement`¶

POST /session/:sessionId/element

Find a UI element given a locator strategy and a selector, erroring if it can't be found

See

https://w3c.github.io/webdriver/#find-element

Parameters¶

Name	Type	Description
`using`	`string`	the locator strategy
`value`	`string`	the selector to combine with the strategy to find the specific element

Response¶

Element<string>

The element object encoding the element id which can be used in element-related commands

`findElementFromElement`¶

POST /session/:sessionId/element/:elementId/element

Find a UI element given a locator strategy and a selector, erroring if it can't be found. Only look for elements among the set of descendants of a given element

See

https://w3c.github.io/webdriver/#find-element-from-element

Parameters¶

Name	Type	Description
`using`	`string`	the locator strategy
`value`	`string`	the selector to combine with the strategy to find the specific element

Response¶

Element<string>

The element object encoding the element id which can be used in element-related commands

`findElementFromShadowRoot`¶

POST /session/:sessionId/shadow/:shadowId/element

Find an element from a shadow root

See

https://w3c.github.io/webdriver/#find-element-from-shadow-root

Parameters¶

Name	Type	Description
`using`	`string`	the locator strategy
`value`	`string`	the selector to combine with the strategy to find the specific elements

Response¶

Element<string>

The element inside the shadow root matching the selector

`findElements`¶

POST /session/:sessionId/elements

Find a a list of all UI elements matching a given a locator strategy and a selector

See

https://w3c.github.io/webdriver/#find-elements

Parameters¶

Name	Type	Description
`using`	`string`	the locator strategy
`value`	`string`	the selector to combine with the strategy to find the specific elements

Response¶

Element<string>[]

A possibly-empty list of element objects

`findElementsFromElement`¶

POST /session/:sessionId/element/:elementId/elements

Find a a list of all UI elements matching a given a locator strategy and a selector. Only look for elements among the set of descendants of a given element

See

https://w3c.github.io/webdriver/#find-elements-from-element

Parameters¶

Name	Type	Description
`using`	`string`	the locator strategy
`value`	`string`	the selector to combine with the strategy to find the specific elements

Response¶

Element<string>[]

A possibly-empty list of element objects

`findElementsFromShadowRoot`¶

POST /session/:sessionId/shadow/:shadowId/elements

Find elements from a shadow root

See

https://w3c.github.io/webdriver/#find-element-from-shadow-root

Parameters¶

Name	Type	Description
`using`	`string`	the locator strategy
`value`	`string`	the selector to combine with the strategy to find the specific elements

Response¶

Element<string>[]

A possibly empty list of elements inside the shadow root matching the selector

`getLog`¶

POST /session/:sessionId/log

Get the log for a given log type.

Deprecated

Please use the /session/:sessionId/se/log endpoint instead

Parameters¶

Name	Type	Description
`type`	`string`	Name/key of log type as defined in ILogCommands.supportedLogTypes.

Response¶

any

`getLog`¶

POST /session/:sessionId/se/log

Get the log for a given log type.

Parameters¶

Name	Type	Description
`type`	`string`	Name/key of log type as defined in ILogCommands.supportedLogTypes.

Response¶

any

`getLogEvents`¶

POST /session/:sessionId/appium/events

Get a list of events that have occurred in the current session

Parameters¶

Name	Type	Description
`type?`	`string` \| `string`[]	filter the returned events by including one or more types

Response¶

EventHistory | Record<string, number>

The event history for the session

`getLogTypes`¶

GET /session/:sessionId/log/types

Get available log types as a list of strings

Deprecated

Please use the /session/:sessionId/se/log/types endpoint instead

Response¶

string[]

`getLogTypes`¶

GET /session/:sessionId/se/log/types

Get available log types as a list of strings

Response¶

string[]

`getPageSource`¶

GET /session/:sessionId/source

Get the current page/app source as HTML/XML

See

https://w3c.github.io/webdriver/#get-page-source

Response¶

string

The UI hierarchy in a platform-appropriate format (e.g., HTML for a web page)

`getSessions`¶

GET /sessions

Get data for all sessions running on an Appium server

Response¶

A list of session data objects. Each session data object will be returned with id and the session's capabilities as capabilities keys like an example below:

[
  {
    "id":"ba30c6da-c266-4734-8ddb-c16f5bb53e16",
    "capabilities":{ "platformName":"ios","browserName":"safari","automationName":"xcuitest","platformVersion":"17.2","deviceName":"iPhone 15" }
  },
  {
    "id":"1441110c-1ece-4e45-abbf-ebf404f45f0a",
    "capabilities":{ "platformName":"ios","browserName":"safari","automationName":"xcuitest","platformVersion":"17.0","deviceName":"iPhone 14" }
  },
  ...
]

`getSettings`¶

GET /session/:sessionId/appium/settings

Update the session's settings dictionary with a new settings object

Response¶

null

`updateSettings`¶

POST /session/:sessionId/appium/settings

Update the session's settings dictionary with a new settings object

Parameters¶

Name	Type	Description
`settings`	`Settings`	A key-value map of setting names to values. Settings not named in the map will not have their value adjusted.

Response¶

null

`getStatus`¶

GET /status

Summary

Retrieve the server's current status.

Description

Returns information about whether a remote end is in a state in which it can create new sessions and can additionally include arbitrary meta information that is specific to the implementation.

The readiness state is represented by the ready property of the body, which is false if an attempt to create a session at the current time would fail. However, the value true does not guarantee that a New Session command will succeed.

Implementations may optionally include additional meta information as part of the body, but the top-level properties ready and message are reserved and must not be overwritten.

Examples¶

JavaScript¶

// webdriver.io example
await driver.status();

Python¶

driver.get_status()

Java¶

driver.getStatus();

Ruby¶

# ruby_lib example
remote_status

# ruby_lib_core example
@driver.remote_status

Response¶

Object

`getTimeouts`¶

GET /session/:sessionId/timeouts

Set the various timeouts associated with a session

See

https://w3c.github.io/webdriver/#set-timeouts

Response¶

null

`timeouts`¶

POST /session/:sessionId/timeouts

Set the various timeouts associated with a session

See

https://w3c.github.io/webdriver/#set-timeouts

Parameters¶

Name	Type	Description
`type?`	`string`	used only for the old (JSONWP) command, the type of the timeout
`ms?`	`string` \| `number`	used only for the old (JSONWP) command, the ms for the timeout
`script?`	`number`	the number in ms for the script timeout, used for the W3C command
`pageLoad?`	`number`	the number in ms for the pageLoad timeout, used for the W3C command
`implicit?`	`string` \| `number`	the number in ms for the implicit wait timeout, used for the W3C command

Response¶

null

`implicitWait`¶

POST /session/:sessionId/timeouts/implicit_wait

Set the implicit wait timeout

Deprecated

Please use the /session/:sessionId/timeouts endpoint instead

Use timeouts instead

Parameters¶

Name	Type	Description
`ms`	`string` \| `number`	the timeout in ms

Response¶

null

`logCustomEvent`¶

POST /session/:sessionId/appium/log_event

Add a custom-named event to the Appium event log

Parameters¶

Name	Type	Description
`vendor`	`string`	the name of the vendor or tool the event belongs to, to namespace the event
`event`	`string`	the name of the event itself

Response¶

null

`reset`¶

POST /session/:sessionId/appium/app/reset

Reset the current session (run the delete session and create session subroutines)

Deprecated

Please use each driver's launch, activate, terminate or cleanup method.

Use explicit session management commands instead

Response¶

null

Driver: base-driver¶

createSession¶

Parameters¶

Response¶

deleteSession¶

Response¶

getSession¶

Response¶

findElement¶

Parameters¶

Response¶

findElementFromElement¶

Parameters¶

Response¶

findElementFromShadowRoot¶

Parameters¶

Response¶

findElements¶

Parameters¶

Response¶

findElementsFromElement¶

Parameters¶

Response¶

findElementsFromShadowRoot¶

Parameters¶

Response¶

getLog¶

Parameters¶

Response¶

getLog¶

Parameters¶

Response¶

getLogEvents¶

Parameters¶

Response¶

getLogTypes¶

Response¶

getLogTypes¶

Response¶

getPageSource¶

Response¶

getSessions¶

Response¶

getSettings¶

Response¶

updateSettings¶

Parameters¶

Response¶

getStatus¶

Examples¶

JavaScript¶

Python¶

Java¶

Ruby¶

Response¶

getTimeouts¶

Response¶

timeouts¶

Parameters¶

Response¶

implicitWait¶

Parameters¶

Response¶

logCustomEvent¶

Parameters¶

Response¶

reset¶

Response¶

`createSession`¶

`deleteSession`¶

`getSession`¶

`findElement`¶

`findElementFromElement`¶

`findElementFromShadowRoot`¶

`findElements`¶

`findElementsFromElement`¶

`findElementsFromShadowRoot`¶

`getLog`¶

`getLog`¶

`getLogEvents`¶

`getLogTypes`¶

`getLogTypes`¶

`getPageSource`¶

`getSessions`¶

`getSettings`¶

`updateSettings`¶

`getStatus`¶

`getTimeouts`¶

`timeouts`¶

`implicitWait`¶

`logCustomEvent`¶

`reset`¶