Skip to content

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.

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

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

MultiSessionData<C>[]

A list of session data objects

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

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

Use explicit session management commands instead

Response

null