Copyright © 2019 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and permissive document license rules apply.
WebDriver is a remote control interface that enables introspection and control of user agents. It provides a platform- and language-neutral wire protocol as a way for out-of-process programs to remotely instruct the behavior of web browsers.
Provided is a set of interfaces to discover and manipulate DOM elements in web documents and to control the behavior of a user agent. It is primarily intended to allow web authors to write tests that automate a user agent from a separate controlling process, but may also be used in such a way as to allow in-browser scripts to control a — possibly separate — browser.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
Use GitHub w3c/webdriver for comments/issues.
This document was published by the Browser Testing and Tools Working Group as a Living Document.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-browser-tools-testing@w3.org ( archives ).
Publication as a Living Document does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy . The group does not expect this document to become a W3C Recommendation. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
This document is governed by the 1 March 2019 W3C Process Document .
This section is non-normative.
The
WebDriver
standard
attempts
to
follow
a
number
of
design
goals:
This
specification
is
derived
from
the
popular
Selenium
WebDriver
browser
automation
framework.
Selenium
is
a
long-lived
project,
and
due
to
its
age
and
breadth
of
use
it
has
a
wide
range
of
expected
functionality.
This
specification
uses
these
expectations
to
inform
its
design.
Where
improvements
or
clarifications
have
been
made,
they
have
been
made
with
care
to
allow
existing
users
of
Selenium
WebDriver
to
avoid
unexpected
breakages.
The
largest
intended
group
of
users
of
this
specification
are
software
developers
and
testers
writing
automated
tests
and
other
tooling,
such
as
monitoring
or
load
testing,
that
relies
on
automating
a
browser.
As
such,
care
has
been
taken
to
provide
commands
that
simplify
common
tasks
such
as
typing
into
and
clicking
elements.
WebDriver
provides
a
mechanism
for
others
to
define
extensions
to
the
protocol
for
the
purposes
of
automating
functionality
that
cannot
be
implemented
entirely
in
ECMAScript
.
This
allows
other
web
standards
to
support
the
automation
of
new
platform
features.
It
also
allows
vendors
to
expose
functionality
that
is
specific
to
their
browser.
1.1
Compatibility
1.2
Simplicity
1.3
Extensions
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. Algorithms in this document are typically written with readability, rather than performance, in mind.
In equations, all numbers are integers, addition is represented by “+”, subtraction by “−”, division by “÷”, and bitwise OR by “|”. The characters “(” and “)” are used to provide logical grouping in these contexts.
The mathematical function min ( value , value [, value ]) returns the smallest item of two or more values. Conversely, the function max ( value , value [, value ]) returns the largest item of two or more values.
The mathematical function floor ( value ) produces the largest integer, closest to positive infinity, that is not larger than value .
A Universally Unique IDentifier (UUID) is a 128 bits long URN that requires no central registration process. Generating a UUID means Creating a UUID From Truly Random or Pseudo-Random Numbers , and converting it to the string representation. [ RFC4122 ]
The Unix Epoch is a value that approximates the number of seconds that have elapsed since the Epoch, as described by The Open Group Base Specifications Issue 7 section 4.15 (IEEE Std 1003.1).
An integer is a Number that is unchanged under the ToInteger operation.
The initial value of an ECMAScript property is the value defined by the platform for that property, i.e. the value it would have in the absence of any shadowing by content script.
The browser chrome is a non-normative term to refer to the representation through which the user interacts with the user agent itself, as distinct from the accessed web content. Examples of browser chrome elements include, but are not limited to, toolbars (such as the bookmark toolbar), menus (such as the file or context menu), buttons (such as the back and forward buttons), door hangers (such as security and certificate indicators), and decorations (such as operating system widget borders).
The webdriver-active flag is set to true when the user agent is under remote control. It is initially false.
Navigator
includes
NavigatorAutomationInformation
;
Note
that
the
NavigatorAutomationInformation
interface
should
not
be
exposed
on
WorkerNavigator
.
webdriver
Returns true if webdriver-active flag is set, false otherwise.
The WebDriver protocol consists of communication between:
The local end represents the client side of the protocol, which is usually in the form of language-specific libraries providing an API on top of the WebDriver protocol . This specification does not place any restrictions on the details of those libraries above the level of the wire protocol.
For remote ends the standard defines two broad conformance classes, known as node types :
All remote end node types must be black-box indistinguishable from a remote end , from the point of view of local end , and so are bound by the requirements on a remote end in terms of the wire protocol.
The readiness state of a remote end indicates whether it is free to accept new connections. It must be false if the maximum active sessions is equal to the length of the list of active sessions , or if the node is an intermediary node and is known to be in a state in which attempting to create new sessions would fail. In all other cases it must be true.
If the intermediary node is a multiplexer that manages multiple endpoint nodes , this might indicate its ability to purvey more sessions , for example if it has hit its maximum capacity.
WebDriver remote ends must provide an HTTP compliant wire protocol where the endpoints map to different commands .
As
this
standard
only
defines
the
remote
end
protocol,
it
puts
no
demands
to
how
local
ends
should
be
implemented.
Local
ends
are
only
expected
to
be
compatible
to
the
extent
that
they
can
speak
the
remote
end
’s
protocol;
no
requirements
are
made
upon
their
exposed
user-facing
API.
Various
parts
of
this
specification
are
written
in
terms
of
step-by-step
algorithms.
The
details
of
these
algorithms
do
not
have
any
normative
significance;
implementations
are
free
to
adopt
any
implementation
strategy
that
produces
equivalent
output
to
the
specification.
In
particular,
algorithms
in
this
document
are
optimised
for
readability
rather
than
performance.
Where
algorithms
that
return
values
are
fallible,
they
are
written
in
terms
of
returning
either
success
or
error
.
A
success
value
has
an
associated
data
field
which
encapsulates
the
value
returned,
whereas
an
error
response
has
an
associated
error
code
.
When
calling
a
fallible
algorithm,
the
construct
“Let
result
be
the
result
of
trying
to
call
algorithm
”
is
equivalent
to
Let
temp
be
the
result
of
calling
algorithm
.
If
temp
is
an
error
return
temp
,
otherwise
let
result
be
temp
’s
data
field.
The
result
of
getting
a
property
with
argument
name
is
defined
as
being
the
same
as
the
result
of
calling
Object
.
[[GetOwnProperty]]
(
name
).
Setting
a
property
with
arguments
name
and
value
is
defined
as
being
the
same
as
calling
Object
.
[[Put]]
(
name
,
value
).
The
result
of
JSON
serialization
with
object
of
type
JSON
Object
is
defined
as
the
result
of
calling
The
result
of
JSON
deserialization
with
text
is
defined
as
the
result
of
calling
The
WebDriver
protocol
is
organised
into
commands
.
Each
HTTP
request
with
a
method
and
template
defined
in
this
specification
represents
a
single
command
,
and
therefore
each
command
produces
a
single
HTTP
response
.
In
response
to
a
command
,
a
remote
end
will
run
a
series
of
actions
known
as
remote
end
steps
.
These
provide
the
sequences
of
actions
that
a
remote
end
takes
when
it
receives
a
particular
command
.
The
remote
end
is
an
HTTP
server
reading
requests
from
the
client
and
writing
responses,
typically
over
a
TCP
socket.
For
the
purposes
of
this
specification
we
model
the
data
transmission
between
a
particular
local
end
and
remote
end
with
a
connection
to
which
the
remote
end
may
write
bytes
and
read
bytes
.
However
the
exact
details
of
how
this
connection
works
and
how
it
is
established
are
out
of
scope.
After
such
a
connection
has
been
established,
a
remote
end
must
run
the
following
steps:
Read
bytes
from
the
connection
until
a
complete
HTTP
request
can
be
constructed
from
the
data.
Let
request
be
a
request
constructed
from
the
received
data,
according
to
the
requirements
of
[
RFC7230
].
If
it
is
not
possible
to
construct
a
complete
HTTP
request
,
the
remote
end
must
either
close
the
connection
,
return
an
HTTP
response
with
status
code
500,
or
return
an
error
with
error
code
unknown
error
.
Let
request
match
be
the
result
of
the
algorithm
to
match
a
request
with
request
’s
method
and
URL
as
arguments.
If
request
match
is
of
type
error
,
send
an
error
with
request
match
’s
error
code
and
jump
to
step
1.
Otherwise,
let
command
and
command
parameters
be
request
match
’s
data.
Let
url
variables
be
a
url
variables
dictionary
mapping
the
command
parameters
to
their
corresponding
values.
If
session
id
is
among
the
variables
defined
by
command
parameters
:
This
condition
is
intended
to
exclude
the
New
Session
and
Status
commands
and
any
extension
commands
which
do
not
operate
on
a
particular
session
.
Let
session
id
be
the
corresponding
variable
from
command
parameters
.
Let
the
current
session
be
the
session
with
ID
session
id
in
the
list
of
active
sessions
,
or
If
the
current
session
is
If
the
current
session
is
not
Enqueue
request
in
the
current
session
’s
request
queue
.
Wait
until
the
first
element
in
the
current
session
’s
request
queue
is
request
:
Dequeue
request
from
the
current
session
’s
request
queue
.
If
the
list
of
active
sessions
no
longer
contains
the
current
session
,
set
the
current
session
to
If
request
’s
method
is
POST:
Let
parse
result
be
the
result
of
parsing
as
JSON
with
request
’s
body
as
the
argument.
If
this
process
throws
an
exception,
return
an
error
with
error
code
invalid
argument
and
jump
back
to
step
1
in
this
overall
algorithm.
If
parse
result
is
not
an
Object
,
send
an
error
with
error
code
invalid
argument
and
jump
back
to
step
1
in
this
overall
algorithm.
Otherwise,
let
parameters
be
parse
result
.
Otherwise,
let
parameters
be
Wait
for
navigation
to
complete
.
If
this
returns
an
error
return
its
value
and
jump
to
step
1
in
this
overall
algorithm,
otherwise
continue.
Let
response
result
be
the
return
value
obtained
by
running
the
remote
end
steps
for
command
with
an
argument
named
url
variables
whose
value
is
url
variables
and
an
additional
argument
named
parameters
whose
value
is
parameters
.
If
response
result
is
an
error
,
send
an
error
with
error
code
equal
to
response
result
’s
error
code
and
jump
back
to
step
1
in
this
overall
algorithm.
Otherwise,
if
response
result
is
a
success
,
let
response
data
be
response
result
’s
data.
Send
a
response
with
status
200
and
response
data
.
Jump
to
step
1.
When
required
to
send
an
error
,
with
error
code
and
an
optional
error
data
dictionary,
a
remote
end
must
run
the
following
steps:
Let
http
status
and
name
be
the
error
response
data
for
error
code
.
Let
message
be
an
implementation-defined
string
containing
a
human-readable
description
of
the
reason
for
the
error.
Let
stacktrace
be
an
implementation-defined
string
containing
a
stack
trace
report
of
the
active
stack
frames
at
the
time
when
the
error
occurred.
Let
body
be
a
new
JSON
Object
initialised
with
the
following
properties:
If
the
error
data
dictionary
contains
any
entries,
set
the
"
Send
a
response
with
status
and
body
as
arguments.
When
required
to
send
a
response
,
with
arguments
status
and
data
,
a
remote
end
must
run
the
following
steps:
Let
response
be
a
new
response
.
Set
response
’s
HTTP
status
to
status
,
and
status
message
to
the
string
corresponding
to
the
description
of
status
in
the
status
code
registry
.
Set
the
response
’s
header
with
name
and
value
with
the
following
values:
Let
response
’s
body
be
the
UTF-8
encoded
JSON
serialization
of
a
JSON
Object
with
a
key
"
Let
response
bytes
be
the
byte
sequence
resulting
from
serializing
response
according
to
the
rules
in
[
RFC7230
].
Write
response
bytes
to
the
connection
.
A
url
variable
dictionary
is
defined
as
the
mapping
of
a
command
’s
URI
template
variable
names
to
their
corresponding
values.
Request
routing
is
the
process
of
going
from
a
HTTP
request
to
the
series
of
steps
needed
to
implement
the
command
represented
by
that
request.
A
remote
end
has
an
associated
URL
prefix
,
which
is
used
as
a
prefix
on
all
WebDriver-defined
URLs
on
that
remote
end
.
This
must
either
be
undefined
or
a
path-absolute
URL
.
In
order
to
match
a
request
given
a
method
and
URL
,
the
following
steps
must
be
taken:
Let
endpoints
be
a
list
containing
each
row
in
the
table
of
endpoints
.
Remove
each
entry
from
endpoints
for
which
the
concatenation
of
the
URL
prefix
and
the
entry’s
URI
template
does
not
match
URL
’s
path
.
If
there
are
no
entries
in
endpoints
,
return
error
with
error
code
unknown
command
.
Remove
each
entry
in
endpoints
for
which
the
method
column
is
not
equal
to
method
.
If
there
are
no
entries
in
endpoints
,
return
error
with
error
code
unknown
method
.
There
is
now
exactly
one
entry
in
endpoints
;
let
entry
be
this
entry.
Let
parameters
be
the
result
of
extracting
the
variables
from
URL
using
entry
’s
URI
template
.
Let
command
be
entry
’s
command
.
Return
success
with
data
command
and
parameters
.
The
following
table
of
endpoints
lists
the
method
and
URI
template
for
each
endpoint
node
command
.
Extension
commands
are
implicitly
appended
to
this
table.
Errors
are
represented
in
the
WebDriver
protocol
by
an
HTTP
response
with
an
HTTP
status
in
the
4xx
or
5xx
range,
and
a
JSON
body
containing
details
of
the
error
.
The
body
is
a
JSON
Object
and
has
a
field
named
"
The
following
table
lists
each
error
code
,
its
associated
HTTP
status
,
JSON
An
error
data
dictionary
is
a
mapping
of
string
keys
to
JSON
serializable
values
that
can
optionally
be
included
with
error
objects.
Using
the
terminology
defined
in
this
section,
others
may
define
additional
commands
that
seamlessly
integrate
with
the
standard
protocol.
This
allows
vendors
to
expose
functionality
that
is
specific
to
their
user
agent,
and
it
also
allows
other
web
standards
to
define
commands
for
automating
new
platform
features.
Commands
defined
in
this
way
are
called
extension
commands
and
behave
no
differently
than
other
commands
;
each
has
a
dedicated
HTTP
endpoint
and
a
set
of
remote
end
steps
.
Each
extension
command
has
an
associated
extension
command
URI
Template
that
is
a
URI
Template
string,
and
which
should
bear
some
resemblance
to
what
the
command
performs.
This
value,
along
with
the
HTTP
method
and
extension
command
,
is
added
to
the
table
of
endpoints
and
thus
follows
the
same
rules
for
request
routing
as
that
of
other
built-in
commands
.
In
order
to
avoid
potential
resource
conflicts
with
other
implementations,
vendor-specific
extension
command
URI
Templates
must
begin
with
one
or
more
path
segments
which
uniquely
identifies
the
vendor
and
UA.
It
is
suggested
that
vendors
use
their
vendor
prefixes
without
additional
characters
as
outlined
in
[
CSS21
],
notably
in
section
4.1.2.2
on
vendor
keywords
,
as
the
name
for
this
path
element,
and
include
a
vendor-chosen
UA
identifier.
Remote
ends
may
also
introduce
extension
capabilities
that
are
extra
capabilities
used
to
provide
configuration
or
fulfill
other
vendor-specific
needs.
Extension
capabilities’
key
must
contain
a
"
As
with
extension
commands
,
it
is
suggested
that
the
key
used
to
denote
the
extension
capability
namespace
is
based
on
the
vendor
keywords
listed
in
[
CSS21
]
and
precedes
the
first
"
6.1
Algorithms
JSON.
[[Stringify]]
(
object
).
JSON.
[[Parse]]
(
text
).
6.2
Commands
6.3
Processing
model
null
if
there
is
no
such
matching
session
.
null
send
an
error
with
error
code
invalid
session
id
,
then
jump
to
step
1
in
this
overall
algorithm.
null
:
null
.
null
.
error
"
message
"
stacktrace
"
data
"
field
on
body
to
a
new
JSON
Object
populated
with
the
dictionary.
Content-Type
application/json;
charset=utf-8
"
Cache-Control
no-cache
"
value
"
set
to
data
.
6.4
Routing
requests
6.5
Endpoints
Method
URI
Template
Command
POST
/session
New
Session
DELETE
/session/{
session
id
}
Delete
Session
GET
/status
Status
GET
/session/{
session
id
}/timeouts
Get
Timeouts
POST
/session/{
session
id
}/timeouts
Set
Timeouts
POST
/session/{
session
id
}/url
Navigate
To
GET
/session/{
session
id
}/url
Get
Current
URL
POST
/session/{
session
id
}/back
Back
POST
/session/{
session
id
}/forward
Forward
POST
/session/{
session
id
}/refresh
Refresh
GET
/session/{
session
id
}/title
Get
Title
GET
/session/{
session
id
}/window
Get
Window
Handle
DELETE
/session/{
session
id
}/window
Close
Window
POST
/session/{
session
id
}/window
Switch
To
Window
GET
/session/{
session
id
}/window/handles
Get
Window
Handles
POST
/session/{
session
id
}/window/new
New
Window
POST
/session/{
session
id
}/frame
Switch
To
Frame
POST
/session/{
session
id
}/frame/parent
Switch
To
Parent
Frame
GET
/session/{
session
id
}/window/rect
Get
Window
Rect
POST
/session/{
session
id
}/window/rect
Set
Window
Rect
POST
/session/{
session
id
}/window/maximize
Maximize
Window
POST
/session/{
session
id
}/window/minimize
Minimize
Window
POST
/session/{
session
id
}/window/fullscreen
Fullscreen
Window
GET
/session/{
session
id
}/element/active
Get
Active
Element
POST
/session/{
session
id
}/element
Find
Element
POST
/session/{
session
id
}/elements
Find
Elements
POST
/session/{
session
id
}/element/{element
id}/element
Find
Element
From
Element
POST
/session/{
session
id
}/element/{element
id}/elements
Find
Elements
From
Element
GET
/session/{
session
id
}/element/{
element
id
}/selected
Is
Element
Selected
GET
/session/{
session
id
}/element/{
element
id
}/attribute/{
name
}
Get
Element
Attribute
GET
/session/{
session
id
}/element/{
element
id
}/property/{
name
}
Get
Element
Property
GET
/session/{
session
id
}/element/{
element
id
}/css/{
property
name
}
Get
Element
CSS
Value
GET
/session/{
session
id
}/element/{
element
id
}/text
Get
Element
Text
GET
/session/{
session
id
}/element/{
element
id
}/name
Get
Element
Tag
Name
GET
/session/{
session
id
}/element/{
element
id
}/rect
Get
Element
Rect
GET
/session/{
session
id
}/element/{
element
id
}/enabled
Is
Element
Enabled
POST
/session/{
session
id
}/element/{
element
id
}/click
Element
Click
POST
/session/{
session
id
}/element/{
element
id
}/clear
Element
Clear
POST
/session/{
session
id
}/element/{
element
id
}/value
Element
Send
Keys
GET
/session/{
session
id
}/source
Get
Page
Source
POST
/session/{
session
id
}/execute/sync
Execute
Script
POST
/session/{
session
id
}/execute/async
Execute
Async
Script
GET
/session/{
session
id
}/cookie
Get
All
Cookies
GET
/session/{
session
id
}/cookie/{
name
}
Get
Named
Cookie
POST
/session/{
session
id
}/cookie
Add
Cookie
DELETE
/session/{
session
id
}/cookie/{
name
}
Delete
Cookie
DELETE
/session/{
session
id
}/cookie
Delete
All
Cookies
POST
/session/{
session
id
}/actions
Perform
Actions
DELETE
/session/{
session
id
}/actions
Release
Actions
POST
/session/{
session
id
}/alert/dismiss
Dismiss
Alert
POST
/session/{
session
id
}/alert/accept
Accept
Alert
GET
/session/{
session
id
}/alert/text
Get
Alert
Text
POST
/session/{
session
id
}/alert/text
Send
Alert
Text
GET
/session/{
session
id
}/screenshot
Take
Screenshot
GET
/session/{
session
id
}/element/{
element
id
}/screenshot
Take
Element
Screenshot
6.6
Errors
value
"
whose
value
is
an
object
bearing
three,
and
sometimes
four,
fields:
error
",
containing
a
string
indicating
the
error
code
.
message
",
containing
an
implementation-defined
string
with
a
human
readable
description
of
the
kind
of
error
that
occurred.
stacktrace
",
containing
an
implementation-defined
string
with
a
stack
trace
report
of
the
active
stack
frames
at
the
time
when
the
error
occurred.
data
",
which
is
a
JSON
Object
with
additional
error
data
helpful
in
diagnosing
the
error.
error
code,
and
a
non-normative
description
of
the
error.
The
error
response
data
for
a
particular
error
code
is
the
values
of
the
HTTP
Status
and
JSON
Error
Code
columns
for
the
row
corresponding
to
that
error
code
.
Error
Code
HTTP
Status
JSON
Error
Code
Description
element
click
intercepted
400
element
click
intercepted
The
Element
Click
command
could
not
be
completed
because
the
element
receiving
the
events
is
obscuring
the
element
that
was
requested
clicked.
element
not
interactable
400
element
not
interactable
A
command
could
not
be
completed
because
the
element
is
not
pointer
-
or
keyboard
interactable
.
insecure
certificate
400
insecure
certificate
Navigation
caused
the
user
agent
to
hit
a
certificate
warning,
which
is
usually
the
result
of
an
expired
or
invalid
TLS
certificate.
invalid
argument
400
invalid
argument
The
arguments
passed
to
a
command
are
either
invalid
or
malformed.
invalid
cookie
domain
400
invalid
cookie
domain
An
illegal
attempt
was
made
to
set
a
cookie
under
a
different
domain
than
the
current
page.
invalid
element
state
400
invalid
element
state
A
command
could
not
be
completed
because
the
element
is
in
an
invalid
state,
e.g.
attempting
to
clear
an
element
that
isn’t
both
editable
and
resettable
.
invalid
selector
400
invalid
selector
Argument
was
an
invalid
selector.
invalid
session
id
404
invalid
session
id
Occurs
if
the
given
session
id
is
not
in
the
list
of
active
sessions
,
meaning
the
session
either
does
not
exist
or
that
it’s
not
active.
javascript
error
500
javascript
error
An
error
occurred
while
executing
JavaScript
supplied
by
the
user.
move
target
out
of
bounds
500
move
target
out
of
bounds
The
target
for
mouse
interaction
is
not
in
the
browser’s
viewport
and
cannot
be
brought
into
that
viewport.
no
such
alert
404
no
such
alert
An
attempt
was
made
to
operate
on
a
modal
dialog
when
one
was
not
open.
no
such
cookie
404
no
such
cookie
No
cookie
matching
the
given
path
name
was
found
amongst
the
associated
cookies
of
the
current
browsing
context
’s
active
document
.
no
such
element
404
no
such
element
An
element
could
not
be
located
on
the
page
using
the
given
search
parameters.
no
such
frame
404
no
such
frame
A
command
to
switch
to
a
frame
could
not
be
satisfied
because
the
frame
could
not
be
found.
no
such
window
404
no
such
window
A
command
to
switch
to
a
window
could
not
be
satisfied
because
the
window
could
not
be
found.
script
timeout
error
500
script
timeout
A
script
did
not
complete
before
its
timeout
expired.
session
not
created
500
session
not
created
A
new
session
could
not
be
created.
stale
element
reference
404
stale
element
reference
A
command
failed
because
the
referenced
element
is
no
longer
attached
to
the
DOM.
timeout
500
timeout
An
operation
did
not
complete
before
its
timeout
expired.
unable
to
set
cookie
500
unable
to
set
cookie
A
command
to
set
a
cookie’s
value
could
not
be
satisfied.
unable
to
capture
screen
500
unable
to
capture
screen
A
screen
capture
was
made
impossible.
unexpected
alert
open
500
unexpected
alert
open
A
modal
dialog
was
open,
blocking
this
operation.
unknown
command
404
unknown
command
A
command
could
not
be
executed
because
the
remote
end
is
not
aware
of
it.
unknown
error
500
unknown
error
An
unknown
error
occurred
in
the
remote
end
while
processing
the
command
.
unknown
method
405
unknown
method
The
requested
command
matched
a
known
URL
but
did
not
match
an
method
for
that
URL.
unsupported
operation
500
unsupported
operation
Indicates
that
a
command
that
should
have
executed
properly
cannot
be
supported
for
some
reason.
6.7
Extensions
:
"
(colon)
character,
denoting
an
implementation
specific
namespace.
The
value
can
be
arbitrary
JSON
types.
:
"
character
in
the
string.
WebDriver capabilities are used to communicate the features supported by a given implementation. The local end may use capabilities to define which features it requires the remote end to satisfy when creating a new session . Likewise, the remote end uses capabilities to describe the full feature set for a session .
The following table of standard capabilities enumerates the capabilities each implementation must support. An implementation may define additional extension capabilities .
Capability | Key | Value Type | Description |
---|---|---|---|
Browser name |
"
browserName
"
| string | Identifies the user agent. |
Browser version |
"
browserVersion
"
| string | Identifies the version of the user agent. |
Platform name |
"
platformName
"
| string | Identifies the operating system of the endpoint node . |
Accept insecure TLS certificates |
"
acceptInsecureCerts
"
| boolean | Indicates whether untrusted and self-signed TLS certificates are implicitly trusted on navigation for the duration of the session . |
Page load strategy |
"
pageLoadStrategy
"
| string | Defines the current session ’s page load strategy . |
Proxy configuration |
"
proxy
"
| JSON Object | Defines the current session ’s proxy configuration . |
Window dimensioning/positioning |
"
setWindowRect
"
| boolean | Indicates whether the remote end supports all of the resizing and repositioning commands . |
Session timeouts |
"
timeouts
"
| JSON Object | Describes the timeouts imposed on certain session operations. |
Strict file interactability |
"
strictFileInteractability
"
| boolean | Defines the current session ’s strict file interactability . |
Unhandled prompt behavior |
"
unhandledPromptBehavior
"
| string | Describes the current session ’s user prompt handler . Defaults to the dismiss and notify state . |
The proxy configuration capability is a JSON Object nested within the primary capabilities . Implementations may define additional proxy configuration options, but they must not alter the semantics of those listed below.
Key | Value Type | Description | Valid values |
---|---|---|---|
proxyType
| string | Indicates the type of proxy configuration. |
"
pac
",
"
direct
",
"
autodetect
",
"
system
",
or
"
manual
".
|
proxyAutoconfigUrl
| string |
Defines
the
URL
for
a
proxy
auto-config
file
if
is
equal
to
"
pac
".
| Any URL . |
ftpProxy
| string |
Defines
the
proxy
host
for
FTP
traffic
when
the
is
"
manual
".
|
A
host
and
optional
port
for
scheme
"
ftp
".
|
httpProxy
| string |
Defines
the
proxy
host
for
HTTP
traffic
when
the
is
"
manual
".
|
A
host
and
optional
port
for
scheme
"
http
".
|
noProxy
| array |
Lists
the
address
for
which
the
proxy
should
be
bypassed
when
the
is
"
manual
".
| A List containing any number of String s. |
sslProxy
| string |
Defines
the
proxy
host
for
encrypted
TLS
traffic
when
the
is
"
manual
".
|
A
host
and
optional
port
for
scheme
"
https
".
|
socksProxy
| string |
Defines
the
proxy
host
for
a
SOCKS
proxy
when
the
is
"
manual
".
| A host and optional port with an undefined scheme. |
socksVersion
| number |
Defines
the
SOCKS
proxy
version
when
the
is
"
manual
".
| Any integer between 0 and 255 inclusive. |
A host and optional port for a scheme is defined as being a valid host , optionally followed by a colon and a valid port . The host may include credentials . If the port is omitted and scheme has a default port , this is the implied port. Otherwise, the port is left undefined.
A
of
"
proxyType
direct
"
indicates
that
the
browser
should
not
use
a
proxy
at
all.
A
of
"
proxyType
system
"
indicates
that
the
browser
should
use
the
various
proxies
configured
for
the
underlying
Operating
System.
A
of
"
proxyType
autodetect
"
indicates
that
the
proxy
to
use
should
be
detected
in
an
implementation-specific
way.
The remote end steps to deserialize as a proxy argument parameter are:
If parameter is not a JSON Object return an error with error code invalid argument .
Let proxy be a new, empty proxy configuration object .
For each enumerable own property in parameter run the following substeps:
Let key be the name of the property.
Let value be the result of getting a property named name from parameter .
If
there
is
no
matching
key
for
key
in
the
proxy
configuration
table
return
an
error
with
error
code
invalid
argument
.
If
value
is
not
one
of
the
valid
values
for
that
key
,
return
an
error
with
error
code
invalid
argument
.
Set a property key to value on proxy .
If
proxy
does
not
have
an
own
property
for
"
proxyType
"
return
an
error
with
error
code
invalid
argument
.
If
the
result
of
getting
a
property
named
proxyType
from
proxy
equals
"
pac
",
and
proxy
does
not
have
an
own
property
for
"
proxyAutoconfigUrl
"
return
an
error
with
error
code
invalid
argument
.
If
proxy
has
an
own
property
for
"
socksProxy
"
and
does
not
have
an
own
property
for
"
socksVersion
"
return
an
error
with
error
code
invalid
argument
.
Return success with data proxy .
A proxy configuration object is a JSON Object where each of its own properties matching keys in the proxy configuration meets the validity criteria for that key.
To process capabilities with argument parameters , the endpoint node must take the following steps:
Let
capabilities
request
be
the
result
of
getting
the
property
"
capabilities
"
from
parameters
.
If capabilities request is not a JSON object, return error with error code invalid argument .
Let
required
capabilities
be
the
result
of
getting
the
property
"
alwaysMatch
"
from
capabilities
request
.
If required capabilities is undefined , set the value to an empty JSON Object .
Let required capabilities be the result of trying to validate capabilities with argument required capabilities .
Let
all
first
match
capabilities
be
the
result
of
getting
the
property
"
firstMatch
"
from
capabilities
request
.
If all first match capabilities is undefined , set the value to a JSON List with a single entry of an empty JSON Object .
If all first match capabilities is not a JSON List with one or more entries, return error with error code invalid argument .
Let validated first match capabilities be an empty JSON List .
For each first match capabilities corresponding to an indexed property in all first match capabilities :
Let validated capabilities be the result of trying to validate capabilities with argument first match capabilities .
Append validated capabilities to validated first match capabilities .
Let merged capabilities be an empty List .
For each first match capabilities corresponding to an indexed property in validated first match capabilities :
Let merged be the result of trying to merge capabilities with required capabilities and first match capabilities as arguments.
Append merged to merged capabilities .
For each capabilities corresponding to an indexed property in merged capabilities :
Let matched capabilities be the result of trying to match capabilities with capabilities as an argument.
If
matched
capabilities
is
not
null
,
return
matched
capabilities
.
When required to validate capabilities with argument capability :
If capability is not a JSON Object return an error with error code invalid argument .
Let result be an empty JSON Object .
For each enumerable own property in capability , run the following substeps:
Let name be the name of the property.
Let value be the result of getting a property named name from capability .
Run the substeps of the first matching condition:
null
Let
deserialized
be
set
to
null
.
acceptInsecureCerts
"
If value is not a boolean return an error with error code invalid argument . Otherwise, let deserialized be set to value
browserName
"
browserVersion
"
platformName
"
If value is not a string return an error with error code invalid argument . Otherwise, let deserialized be set to value .
pageLoadStrategy
"
Let deserialized be the result of trying to deserialize as a page load strategy with argument value .
proxy
"
Let deserialized be the result of trying to deserialize as a proxy with argument value .
strictFileInteractability
"
If value is not a boolean return an error with error code invalid argument . Otherwise, let deserialized be set to value
timeouts
"
Let deserialized be the result of trying to JSON deserialize as a timeouts configuration the value .
unhandledPromptBehavior
"
Let deserialized be the result of trying to deserialize as an unhandled prompt behavior with argument value .
If name is known to the implementation, let deserialized be the result of trying to deserialize value in an implementation-specific way. Otherwise, let deserialized be set to value .
Return an error with error code invalid argument .
If
deserialized
is
not
null
,
set
a
property
on
result
with
name
name
and
value
deserialized
.
When merging capabilities with JSON Object arguments primary and secondary , an endpoint node must take the following steps:
Let result be a new JSON Object .
For each enumerable own property in primary , run the following substeps:
Let name be the name of the property.
Let value be the result of getting a property named name from primary .
If secondary is undefined , return result .
For each enumerable own property in secondary , run the following substeps:
Let name be the name of the property.
Let value be the result of getting a property named name from secondary .
Let primary value be the result of getting the property name from primary .
If primary value is not undefined , return an error with error code invalid argument .
Return result .
When matching capabilities with JSON Object argument capabilities , an endpoint node must take the following steps:
Let matched capabilities be a JSON Object with the following entries:
browserName
"
browserVersion
"
platformName
"
acceptInsecureCerts
"
strictFileInteractability
"
setWindowRect
"
Optionally add extension capabilities as entries to matched capabilities . The values of these may be elided, and there is no requirement that all extension capabilities be added.
For each name and value corresponding to capability ’s own properties :
Run the substeps of the first matching name :
browserName
"
If
value
is
not
a
string
equal
to
the
"
browserName
"
entry
in
matched
capabilities
,
return
success
with
data
null
.
There
is
a
chance
the
remote
end
will
need
to
start
a
browser
process
to
correctly
determine
the
browserName
.
Lightweight
checks
are
preferred
before
this
is
done.
browserVersion
"
Compare
value
to
the
"
browserVersion
"
entry
in
matched
capabilities
using
an
implementation-defined
comparison
algorithm.
The
comparison
is
to
accept
a
value
that
places
constraints
on
the
version
using
the
"
<
",
"
<=
",
"
>
",
and
"
>=
"
operators.
If
the
two
values
do
not
match,
return
success
with
data
null
.
Version comparison is left as an implementation detail since each user agent will likely have conflicting methods of encoding the user agent version, and standardizing these schemes is beyond the scope of this standard.
There
is
a
chance
the
remote
end
will
need
to
start
a
browser
process
to
correctly
determine
the
browserVersion
.
Lightweight
checks
are
preferred
before
this
is
done.
platformName
"
If
value
is
not
a
string
equal
to
the
"
platformName
"
entry
in
matched
capabilities
,
return
success
with
data
null
.
The following platform names are in common usage with well-understood semantics and, when matching capabilities , greatest interoperability can be achieved by honoring them as valid synonyms for well-known Operating Systems:
Key | System |
---|---|
"
linux
"
|
Any server or desktop system based upon the Linux kernel. |
"
mac
"
|
Any version of Apple’s macOS. |
"
windows
"
|
Any version of Microsoft Windows, including desktop and mobile versions. |
This list is not exhaustive.
When
returning
capabilities
from
New
Session
,
it
is
valid
to
return
a
more
specific
platformName
,
allowing
users
to
correctly
identify
the
Operating
System
the
WebDriver
implementation
is
running
on.
acceptInsecureCerts
"
If
value
is
true
and
the
endpoint
node
does
not
support
insecure
TLS
certificates
,
return
success
with
data
null
.
If the endpoint node does not support insecure TLS certificates and this is the reason no match is ultimately made, it is useful to provide this information to the local end .
proxy
"
If
the
endpoint
node
does
not
allow
the
proxy
it
uses
to
be
configured,
or
if
the
proxy
configuration
defined
in
value
is
not
one
that
passes
the
endpoint
node
’s
implementation-specific
validity
checks,
return
success
with
data
null
.
A local end would only send this capability if it expected it to be honored and the configured proxy used. The intent is that if this is not possible a new session will not be established.
If name is the key of an extension capability ,
let
value
be
the
result
of
trying
implementation-specific
steps
to
match
on
name
with
value
.
If
the
match
is
not
successful,
return
success
with
data
null
.
Set a property on matched capabilities with name name and value value .
Return success with data matched capabilities .
A session is equivalent to a single instantiation of a particular user agent, including all its child browsers. WebDriver gives each session a unique session ID that can be used to differentiate one session from another, allowing multiple user agents to be controlled from a single HTTP server, and allowing sessions to be routed via a multiplexer (known as an intermediary node ).
A WebDriver session represents the connection between a local end and a specific remote end .
A session is started when a New Session is invoked. It is an error to send any commands before starting a session, or to continue to send commands after the session has been closed. Maintaining session continuity between commands to the remote end requires passing a session ID .
A session is torn down at some later point; either explicitly by invoking Delete Session , or implicitly when Close Window is called at the last remaining top-level browsing context .
An intermediary node will maintain an associated session for each active session . This is the session on the upstream neighbor that is created when the intermediary node executes the New Session command . Closing a session on an intermediary node will also close the session of the associated session .
All commands , except New Session and Status , have an associated current session , which is the session in which that command will run.
A remote end has an associated list of active sessions , which is a list of all sessions that are currently started. A remote end that is not an intermediary node has at most one active session at a given time.
A remote end has an associated maximum active sessions (an integer) that defines the number of active sessions that are supported. This may be “unlimited” for intermediary nodes , but must be exactly one for a remote end that is an endpoint node .
A
session
has
an
associated
session
ID
(a
string
representation
of
a
UUID
)
used
to
uniquely
identify
this
session.
Unless
stated
otherwise
it
is
null
.
A session has an associated current browsing context , which is the browsing context against which commands will run.
A session has an associated current top-level browsing context , which is the current browsing context if it itself is a top-level browsing context , and otherwise is the top-level browsing context of the current browsing context .
A session has an associated session timeouts that records the timeout duration values used to control the behavior of script evaluation , navigation , and element retrieval .
A session has an associated page loading strategy , which is one of the keywords from the table of page load strategies . Unless stated otherwise, it is normal .
A
session
has
an
associated
secure
TLS
state
that
indicates
whether
untrusted
or
self-signed
TLS
certificates
should
be
trusted
for
the
duration
of
the
WebDriver
session.
If
it
is
unset,
this
indicates
that
certificate-
or
TLS
errors
that
occur
upon
navigation
should
be
suppressed.
The
state
can
be
unset
by
providing
an
"
acceptInsecureCerts
"
capability
with
the
value
true.
Unless
stated
otherwise,
it
is
set.
A session has an associated strict file interactability state which is a boolean.
A session has an associated user prompt handler . Unless stated otherwise it is in the dismiss and notify state .
A session has an associated list of active input sources .
A session has an associated input state table .
A session has an associated input cancel list .
A session has an associated request queue which is a queue of requests that are currently awaiting processing.
When asked to close the session , a remote end must take the following steps:
Perform the following substeps based on the remote end ’s type:
Set the webdriver-active flag to false.
An endpoint node must close any top-level browsing contexts associated with the session , without prompting to unload .
Close the associated session . If this causes an error to occur, complete the remainder of this algorithm before returning the error .
Remove the current session from active sessions .
Perform any implementation-specific cleanup steps.
If
an
error
has
occurred
in
any
of
the
steps
above,
return
the
error
,
otherwise
return
success
with
data
null
.
Closing
a
session
might
cause
the
associated
browser
process
to
be
killed.
It
is
assumed
that
any
implementation-specific
cleanup
steps
are
performed
after
the
response
has
been
sent
back
to
the
client
so
that
the
connection
is
not
prematurely
closed.
The
New
Session
command
creates
a
new
WebDriver
session
with
the
endpoint
node
.
If
the
creation
fails,
a
session
not
created
error
is
returned.
If
the
remote
end
is
an
intermediary
node
,
it
may
use
the
result
of
the
capabilities
processing
algorithm
to
route
the
new
session
request
to
the
appropriate
endpoint
node
.
An
intermediary
node
is
free
to
define
extension
capabilities
to
assist
in
this
process,
however,
these
specific
capabilities
must
not
be
forwarded
to
the
endpoint
node
.
If
the
intermediary
node
requires
additional
information
unrelated
to
user
agent
features,
it
is
recommended
that
this
information
be
passed
as
top-level
parameters,
and
not
as
part
of
the
requested
capabilities
.
An
intermediary
node
must
forward
custom,
top-level
parameters
(i.e.
non-
capabilities
)
to
subsequent
remote
end
nodes.
The
remote
end
steps
are:
If
the
maximum
active
sessions
is
equal
to
the
length
of
the
list
of
active
sessions
,
return
error
with
error
code
session
not
created
.
If
the
remote
end
is
an
intermediary
node
,
take
implementation-defined
steps
that
either
result
in
returning
an
error
with
error
code
session
not
created
,
or
in
returning
a
success
with
data
that
is
isomorphic
to
that
returned
by
remote
ends
according
to
the
rest
of
this
algorithm.
If
an
error
is
not
returned,
the
intermediary
node
must
retain
a
reference
to
the
session
created
on
the
upstream
node
as
the
associated
session
such
that
commands
may
be
forwarded
to
this
associated
session
on
subsequent
commands.
How
this
is
done
is
entirely
up
to
the
implementation,
but
typically
the
If
the
maximum
active
sessions
is
equal
to
the
length
of
the
list
of
active
sessions
,
return
error
with
error
code
session
not
created
.
Let
capabilities
be
the
result
of
trying
to
process
capabilities
with
parameters
as
an
argument.
If
capabilities
’s
is
Let
session
id
be
the
result
of
generating
a
UUID
.
Let
session
be
a
new
session
with
the
session
ID
of
session
id
.
Set
the
current
session
to
session
.
Append
session
to
active
sessions
.
Let
body
be
a
JSON
Object
initialised
with:
Initialize
the
following
from
capabilities
:
Let
strategy
be
the
result
of
getting
property
"
If
strategy
is
a
string,
set
the
current
session
’s
page
loading
strategy
to
strategy
.
Otherwise,
set
the
page
loading
strategy
to
normal
and
set
a
property
of
capabilities
with
name
"
Let
strictFileInteractability
be
the
result
of
getting
property
"
If
strictFileInteractability
is
a
boolean,
set
the
current
session
’s
strict
file
interactability
to
strictFileInteractability
.
Otherwise
set
the
current
session
’s
strict
file
interactability
to
false.
Let
proxy
be
the
result
of
getting
property
"
Take
implementation-defined
steps
to
set
the
user
agent
proxy
using
the
extracted
proxy
configuration.
If
the
defined
proxy
cannot
be
configured
return
error
with
error
code
session
not
created
.
If
capabilities
has
a
property
with
the
key
"
Let
timeouts
be
the
result
of
trying
to
JSON
deserialize
as
a
timeouts
configuration
the
value
of
the
"
Make
the
session
timeouts
the
new
timeouts
.
Set
a
property
on
capabilities
with
name
"
Apply
changes
to
the
user
agent
for
any
implementation-defined
capabilities
selected
during
the
capabilities
processing
step.
Set
the
webdriver-active
flag
to
true.
Set
the
current
top-level
browsing
context
for
session
in
an
implementation-specific
way.
This
should
be
the
top-level
browsing
context
of
the
UA’s
current
browsing
context
.
WebDriver
implementations
typically
start
a
completely
new
browser
instance,
but
there
is
no
requirement
in
this
specification
(or
for
WebDriver
only
to
be
used
to
automate
only
web
browsers).
Implementations
might
choose
to
use
an
existing
browser
instance,
eg.
by
selecting
the
window
that
currently
has
focus.
Set
the
request
queue
to
a
new
queue
.
Return
success
with
data
body
.
The
remote
end
steps
are:
If
the
current
session
is
an
active
session
,
try
to
close
the
session
.
Implementations
may
optionally
include
additional
meta
information
as
part
of
the
body,
but
the
top-level
properties
The
remote
end
steps
are:
Let
body
be
a
new
JSON
Object
with
the
following
properties:
The
remote
end
’s
readiness
state
.
An
implementation-defined
string
explaining
the
remote
end
’s
readiness
state
.
Return
success
with
data
body
.
8.1
New
Session
HTTP
Method
URI
Template
POST
/session
sessionId
,
and
URL
and
URL
prefix
of
the
upstream
remote
end
will
need
to
be
tracked.
null
,
return
error
with
error
code
session
not
created
.
sessionId
"
capabilities
"
pageLoadStrategy
"
from
capabilities
.
pageLoadStrategy
"
and
value
"
normal
".
strictFileInteractability
"
from
capabilities
.
proxy
"
from
capabilities
and
run
the
substeps
of
the
first
matching
statement:
proxy
"
and
a
value
that
is
a
new
JSON
Object
.
timeouts
":
timeouts
"
property.
timeouts
"
and
value
that
of
the
JSON
deserialization
of
the
session
timeouts
.
8.2
Delete
Session
HTTP
Method
URI
Template
DELETE
/session/{
session
id
}
8.3
Status
HTTP
Method
URI
Template
GET
/status
ready
and
message
are
reserved
and
must
not
be
overwritten.
ready
"
message
"
A timeouts configuration is a record of the different timeouts that control the behavior of script evaluation , navigation , and element retrieval :
Field | Default | JSON key | Optional † | Nullable | Description † |
---|---|---|---|---|---|
Script timeout | 30,000 |
"
script
"
| ✓ | ✓ |
Specifies when to interrupt a script that is being evaluated .
A
|
Page load timeout | 300,000 |
"
pageLoad
"
| ✓ |
Provides the timeout limit used to interrupt an explicit navigation attempt. | |
Implicit wait timeout | 0 |
"
implicit
"
| ✓ |
Specifies a time to wait for the element location strategy to complete when locating an element |
† Informative.
The timeouts configuration ’s JSON serialization is expressed as a JSON Object with the following properties:
script
"
pageLoad
"
implicit
"
To JSON deserialize an input value into a timeouts configuration record:
Let timeouts be a new timeouts configuration .
If value is not a JSON Object , return error with error code invalid argument .
If
value
has
a
property
with
the
key
"
script
":
Let
script
duration
be
the
value
of
property
"
script
".
If
script
duration
is
a
number
and
less
than
0
or
greater
than
2
16
–
1,
or
it
is
not
null
,
return
error
with
error
code
invalid
argument
.
Set timeouts ’s script timeout to script duration .
If
value
has
a
property
with
the
key
"
pageLoad
":
Let
page
load
duration
be
the
value
of
property
"
pageLoad
".
If page load duration is less than 0 or greater than 2 16 – 1, return error with error code invalid argument .
Set timeouts ’s page load timeout to page load duration .
If
value
has
a
property
with
the
key
"
implicit
":
Let
implicit
duration
be
the
value
of
property
"
implicit
".
If implicit duration is less than 0 or greater than 2 16 – 1, return error with error code invalid argument .
Set timeouts ’s implicit wait timeout to implicit duration .
Return success with data timeouts .
HTTP Method | URI Template |
---|---|
GET | /session/{ session id }/timeouts |
The remote end step is to return success with data being the JSON serialization of the active session ’s timeouts configuration .
HTTP Method | URI Template |
---|---|
POST | /session/{ session id }/timeouts |
The remote end steps are:
Let timeouts be the result of trying to JSON deserialize as a timeouts configuration the request’s parameters .
Make the session timeouts the new timeouts .
Many WebDriver commands happen in the context of either the current browsing context or current top-level browsing context . The current top-level browsing context is represented in the protocol by its associated window handle . When a top-level browsing context is selected using the Switch To Window command, a specific browsing context can be selected using the Switch to Frame command.
The
use
of
the
term
“window”
to
refer
to
a
top-level
browsing
context
is
legacy
and
doesn’t
correspond
with
either
the
operating
system
notion
of
a
“window”
or
the
DOM
Window
object.
A browsing context is said to be no longer open if it has been discarded .
Each
browsing
context
has
an
associated
window
handle
which
uniquely
identifies
it.
This
must
be
a
String
and
must
not
be
"
current
".
The
web
window
identifier
is
the
string
constant
"
window-fcc6-11e5-b4f8-330a88ab9d7f
".
The
web
frame
identifier
is
the
string
constant
"
frame-075b-4da1-b6ba-e579c2d3230a
".
The
JSON
serialization
of
the
WindowProxy
object
is
the
JSON
Object
obtained
by
applying
the
following
algorithm
to
the
given
WindowProxy
object
window
:
Let identifier be the web window identifier if the associated browsing context of window is a top-level browsing context .
Otherwise let it be the web frame identifier .
Return a JSON Object initialised with the following properties:
Associated window handle of the window ’s browsing context .
In accordance with the focus section of the [ HTML ] specification, commands are unaffected by whether the operating system window has focus or not.
HTTP Method | URI Template |
---|---|
GET | /session/{ session id }/window |
The remote end steps are:
If the current top-level browsing context is no longer open , return error with error code no such window .
Return success with data being the window handle associated with the current top-level browsing context .
HTTP Method | URI Template |
---|---|
DELETE | /session/{ session id }/window |
The remote end steps are:
If the current top-level browsing context is no longer open , return error with error code no such window .
Handle any user prompts and return its value if it is an error .
If there are no more open top-level browsing contexts , then try to close the session .
HTTP Method | URI Template |
---|---|
POST | /session/{ session id }/window |
Switching window will select the current top-level browsing context used as the target for all subsequent commands . In a tabbed browser, this will typically make the tab containing the browsing context the selected tab.
The remote end steps are:
Let
handle
be
the
result
of
getting
the
property
"
handle
"
from
the
parameters
argument.
If handle is undefined , return error with error code invalid argument .
If there is an active user prompt , that prevents the focussing of another top-level browsing context , return error with error code unexpected alert open .
If handle is equal to the associated window handle for some top-level browsing context in the current session , set the session ’s current browsing context to that browsing context.
Otherwise, return error with error code no such window .
Update any implementation-specific state that would result from the user selecting the current browsing context for interaction, without altering OS-level focus.
HTTP Method | URI Template |
---|---|
GET | /session/{ session id }/window/handles |
The order in which the window handles are returned is arbitrary.
The remote end steps are:
Let handles be a JSON List .
For each top-level browsing context in the remote end , push the associated window handle onto handles .
HTTP Method | URI Template |
---|---|
POST | /session/{ session id }/window/new |
Create a new top-level browsing context .
The remote end steps are:
If the implementation does not support creating new top-level browsing contexts, return error with error code unsupported operation .
If the current top-level browsing context is no longer open , return error with error code no such window .
Handle any user prompts and return its value if it is an error .
Let
type
hint
be
the
result
of
getting
the
property
"
type
"
from
the
parameters
argument.
Create
a
new
top-level
browsing
context
by
running
the
window
open
steps
with
url
set
to
"
about:blank
",
target
set
to
the
empty
string,
and
features
set
to
"
noopener
"
and
the
user
agent
configured
to
create
a
new
browsing
context.
This
must
be
done
without
invoking
the
focusing
steps
for
the
created
browsing
context.
If
type
hint
has
the
value
"
tab
",
and
the
implementation
supports
multiple
browsing
context
in
the
same
OS
window,
the
new
browsing
context
should
share
an
OS
window
with
the
current
browsing
context
.
If
type
hint
is
"
window
",
and
the
implementation
supports
multiple
browsing
contexts
in
separate
OS
windows,
the
created
browsing
context
should
be
in
a
new
OS
window.
In
all
other
cases
the
details
of
how
the
browsing
context
is
presented
to
the
user
are
implementation
defined.
Let handle be the associated window handle of the newly created window.
Let
type
be
"
tab
"
if
the
newly
created
window
shares
an
OS-level
window
with
the
current
browsing
context
,
or
"
window
"
otherwise.
Let result be a new JSON Object initialised with:
handle
"
type
"
Return success with data result .
HTTP Method | URI Template |
---|---|
POST | /session/{ session id }/frame |
The Switch To Frame command is used to select the current top-level browsing context or a child browsing context of the current browsing context to use as the current browsing context for subsequent commands .
The remote end steps are:
Let
id
be
the
result
of
getting
the
property
"
id
"
from
the
parameters
argument.
If
id
is
not
null
,
a
Number
object,
or
an
Object
that
represents
a
web
element
,
return
error
with
error
code
invalid
argument
.
If the current browsing context is no longer open , return error with error code no such window .
Handle any user prompts and return its value if it is an error .
Run the substeps of the first matching condition:
null
Set the current browsing context to the current top-level browsing context .
Number
object
If id is less than 0 or greater than 2 16 – 1, return error with error code invalid argument .
Let window be the associated window of the current browsing context ’s active document .
If id is not a supported property index of window , return error with error code no such frame .
Let
child
window
be
the
WindowProxy
object
obtained
by
calling
window
.
[[GetOwnProperty]]
(
id
).
Set the current browsing context to child window ’s browsing context .
Let element be the result of trying to get a known element by web element reference id .
If element is stale , return error with error code stale element reference .
If
element
is
not
a
frame
or
iframe
element,
return
error
with
error
code
no
such
frame
.
Set the current browsing context to element ’s nested browsing context .
Update any implementation-specific state that would result from the user selecting the current browsing context for interaction, without altering OS-level focus.
WebDriver is not bound by the same origin policy, so it is always possible to switch into child browsing contexts, even if they are different origin to the current browsing context.
HTTP Method | URI Template |
---|---|
POST | /session/{ session id }/frame/parent |
The Switch to Parent Frame command sets the current browsing context for future commands to the parent of the current browsing context .
The remote end steps are:
If the current browsing context is no longer open , return error with error code no such window .
Handle any user prompts and return its value if it is an error .
If the current browsing context is not equal to the current top-level browsing context , set the current browsing context to the parent browsing context of the current browsing context .
Update any implementation-specific state that would result from the user selecting the current browsing context for interaction, without altering OS-level focus.
WebDriver provides commands for interacting with the operating system window containing the current top-level browsing context . Because different operating systems’ window managers provide different abilities, not all of the commands in this section can be supported by all remote ends . Support for these commands is determined by the window dimensioning/positioning capability . Where a command is not supported, an unsupported operation error is returned.
The top-level browsing context has an associated window state which describes what visibility state its OS widget window is in. It can be in one of the following states:
State | Keyword | Default | Description |
---|---|---|---|
Maximized window state |
"
maximized
"
| The window is maximized. | |
Minimized window state |
"
minimized
"
| The window is iconified. | |
Normal window state |
"
normal
"
| ✓ | The window is shown normally. |
Fullscreen window state |
"
fullscreen
"
| The window is in full screen mode. |
If for whatever reason the top-level browsing context ’s OS window cannot enter either of the window states , or if this concept is not applicable on the current system, the default state must be normal .
A
top-level
browsing
context
’s
window
rect
is
defined
as
a
dictionary
of
the
screenX
,
screenY
,
outerWidth
and
outerHeight
attributes
of
the
WindowProxy
.
Its
JSON
representation
is
the
following:
x
"
WindowProxy
’s
screenX
attribute.
y
"
WindowProxy
’s
screenY
attribute.
width
"
WindowProxy
’s
outerWidth
attribute.
height
"
WindowProxy
’s
outerHeight
attribute.
To maximize the window , given an operating system level window with an associated top-level browsing context , run the implementation-specific steps to transition the operating system level window into the maximized window state . If the window manager supports window resizing but does not have a concept of window maximization, the window dimensions must be increased to the maximum available size permitted by the window manager for the current screen. Return when the window has completed the transition, or within an implementation-defined timeout.
To iconify the window , given an operating system level window with an associated top-level browsing context , run implementation-specific steps to iconify, minimize, or hide the window from the visible screen. Do not return from this operation until the visibility state of the top-level browsing context ’s active document has reached the hidden state, or until the operation times out.
To
restore
the
window
,
given
an
operating
system
level
window
with
an
associated
top-level
browsing
context
,
run
implementation-specific
steps
to
restore
or
unhide
the
window
to
the
visible
screen.
Do
not
return
from
this
operation
until
the
visibility
state
of
the
top-level
browsing
context
’s
active
document
has
reached
the
visible
state,
or
until
the
operation
times
out.
The
Get
Window
Rect
command
returns
the
size
and
position
on
the
screen
of
the
operating
system
window
corresponding
to
the
current
top-level
browsing
context
.
The
remote
end
steps
are:
If
the
current
top-level
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Return
success
with
the
JSON
serialization
of
the
current
top-level
browsing
context
’s
window
rect
.
The
Set
Window
Rect
command
alters
the
size
and
the
position
of
the
operating
system
window
corresponding
to
the
current
top-level
browsing
context
.
The
remote
end
steps
are:
Let
width
be
the
result
of
getting
a
property
named
Let
height
be
the
result
of
getting
a
property
named
Let
x
be
the
result
of
getting
a
property
named
Let
y
be
the
result
of
getting
a
property
named
If
width
or
height
is
neither
If
x
or
y
is
neither
If
the
remote
end
does
not
support
the
Set
Window
Rect
command
for
the
current
top-level
browsing
context
for
any
reason,
return
error
with
error
code
unsupported
operation
.
If
the
current
top-level
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
If
width
and
height
are
not
Set
the
width,
in
CSS
pixels
,
of
the
operating
system
window
containing
the
current
top-level
browsing
context
,
including
any
browser
chrome
and
externally
drawn
window
decorations
to
a
value
that
is
as
close
as
possible
to
width
.
Set
the
height,
in
CSS
pixels
,
of
the
operating
system
window
containing
the
current
top-level
browsing
context
,
including
any
browser
chrome
and
externally
drawn
window
decorations
to
a
value
that
is
as
close
as
possible
to
height
.
If
x
and
y
are
not
Run
the
implementation-specific
steps
to
set
the
position
of
the
operating
system
level
window
containing
the
current
top-level
browsing
context
to
the
position
given
by
the
x
and
y
coordinates.
Return
success
with
the
JSON
serialization
of
the
current
top-level
browsing
context
’s
window
rect
.
The
Maximize
Window
command
invokes
the
window
manager-specific
“maximize”
operation,
if
any,
on
the
window
containing
the
current
top-level
browsing
context
.
This
typically
increases
the
window
to
the
maximum
available
size
without
going
full-screen.
The
remote
end
steps
are:
If
the
remote
end
does
not
support
the
Maximize
Window
command
for
the
current
top-level
browsing
context
for
any
reason,
return
error
with
error
code
unsupported
operation
.
If
the
current
top-level
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Maximize
the
window
of
the
current
top-level
browsing
context
.
Return
success
with
the
JSON
serialization
of
the
current
top-level
browsing
context
’s
window
rect
.
The
Minimize
Window
command
invokes
the
window
manager-specific
“minimize”
operation,
if
any,
on
the
window
containing
the
current
top-level
browsing
context
.
This
typically
hides
the
window
in
the
system
tray.
The
remote
end
steps
are:
If
the
remote
end
does
not
support
the
Minimize
Window
command
for
the
current
top-level
browsing
context
for
any
reason,
return
error
with
error
code
unsupported
operation
.
If
the
current
top-level
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Return
success
with
the
JSON
serialization
of
the
current
top-level
browsing
context
’s
window
rect
.
The
remote
end
steps
are:
If
the
remote
end
does
not
support
fullscreen
return
error
with
error
code
unsupported
operation
.
If
the
current
top-level
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Call
fullscreen
an
element
with
the
current
top-level
browsing
context
’s
active
document
’s
document
element
.
Return
success
with
the
JSON
serialization
of
the
current
top-level
browsing
context
’s
window
rect
.
11.8.1
Get
Window
Rect
HTTP
Method
URI
Template
GET
/session/{session
id}/window/rect
11.8.2
Set
Window
Rect
HTTP
Method
URI
Template
POST
/session/{
session
id
}/window/rect
width
from
the
parameters
argument,
else
let
it
be
null
.
height
from
the
parameters
argument,
else
let
it
be
null
.
x
from
the
parameters
argument,
else
let
it
be
null
.
y
from
the
parameters
argument,
else
let
it
be
null
.
null
nor
a
Number
from
0
to
2
31
−
1,
return
error
with
error
code
invalid
argument
.
null
nor
a
Number
from
−(2
31
)
to
2
31
−
1,
return
error
with
error
code
invalid
argument
.
null
:
null
:
11.8.3
Maximize
Window
HTTP
Method
URI
Template
POST
/session/{
session
id
}/window/maximize
11.8.4
Minimize
Window
HTTP
Method
URI
Template
POST
/session/{
session
id
}/window/minimize
11.8.5
Fullscreen
Window
HTTP
Method
URI
Template
POST
/session/{
session
id
}/window/fullscreen
A web element is an abstraction used to identify an element when it is transported via the protocol , between remote - and local ends.
The
web
element
identifier
is
the
string
constant
"
element-6066-11e4-a52e-4f735466cecf
".
Each element has an associated web element reference that uniquely identifies the element across all browsing contexts . The web element reference for every element representing the same element must be the same. It must be a string, and should be the result of generating a UUID .
An ECMAScript Object represents a web element if it has a web element identifier own property .
Each browsing context has an associated list of known elements . When the browsing context is discarded , the list of known elements is discarded along with it.
To get a known element with argument reference , run the following steps:
To get a known connected element with argument reference , run the following steps:
To create a web element reference for an element :
For each known element of the current browsing context ’s list of known elements :
If known element equals element , return success with known element ’s web element reference .
Add element to the list of known elements of the current browsing context .
Return success with the element ’s web element reference .
The JSON serialization of an element is a JSON Object where the web element identifier key is mapped to the element ’s web element reference .
When required to deserialize a web element by a JSON Object object that represents a web element :
If object has no own property web element identifier , return error with error code invalid argument .
Let reference be the result of getting the web element identifier property from object .
Let element be the result of trying to get a known element with argument reference .
Return success with data element .
An element is stale if its node document is not the active document or if its context object is not connected .
To scroll into view an element perform the following steps only if the element is not already in view :
Let
options
be
the
following
ScrollIntoViewOptions
:
behavior
"
instant
"
block
"
end
"
inline
"
nearest
"
On the element , Call ( scrollIntoView , options ).
Editable elements are those that can be used for typing and clearing , and they fall into two subcategories:
Denotes
input
elements
that
are
mutable
(e.g.
that
are
not
read
only
or
disabled
)
and
whose
type
attribute
is
in
one
of
the
following
states:
And
the
textarea
element
.
Denotes elements that are editing hosts or content editable .
An
element
is
said
to
have
pointer
events
disabled
if
the
resolved
value
of
its
"
pointer-events
"
style
property
is
"
none
".
An
element
is
to
be
considered
read
only
if
it
is
an
In
order
to
determine
if
an
element
can
be
interacted
with
using
pointer
actions,
WebDriver
performs
hit-testing
to
find
if
the
interaction
will
be
able
to
reach
the
requested
element.
An
interactable
element
is
an
element
which
is
either
pointer-interactable
or
keyboard-interactable
.
A
pointer-interactable
element
is
defined
to
be
the
first
element
,
defined
by
the
paint
order
found
at
the
center
point
of
its
rectangle
that
is
inside
the
viewport
,
excluding
the
size
of
any
rendered
scrollbars.
A
keyboard-interactable
element
is
any
element
that
has
a
focusable
area
,
is
a
An
element
’s
in-view
center
point
is
the
origin
position
of
the
rectangle
that
is
the
intersection
between
the
element’s
first
DOM
client
rectangle
and
the
initial
viewport
.
Given
an
element
that
is
known
to
be
in
view
,
it
can
be
calculated
this
way:
Let
rectangle
be
the
first
element
of
the
Let
left
be
max
(0,
min
(
x
coordinate
,
x
coordinate
+
width
dimension
)).
Let
right
be
min
(
innerWidth
,
max
(
x
coordinate
,
x
coordinate
+
width
dimension
)).
Let
top
be
max
(0,
min
(
y
coordinate
,
y
coordinate
+
height
dimension
)).
Let
bottom
be
min
(
innerHeight
,
max
(
y
coordinate
,
y
coordinate
+
height
dimension
)).
Let
x
be
floor
((
left
+
right
)
÷
2.0).
Let
y
be
floor
((
top
+
bottom
)
÷
2.0).
Return
the
pair
of
(
x
,
y
).
An
element
is
in
view
if
it
is
a
member
of
its
own
pointer-interactable
paint
tree
,
given
the
pretense
that
its
pointer
events
are
not
disabled
.
An
element
is
obscured
if
the
pointer-interactable
paint
tree
at
its
center
point
is
empty,
or
the
first
element
in
this
tree
is
not
an
inclusive
descendant
of
itself.
An
element
’s
pointer-interactable
paint
tree
is
produced
this
way:
If
element
is
not
in
the
same
tree
as
the
current
browsing
context
’s
active
document
,
return
an
empty
sequence.
Let
rectangles
be
the
If
rectangles
has
the
length
of
0,
return
an
empty
sequence.
Let
center
point
be
the
in-view
center
point
of
the
first
indexed
element
in
rectangles
.
Return
the
elements
from
point
given
the
coordinates
center
point
.
The
Find
Element
,
Find
Elements
,
Find
Element
From
Element
,
and
Find
Elements
From
Element
commands
allow
lookup
of
individual
elements
and
collections
of
elements.
Element
retrieval
searches
are
performed
using
pre-order
traversal
of
the
document’s
nodes
that
match
the
provided
selector’s
expression.
Elements
are
serialized
and
returned
as
web
elements
.
When
required
to
find
with
arguments
start
node
,
using
and
value
,
a
remote
end
must
run
the
following
steps:
Let
end
time
be
the
current
time
plus
the
session
implicit
wait
timeout
.
Let
location
strategy
be
equal
to
using
.
Let
selector
be
equal
to
value
.
Let
elements
returned
be
the
result
of
trying
to
call
the
relevant
element
location
strategy
with
arguments
start
node
,
and
selector
.
If
elements
returned
is
empty
and
the
current
time
is
less
than
end
time
return
to
step
4.
Otherwise,
continue
to
the
next
step.
Let
result
be
an
empty
JSON
List
.
For
each
element
in
elements
returned
,
append
the
serialization
of
element
to
result
.
Return
success
with
data
result
.
An
element
location
strategy
is
an
enumerated
attribute
deciding
what
technique
should
be
used
to
search
for
elements
in
the
current
browsing
context
.
The
following
table
of
location
strategies
lists
the
keywords
and
states
defined
for
this
attribute:
To
find
a
web
element
with
the
CSS
Selector
strategy
the
following
steps
need
to
be
completed:
Let
elements
be
the
result
of
calling
querySelectorAll
with
selector
with
the
context
object
equal
to
the
start
node
.
If
this
causes
an
exception
to
be
thrown,
return
error
with
error
code
invalid
selector
.
Return
success
with
data
elements
.
To
find
a
web
element
with
the
Link
Text
strategy
the
following
steps
need
to
be
completed:
Let
elements
be
the
result
of
calling
querySelectorAll
,
with
argument
Let
result
be
an
empty
NodeList
.
For
each
element
in
elements
:
Let
rendered
text
be
the
value
that
would
be
returned
via
a
call
to
Get
Element
Text
for
element
.
Let
trimmed
text
be
the
result
of
removing
all
whitespace
from
the
start
and
end
of
the
string
rendered
text
.
If
trimmed
text
equals
selector
,
append
element
to
result
.
Return
success
with
data
result
.
The
Partial
link
text
strategy
is
very
similar
to
the
Link
Text
strategy
,
but
rather
than
matching
the
entire
string,
only
a
substring
needs
to
match.
That
is,
return
all
To
find
a
web
element
with
the
Partial
Link
Text
strategy
the
following
steps
need
to
be
completed:
Let
elements
be
the
result
of
calling
querySelectorAll
,
with
argument
Let
result
be
an
empty
NodeList
.
For
each
element
in
elements
:
Let
rendered
text
be
the
value
that
would
be
returned
via
a
call
to
Get
Element
Text
for
element
.
If
rendered
text
contains
selector
,
append
element
to
result
.
Return
success
with
data
result
.
To
find
a
web
element
with
the
Tag
Name
strategy
return
success
with
data
set
to
the
result
of
calling
To
find
a
web
element
with
the
XPath
Selector
strategy
the
following
steps
need
to
be
completed:
Let
evaluateResult
be
the
result
of
calling
A
snapshot
is
used
to
promote
operation
atomicity.
Let
index
be
0.
Let
length
be
the
result
of
getting
the
property
"
Let
result
be
an
empty
NodeList
.
Repeat,
while
index
is
less
than
length
:
If
node
is
not
an
element
return
an
error
with
error
code
invalid
selector
.
Return
success
with
data
result
.
The
remote
end
steps
are:
Let
location
strategy
be
the
result
of
getting
a
property
called
"
If
location
strategy
is
not
present
as
a
keyword
in
the
table
of
location
strategies
,
return
error
with
error
code
invalid
argument
.
Let
selector
be
the
result
of
getting
a
property
called
"
If
selector
is
undefined
,
return
error
with
error
code
invalid
argument
.
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
start
node
be
the
current
browsing
context
’s
document
element
.
If
start
node
is
Let
result
be
the
result
of
trying
to
Find
with
start
node
,
location
strategy
,
and
selector
.
If
result
is
empty,
return
error
with
error
code
no
such
element
.
Otherwise,
return
the
first
element
of
result
.
The
remote
end
steps
are:
Let
location
strategy
be
the
result
of
getting
a
property
called
"
If
location
strategy
is
not
present
as
a
keyword
in
the
table
of
location
strategies
,
return
error
with
error
code
invalid
argument
.
Let
selector
be
the
result
of
getting
a
property
called
"
If
selector
is
undefined
,
return
error
with
error
code
invalid
argument
.
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
start
node
be
the
current
browsing
context
’s
document
element
.
If
start
node
is
The
remote
end
steps
are:
Let
location
strategy
be
the
result
of
getting
a
property
called
"
If
location
strategy
is
not
present
as
a
keyword
in
the
table
of
location
strategies
,
return
error
with
error
code
invalid
argument
.
Let
selector
be
the
result
of
getting
a
property
called
"
If
selector
is
undefined
,
return
error
with
error
code
invalid
argument
.
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
start
node
be
the
result
of
trying
to
get
a
known
connected
element
with
url
variable
element
id
.
If
result
is
empty,
return
error
with
error
code
no
such
element
.
Otherwise,
return
the
first
element
of
result
.
The
remote
end
steps
are:
Let
location
strategy
be
the
result
of
getting
a
property
called
"
If
location
strategy
is
not
present
as
a
keyword
in
the
table
of
location
strategies
,
return
error
with
error
code
invalid
argument
.
Let
selector
be
the
result
of
getting
a
property
called
"
If
selector
is
undefined
,
return
error
with
error
code
invalid
argument
.
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
start
node
be
the
result
of
trying
to
get
a
known
connected
element
with
url
variable
element
id
.
The
remote
end
steps
are:
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
active
element
be
the
active
element
of
the
current
browsing
context
’s
document
element
.
If
active
element
is
a
non-null
element
,
return
success
with
its
JSON
serialization
.
Otherwise,
return
error
with
error
code
no
such
element
.
To
calculate
the
absolute
position
of
element
:
Let
rect
be
the
value
returned
by
calling
getBoundingClientRect
.
Let
window
be
the
associated
window
of
current
top-level
browsing
context
.
Let
x
be
(
scrollX
of
window
+
rect
’s
x
coordinate
).
Let
y
be
(
scrollY
of
window
+
rect
’s
y
coordinate
).
Return
a
pair
of
(
x
,
y
).
To
determine
if
node
is
not
in
the
same
tree
as
another
node
,
other
,
run
the
following
substeps:
If
the
node
’s
node
document
is
not
other
’s
node
document
,
return
true.
Return
true
if
the
result
of
calling
the
node
’s
compareDocumentPosition
with
other
as
argument
is
DOCUMENT_POSITION_DISCONNECTED
(1),
otherwise
return
false.
An
element
’s
container
is:
The
element
’s
element
context
,
which
is
determined
by:
Let
datalist
parent
be
the
first
Let
select
parent
be
the
first
If
datalist
parent
is
undefined
,
the
element
context
is
select
parent
.
Otherwise,
the
element
context
is
datalist
parent
.
The
element
does
not
have
a
container.
The
container
is
the
element
itself.
The
Is
Element
Selected
command
determines
if
the
referenced
element
is
selected
or
not.
This
operation
only
makes
sense
on
The
remote
end
steps
are:
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
element
be
the
result
of
trying
to
get
a
known
connected
element
with
url
variable
element
id
.
Let
selected
be
the
value
corresponding
to
the
first
matching
statement:
The
result
of
element
’s
checkedness
.
The
result
of
element
’s
selectedness
.
Return
success
with
data
selected
.
The
remote
end
steps
are:
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
element
be
the
result
of
trying
to
get
a
known
element
with
url
variable
element
id
.
"
The
result
of
getting
an
attribute
by
name
name
.
Return
success
with
data
result
.
Please
note
that
the
behavior
of
this
command
deviates
from
the
behavior
of
getAttribute
in
[
DOM
],
which
in
the
case
of
a
set
boolean
attribute
would
return
an
empty
string.
The
reason
this
command
returns
true
as
a
string
is
because
this
evaluates
to
true
in
most
dynamically
typed
programming
languages,
but
still
preserves
the
expected
type
information.
The
remote
end
steps
are:
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
element
be
the
result
of
trying
to
get
a
known
element
with
url
variable
element
id
.
Let
property
be
the
result
of
calling
the
element
.
[[GetProperty]]
(
name
).
Let
result
be
the
value
of
property
if
not
undefined
,
or
Return
success
with
data
result
.
The
remote
end
steps
are:
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
element
be
the
result
of
trying
to
get
a
known
connected
element
with
url
variable
element
id
.
Let
computed
value
be
the
result
of
the
first
matching
condition:
When
processing
text,
whitespace
is
defined
as
characters
from
the
Unicode
Character
Database
with
the
Unicode
character
property
"
The
remote
end
steps
are:
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
element
be
the
result
of
trying
to
get
a
known
connected
element
with
url
variable
element
id
.
Let
rendered
text
be
the
result
of
performing
implementation-specific
steps
whose
result
is
exactly
the
same
as
the
result
of
a
Call
(
Return
success
with
data
rendered
text
.
The
remote
end
steps
are:
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
element
be
the
result
of
trying
to
get
a
known
element
with
url
variable
element
id
.
Let
qualified
name
be
the
result
of
getting
element
’s
tagName
content
attribute
.
Return
success
with
data
qualified
name
.
The
remote
end
steps
are:
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
element
be
the
result
of
trying
to
get
a
known
connected
element
with
url
variable
element
id
.
Calculate
the
absolute
position
of
element
and
let
it
be
coordinates
.
Let
rect
be
element
’s
bounding
rectangle
.
Let
body
be
a
new
JSON
Object
initialised
with:
Return
success
with
data
body
.
The
remote
end
steps
are:
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
element
be
the
result
of
trying
to
get
a
known
connected
element
with
url
variable
element
id
.
Let
enabled
be
a
boolean
initially
set
to
true
if
the
current
browsing
context
’s
document
type
is
not
"
Otherwise,
let
enabled
to
false
and
jump
to
the
last
step
of
this
algorithm.
Set
enabled
to
false
if
a
form
control
is
disabled
.
Return
success
with
data
enabled
.
The
element
interaction
commands
provide
a
high-level
instruction
set
for
manipulating
form
controls.
Unlike
Actions
,
they
will
implicitly
scroll
elements
into
view
and
check
that
it
is
an
interactable
element
.
Some
resettable
elements
define
their
own
clear
algorithm
.
Unlike
their
associated
reset
algorithms
,
changes
made
to
form
controls
as
part
of
these
algorithms
do
count
as
changes
caused
by
the
user
(and
thus,
e.g.
do
cause
The
clear
algorithm
for
The
clear
algorithm
for
The
clear
algorithm
for
The
remote
end
steps
are:
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
element
be
the
result
of
trying
to
get
a
known
connected
element
with
argument
element
id
.
If
the
element
is
an
Scroll
into
view
the
element
’s
container
.
If
element
’s
container
is
still
not
in
view
,
return
error
with
error
code
element
not
interactable
.
If
element
’s
container
is
obscured
by
another
element
,
return
error
with
error
code
element
click
intercepted
.
Matching
on
element
:
Let
parent
node
be
the
element
’s
container
.
Fire
a
mouseOver
event
at
parent
node
.
Fire
a
mouseMove
event
at
parent
node
.
Fire
a
mouseDown
event
at
parent
node
.
Run
the
focusing
steps
on
parent
node
.
If
element
is
not
disabled
:
Let
previous
selectedness
be
equal
to
element
selectedness
.
If
element
’s
container
has
the
Otherwise,
set
the
element
’s
selectedness
state
to
true.
If
previous
selectedness
is
false,
fire
a
Fire
a
mouseUp
event
at
parent
node
.
Fire
a
click
event
at
parent
node
.
Let
mouse
be
a
new
pointer
input
source
.
Let
click
point
be
the
element
’s
in-view
center
point
.
Let
pointer
move
action
be
an
action
object
with
the
mouse
’s
Set
a
property
Set
a
property
Set
a
property
Let
pointer
down
action
be
an
action
object
with
the
mouse
’s
Set
a
property
Let
pointer
up
action
be
an
action
object
with
the
mouse
’s
Set
a
property
Dispatch
a
pointerMove
action
with
arguments
mouse
’s
Dispatch
a
pointerDown
action
with
arguments
mouse
’s
Dispatch
a
pointerUp
action
with
arguments
mouse
’s
Remove
mouse
from
the
current
session
’s
input
state
table
.
Remove
mouse
from
the
list
of
active
input
sources
.
Wait
until
the
user
agent
event
loop
has
spun
enough
times
to
process
the
DOM
events
generated
by
the
previous
step.
Perform
implementation-defined
steps
to
allow
any
navigations
triggered
by
the
click
to
start.
It
is
not
always
clear
how
long
this
will
cause
the
algorithm
to
wait,
and
it
is
acknowledged
that
some
implementations
may
have
unavoidable
race
conditions.
The
intention
is
to
allow
a
new
attempt
to
navigate
to
begin
so
that
the
next
step
in
the
algorithm
is
meaningful.
It
is
possible
the
click
does
not
cause
an
attempt
to
navigate
,
in
which
case
the
implementation-defined
steps
can
return
immediately,
and
the
next
step
will
also
return
immediately.
Try
to
run
the
post-navigation
checks
.
To
clear
a
content
editable
element
:
If
element
’s
Run
the
focusing
steps
for
element
.
Set
element
’s
Run
the
unfocusing
steps
for
the
element
.
To
clear
a
resettable
element
:
Let
empty
be
the
result
of
the
first
matching
condition:
If
element
is
a
candidate
for
constraint
validation
it
satisfies
its
constraints
,
and
empty
is
true,
abort
these
substeps.
Invoke
the
focusing
steps
for
element
.
Invoke
the
clear
algorithm
for
element
.
Invoke
the
unfocusing
steps
for
the
element
.
The
remote
end
steps
for
Element
Clear
are:
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
and
return
its
value
if
it
is
an
error
.
Let
element
be
the
result
of
trying
to
get
a
known
connected
element
with
argument
element
id
.
If
element
is
not
editable
,
return
an
error
with
error
code
invalid
element
state
.
Scroll
into
view
the
element
.
Wait
in
an
implementation-specific
way
up
to
the
session
implicit
wait
timeout
for
element
to
become
interactable
.
If
element
is
not
interactable
,
return
error
with
error
code
element
not
interactable
.
Run
the
substeps
of
the
first
matching
statement:
Invoke
the
steps
to
clear
a
resettable
element
.
Invoke
the
steps
to
clear
a
content
editable
element
.
Return
error
with
error
code
invalid
element
state
.
The
Element
Send
Keys
command
scrolls
into
view
the
form
control
element
and
then
sends
the
provided
keys
to
the
element
.
In
case
the
element
is
not
keyboard-interactable
,
an
element
not
interactable
error
is
returned.
The
key
input
state
used
for
input
may
be
cleared
mid-way
through
“typing”
by
sending
the
null
key
,
which
is
U+E000
(NULL).
When
required
to
clear
the
modifier
key
state
with
an
argument
of
undo
actions
and
keyboard
a
remote
end
must
run
the
following
steps:
If
keyboard
is
not
a
key
input
source
return
error
with
error
code
invalid
argument
.
For
each
entry
key
in
the
lexically
sorted
keys
of
undo
actions
:
Let
action
be
the
value
of
undo
actions
equal
to
the
key
entry
key
.
If
action
is
not
an
action
object
of
Dispatch
a
keyUp
action
with
arguments
action
and
keyboard
’s
key
input
state
.
An
extended
grapheme
cluster
is
typeable
if
it
consists
of
a
single
unicode
code
point
and
the
code
is
not
undefined
.
The
shifted
state
for
keyboard
is
the
value
of
keyboard
’s
key
input
state
’s
In
order
to
dispatch
the
events
for
a
typeable
string
with
arguments
text
and
keyboard
,
a
remote
end
must
for
each
char
corresponding
to
an
indexed
property
in
text
:
If
char
is
a
shifted
character
and
the
shifted
state
of
keyboard
is
false,
create
a
new
action
object
with
keyboard
’s
If
char
is
not
a
shifted
character
and
the
shifted
state
of
keyboard
is
true,
create
a
new
action
object
with
keyboard
’s
Let
keydown
action
be
a
new
action
object
constructed
with
arguments
keyboard
’s
Set
the
Dispatch
a
keyDown
action
with
arguments
keydown
action
and
keyboard
’s
key
input
state
.
Let
keyup
action
be
a
copy
of
keydown
action
with
the
Dispatch
a
keyUp
action
with
arguments
keyup
action
and
keyboard
’s
key
input
state
.
When
required
to
dispatch
a
composition
event
with
arguments
type
and
cluster
,
the
remote
end
must
perform
implementation-specific
action
dispatch
steps
equivalent
to
sending
composition
events
in
accordance
with
the
requirements
of
[
UI-EVENTS
],
and
producing
the
following
event
with
the
specified
properties.
When
required
to
dispatch
actions
for
a
string
with
arguments
text
and
keyboard
,
a
remote
end
must
run
the
following
steps:
Let
clusters
be
an
array
created
by
breaking
text
into
extended
grapheme
clusters
.
Let
undo
actions
be
an
empty
dictionary.
Let
current
typeable
text
be
an
empty
string.
For
each
cluster
corresponding
to
an
indexed
property
in
clusters
run
the
substeps
of
the
first
matching
statement:
Dispatch
the
events
for
a
typeable
string
with
arguments
current
typeable
text
and
keyboard
.
Reset
current
typeable
text
to
an
empty
string.
Clear
the
modifier
key
state
with
arguments
being
undo
actions
and
keyboard
.
If
the
previous
step
results
in
an
error
,
return
that
error
.
Reset
undo
actions
to
be
an
empty
dictionary.
Dispatch
the
events
for
a
typeable
string
with
arguments
current
typeable
text
and
keyboard
.
Reset
current
typeable
text
to
an
empty
string.
Let
keydown
action
be
an
action
object
constructed
with
arguments
keyboard
’s
ID,
"
Set
the
Dispatch
a
keyDown
action
with
arguments
keydown
action
and
keyboard
’s
key
input
state
.
Add
an
entry
to
undo
actions
with
key
cluster
and
value
being
a
copy
of
keydown
action
with
the
Append
cluster
to
current
typeable
text
.
Dispatch
the
events
for
a
typeable
string
with
arguments
current
typeable
text
and
keyboard
.
Reset
current
typeable
text
to
an
empty
string.
Dispatch
a
Dispatch
a
Dispatch
a
Dispatch
the
events
for
a
typeable
string
with
arguments
current
typeable
text
and
keyboard
.
Clear
the
modifier
key
state
with
arguments
undo
actions
and
keyboard
.
If
an
error
is
returned,
return
that
error
The
remote
end
steps
for
Element
Send
Keys
are:
Let
text
be
the
result
of
getting
a
property
called
"
If
text
is
not
a
String
,
return
an
error
with
error
code
invalid
argument
.
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
,
and
return
its
value
if
it
is
an
error
.
Let
element
be
the
result
of
trying
to
get
a
known
connected
element
with
url
variable
element
id
.
Let
file
be
true
if
element
is
If
file
is
false
or
the
current
session
’s
strict
file
interactability
,
is
true
run
the
following
substeps:
Scroll
into
view
the
element
.
Wait
in
an
implementation-specific
way
up
to
the
session
implicit
wait
timeout
for
element
to
become
keyboard-interactable
.
If
element
is
not
keyboard-interactable
,
return
error
with
error
code
element
not
interactable
.
If
element
is
not
the
active
element
run
the
focusing
steps
for
the
element
.
Run
the
substeps
of
the
first
matching
condition:
Let
files
be
the
result
of
splitting
text
on
the
newline
(
If
files
is
of
0
length,
return
an
error
with
error
code
invalid
argument
.
Let
multiple
equal
the
result
of
calling
if
multiple
is
Verify
that
each
file
given
by
the
user
exists.
If
any
do
not,
return
error
with
error
code
invalid
argument
.
Complete
implementation
specific
steps
equivalent
to
setting
the
selected
files
on
the
Fire
these
events
in
order
on
element
:
If
element
does
not
have
an
own
property
named
If
element
is
not
mutable
return
an
error
with
error
code
element
not
interactable
.
Set
a
property
If
element
is
suffering
from
bad
input
return
an
error
with
error
code
invalid
argument
.
Let
current
text
length
be
the
JavaScript
string’s
length
of
element
’s
API
value
.
Set
the
text
insertion
caret
using
set
selection
range
using
current
text
length
for
both
the
Let
keyboard
be
a
new
key
input
source
.
Dispatch
actions
for
a
string
with
arguments
text
and
keyboard
.
Remove
keyboard
from
the
current
session
’s
input
state
table
Remove
keyboard
from
the
list
of
active
input
sources
.
input
element
whose
readOnly
attribute
is
set.
12.1
Interactability
body
element
,
or
is
the
document
element
.
sequence
returned
by
calling
getClientRects
on
element
.
DOMRect
sequence
returned
by
calling
getClientRects
.
DOMRect
12.2
Retrieval
,
DOMException
SyntaxError
,
,
or
other
error
occurs
during
the
execution
of
the
element
location
strategy
,
return
error
invalid
selector
.
XPathException
12.2.1
Locator
strategies
State
Keyword
CSS
selector
"
css
selector
"
Link
text
selector
"
link
text
"
Partial
link
text
selector
"
partial
link
text
"
Tag
name
"
tag
name
"
XPath
selector
"
xpath
"
12.2.1.1
CSS
selectors
12.2.1.2
Link
text
a
elements
,
with
the
context
object
equal
to
the
start
node
.
If
this
throws
an
exception,
return
error
with
error
code
unknown
error
.
12.2.1.3
Partial
link
text
a
elements
with
rendered
text
that
contains
the
selector
expression.
a
elements
,
with
the
context
object
equal
to
the
start
node
.
If
this
throws
an
exception,
return
error
with
error
code
unknown
error
.
12.2.1.4
Tag
name
getElementsByTagName
with
the
argument
selector
,
with
the
context
object
equal
to
the
start
node
.
12.2.1.5
XPath
,
with
arguments
selector
,
start
node
,
evaluate
null
,
ORDERED_NODE_SNAPSHOT_TYPE
,
and
null
.
snapshotLength
"
from
evaluateResult
.
If
this
throws
an
XPathException
return
error
with
error
code
invalid
selector
,
otherwise
if
this
throws
any
other
exception
return
error
with
error
code
unknown
error
.
snapshotItem
with
argument
index
,
with
the
context
object
equal
to
evaluateResult
.
12.2.2
Find
Element
HTTP
Method
URI
Template
POST
/session/{
session
id
}/element
using
".
value
".
null
,
return
error
with
error
code
no
such
element
.
12.2.3
Find
Elements
HTTP
Method
URI
Template
POST
/session/{
session
id
}/elements
using
".
value
".
null
,
return
error
with
error
code
no
such
element
.
12.2.4
Find
Element
From
Element
HTTP
Method
URI
Template
POST
/session/{
session
id
}/element/{
element
id
}/element
using
".
value
".
12.2.5
Find
Elements
From
Element
HTTP
Method
URI
Template
POST
/session/{
session
id
}/element/{
element
id
}/elements
using
".
value
".
12.2.6
Get
Active
Element
HTTP
Method
URI
Template
GET
/session/{
session
id
}/element/active
12.3
State
option
element
in
a
valid
element
context
optgroup
element
in
a
valid
element
context
datalist
element
reached
by
traversing
the
tree
in
reverse
order
from
element
,
or
undefined
if
the
root
of
the
tree
is
reached.
select
element
reached
by
traversing
the
tree
in
reverse
order
from
element
,
or
undefined
if
the
root
of
the
tree
is
reached.
option
element
in
an
invalid
element
context
12.3.1
Is
Element
Selected
HTTP
Method
URI
Template
GET
/session/{
session
id
}/element/{
element
id
}/selected
input
elements
of
the
Checkbox
-
and
Radio
Button
states,
or
on
option
elements
.
input
element
with
a
type
attribute
in
the
Checkbox
-
or
Radio
Button
state
option
element
12.3.2
Get
Element
Attribute
HTTP
Method
URI
Template
GET
/session/{
session
id
}/element/{
element
id
}/attribute/{
name
}
true
"
(string)
if
the
element
has
the
attribute
,
otherwise
null
.
12.3.3
Get
Element
Property
HTTP
Method
URI
Template
GET
/session/{
session
id
}/element/{
element
id
}/property/{
name
}
null
.
12.3.4
Get
Element
CSS
Value
HTTP
Method
URI
Template
GET
/session/{
session
id
}/element/{
element
id
}/css/{
property
name
}
xml
"
12.3.5
Get
Element
Text
HTTP
Method
URI
Template
GET
/session/{
session
id
}/element/{
element
id
}/text
WSpace=Y
"
or
"
WS
".
[
UAX44
]
bot.dom.getVisibleText
,
null
,
element
).
12.3.6
Get
Element
Tag
Name
HTTP
Method
URI
Template
GET
/session/{
session
id
}/element/{
element
id
}/name
12.3.7
Get
Element
Rect
HTTP
Method
URI
Template
GET
/session/{
session
id
}/element/{
element
id
}/rect
x
"
y
"
width
"
height
"
12.3.8
Is
Element
Enabled
HTTP
Method
URI
Template
GET
/session/{
session
id
}/element/{
element
id
}/enabled
xml
".
12.4
Interaction
input
events
to
fire).
When
the
clear
algorithm
is
invoked
for
an
element
that
does
not
define
its
own
clear
algorithm
,
its
reset
algorithm
must
be
invoked
instead.
input
elements
is
to
set
the
dirty
value
flag
and
dirty
checkedness
flag
back
to
false,
set
the
value
of
the
element
to
an
empty
string,
set
the
checkedness
of
the
element
to
true
if
the
element
has
a
checked
content
attribute
and
false
if
it
does
not,
empty
the
list
of
selected
files
,
and
then
invoke
the
value
sanitization
algorithm
iff
the
type
attribute’s
current
state
defines
one.
textarea
elements
is
to
set
the
dirty
value
flag
back
to
false,
and
set
the
raw
value
of
element
to
an
empty
string.
output
elements
is
set
the
element’s
value
mode
flag
to
default
and
then
to
set
the
element’s
textContent
IDL
attribute
to
an
empty
string
(thus
clearing
the
element’s
child
nodes).
12.4.1
Element
Click
HTTP
Method
URI
Template
POST
/session/{
session
id
}/element/{
element
id
}/click
input
element
in
the
file
upload
state
return
error
with
error
code
invalid
argument
.
option
element
multiple
attribute
,
toggle
the
element
’s
selectedness
state
by
setting
it
to
the
opposite
value
of
its
current
selectedness
.
change
event
at
parent
node
.
id
,
"
pointer
",
and
"
pointerMove
"
as
arguments.
x
to
0
on
pointer
move
action
.
y
to
0
on
pointer
move
action
.
origin
to
element
on
pointer
move
action
.
id
,
"
pointer
",
and
"
pointerDown
"
as
arguments.
button
to
0
on
pointer
down
action
.
id
,
"
mouse
",
and
"
pointerUp
"
as
arguments.
button
to
0
on
pointer
up
action
.
input
id
,
pointer
move
action
,
mouse
’s
input
source
state
,
and
0
.
input
id
,
pointer
down
action
,
mouse
’s
input
source
state
,
and
0
.
input
id
,
pointer
up
action
,
mouse
’s
input
source
state
,
and
0
.
12.4.2
Element
Clear
HTTP
Method
URI
Template
POST
/session/{
session
id
}/element/{
element
id
}/clear
innerHTML
IDL
attribute
is
an
empty
string
do
nothing
and
return.
innerHTML
IDL
attribute
to
an
empty
string.
input
element
whose
type
attribute
is
in
the
File
Upload
state
12.4.3
Element
Send
Keys
HTTP
Method
URI
Template
POST
/session/{
session
id
}/element/{
element
id
}/value
type
"
key
"
and
subtype
"
keyUp
",
return
error
with
error
code
invalid
argument
.
shift
property.
id
,
"
key
",
and
"
keyDown
",
and
set
its
value
property
to
U+E008
("left
shift").
Dispatch
a
keyDown
action
with
this
action
object
and
keyboard
’s
key
input
state
.
id
,
"
key"
",
and
"
keyUp
",
and
set
its
value
property
to
U+E008
("left
shift").
Dispatch
a
keyUp
action
with
this
action
object
and
keyboard
’s
key
input
state
.
id
,
"
key
",
and
"
keyDown
".
value
property
of
keydown
action
to
char
.
subtype
property
changed
to
"
keyUp
".
composition
event
with
properties:
Attribute
Value
type
type
data
cluster
key
",
and
"
keyDown
".
value
property
of
keydown
action
to
cluster
.
subtype
modified
to
"
keyUp
".
composition
event
with
arguments
"
compositionstart
"
and
undefined
.
composition
event
with
arguments
"
compositionupdate
"
and
cluster
.
composition
event
with
arguments
"
compositionend
"
and
cluster
.
text
"
from
the
parameters
argument.
input
element
in
the
file
upload
state
,
or
false
otherwise.
\n
)
character.
hasAttribute
("multiple")
on
element
.
false
and
the
length
of
files
is
not
equal
to
1,
return
an
error
with
error
code
invalid
argument
.
input
.
If
multiple
is
true
files
are
be
appended
to
element
’s
selected
files
.
input
element
in
the
color
state
being
presented
as
a
colorwheel):
value
return
an
error
with
error
code
element
not
interactable
value
to
text
on
element
.
start
and
end
parameters.
HTTP Method | URI Template |
---|---|
GET | /session/{ session id }/source |
The Get Page Source command returns a string serialization of the DOM of the current browsing context active document .
The remote end steps are:
If the current browsing context is no longer open , return error with error code no such window .
Handle any user prompts and return its value if it is an error .
Let
source
be
the
result
of
invoking
the
fragment
serializing
algorithm
on
a
fictional
node
whose
only
child
is
the
document
element
providing
true
for
the
require
well-formed
flag.
If
this
causes
an
exception
to
be
thrown,
let
source
be
null
.
Let
source
be
the
result
of
serializing
to
string
the
current
browsing
context
active
document
,
if
source
is
null
.
Return success with data source .
A collection is an Object that implements the Iterable interface, and whose:
toString
own
property
is
"
Arguments
"
FileList
HTMLAllCollection
HTMLCollection
HTMLFormControlsCollection
HTMLOptionsCollection
NodeList
When required to JSON deserialize with argument value and optional argument seen , a remote end must run the following steps:
If seen is not provided, let seen be an empty List .
Jump to the first appropriate step below:
Matching on value :
null
Return success with data value .
Return the deserialized web element of value .
Return the result of running the clone an object algorithm with arguments value and seen , and the JSON deserialize algorithm as the clone algorithm.
To perform a JSON clone return the result of calling the internal JSON clone algorithm with arguments value and an empty List .
When required to run the internal JSON clone algorithm with arguments value and seen , a remote end must return the value of the first matching statement, matching on value :
null
Success with data value .
Let result list be an empty list.
For each item of value , add the result of trying to clone an object with arguments item and seen and the internal JSON clone algorithm as the clone algorithm to result list .
Return success with result list .
If the element is stale , return error with error code stale element reference .
Otherwise return success with the JSON serialization of value .
WindowProxy
object
If
the
associated
browsing
context
of
the
WindowProxy
object
in
value
has
been
discarded
,
return
error
with
error
code
stale
element
reference
.
Otherwise return success with the JSON serialization of value .
toJSON
"
that
is
a
Function
toJSON
).
If value is in seen , return error with error code javascript error .
Append value to seen .
Let result be the value of running the clone an object algorithm with arguments value and seen , and the internal JSON clone algorithm as the clone algorithm .
Remove the last element of seen .
Return result .
To clone an object , taking the arguments value , seen , and clone algorithm :
Let result be the value of the first matching statement, matching on value :
A
new
Array
which
length
property
is
equal
to
the
result
of
getting
the
property
length
of
value
.
A new Object .
For each enumerable own property in value , run the following substeps:
Let name be the name of the property.
Let source property value be the result of getting a property named name from value . If doing so causes script to be run and that script throws an error, return error with error code javascript error .
Let cloned property result be the result of calling the clone algorithm with arguments source property value and seen .
If cloned property result is a success , set a property of result with name name and value equal to cloned property result ’s data.
Otherwise, return cloned property result .
When required to extract the script arguments from a request with argument parameters the implementation must:
Let
script
be
the
result
of
getting
a
property
named
script
from
the
parameters
.
If script is not a String , return error with error code invalid argument .
Let
args
be
the
result
of
getting
a
property
named
args
from
the
parameters
.
If args is not an Array return error with error code invalid argument .
Let arguments be the result of calling the JSON deserialize algorithm with arguments args .
Return success with data script and arguments .
The rules to execute a function body are as follows. The algorithm returns an ECMASCript completion record .
If
at
any
point
during
the
algorithm
a
user
prompt
appears,
abort
all
subsequent
substeps
of
this
algorithm,
and
return
Completion
{
[[Type]]:
normal
,
[[Value]]:
null
,
[[Target]]:
empty
}.
Let window be the associated window of the current browsing context ’s active document .
Let environment settings be the environment settings object for window .
If
body
is
not
parsable
as
a
FunctionBody
or
if
parsing
detects
an
early
error
,
return
Completion
{
[[Type]]:
normal
,
[[Value]]:
null
,
[[Target]]:
empty
}.
If body begins with a directive prologue that contains a use strict directive then let strict be true, otherwise let strict be false.
Prepare to run a script with environment settings .
Prepare to run a callback with environment settings .
Let function be the result of calling FunctionCreate , with arguments:
Let completion be Call ( function , window , parameters ).
Clean up after running a callback with environment settings .
Clean up after running a script with environment settings .
Return completion .
The above algorithm is not associated with any particular element, and is therefore not subject to the document CSP directives .
HTTP Method | URI Template |
---|---|
POST | /session/{ session id }/execute/sync |
The remote end steps are:
Let body and arguments be the result of trying to extract the script arguments from a request with argument parameters .
If the current browsing context is no longer open , return error with error code no such window .
Handle any user prompts , and return its value if it is an error .
Let promise be a new Promise .
Run the following substeps in parallel :
Let scriptPromise be the result of promise-calling execute a function body , with arguments body and arguments .
Upon fulfillment of scriptPromise with value v , resolve promise with value v .
Upon rejection of scriptPromise with value r , reject promise with value r .
If promise is still pending and the session script timeout is reached, return error with error code script timeout .
Upon fulfillment of promise with value v , let result be a JSON clone of v , and return success with data result .
Upon rejection of promise with reason r , let result be a JSON clone of r , and return error with error code javascript error and data result .
HTTP Method | URI Template |
---|---|
POST | /session/{ session id }/execute/async |
The Execute Async Script command causes JavaScript to execute as an anonymous function. An additional value is provided as the final argument to the function. This is a function that may be invoked to signal the completion of the asynchronous operation. The first argument provided to the function will be serialized to JSON and returned by Execute Async Script .
The remote end steps are:
Let body and arguments by the result of trying to extract the script arguments from a request with argument parameters .
If the current browsing context is no longer open , return error with error code no such window .
Handle any user prompts , and return its value if it is an error .
Let promise be a new Promise .
Run the following substeps in parallel :
Let resolvingFunctions be CreateResolvingFunctions ( promise ).
Append
resolvingFunctions
.[[Resolve]]
to
arguments
.
Let result be the result of calling execute a function body , with arguments body and arguments .
If
scriptResult
.[[Type]]
is
not
normal
,
then
reject
promise
with
value
scriptResult
.[[Value]],
and
abort
these
steps.
Prior revisions of this specification did not recognize the return value of the provided script. In order to preserve legacy behavior, the return value only influences the command if it is a "thenable" object or if determining this produces an exception.
If Type ( scriptResult .[[Value]]) is not Object , then abort these steps.
Let then be Get ( scriptResult .[[Value]], "then").
If
then
.[[Type]]
is
not
normal
,
then
reject
promise
with
value
then
.[[Value]],
and
abort
these
steps.
If
IsCallable
(
then
.[[Type]])
is
false
,
then
abort
these
steps.
Let scriptPromise be PromiseResolve ( Promise , scriptResult .[[Value]]).
Upon fulfillment of scriptPromise with value v , resolve promise with value v .
Upon rejection of scriptPromise with value r , reject promise with value r .
If promise is still pending and session script timeout milliseconds is reached, return error with error code script timeout .
Upon fulfillment of promise with value v , let result be a JSON clone of v , and return success with data result .
Upon rejection of promise with reason r , let result be a JSON clone of r , and return error with error code javascript error and data result .
The
Actions
API
provides
a
low-level
interface
for
providing
virtualised
device
input
to
the
web
browser.
Conceptually,
the
Actions
commands
divide
time
into
a
series
of
ticks
.
The
local
end
sends
a
series
of
actions
which
correspond
to
the
change
in
state,
if
any,
of
each
input
device
during
each
tick
.
For
example,
pressing
a
key
is
represented
by
an
action
sequence
consisting
of
a
single
key
input
device
and
two
ticks
,
the
first
containing
a
keyDown
action,
and
the
second
a
keyUp
action,
whereas
a
pinch-zoom
input
is
represented
by
an
action
sequence
consisting
of
three
ticks
and
two
pointer
input
devices
of
type
touch,
each
performing
a
sequence
of
actions
pointerDown
,
followed
by
pointerMove
,
and
then
pointerUp
.
The
objects
and
properties
defined
in
this
section
are
spec-internal
constructs
and
do
not
correspond
to
ECMAScript
objects.
For
convenience
the
same
terminology
is
used
for
their
manipulation.
An
input
source
is
a
virtual
device
providing
input
events.
Each
input
source
has
an
associated
input
id
,
which
is
a
string
that
identifies
the
particular
device,
and
a
source
type
which
determines
the
kind
of
input
the
device
can
provide.
As
with
real
devices,
virtual
devices
are
stateful;
this
state
is
recorded
in
an
input
source
state
object
associated
with
each
input
source
.
A
null
input
source
is
an
input
source
that
is
not
associated
with
a
specific
physical
device.
A
null
input
source
supports
the
following
actions:
A
key
input
source
is
an
input
source
that
is
associated
with
a
keyboard-type
device.
A
key
input
source
supports
the
same
pause
action
as
a
null
input
source
plus
the
following
actions:
A
pointer
input
source
is
an
input
source
that
is
associated
with
a
pointer-type
input
device.
Such
an
input
source
has
an
associated
pointer
type
specifying
exactly
which
kind
of
pointing
device
it
is
associated
with.
A
pointer
input
source
supports
the
same
pause
action
as
a
null
input
source
plus
the
following
actions:
Each
session
maintains
a
list
of
active
input
sources
.
This
list
is
initially
empty.
When
an
input
source
is
added
to
the
list
of
active
input
sources
,
a
corresponding
entry
is
made
in
the
input
state
table
where
the
key
is
the
input
source
’s
Input
source
state
is
used
as
a
generic
term
to
describe
the
state
associated
with
each
input
source
.
The
corresponding
input
source
state
type
for
a
label
action
type
is
given
by
the
following
table:
A
null
input
source
’s
input
source
state
is
a
null
input
state
.
This
is
always
an
empty
object.
A
key
input
source
’s
input
source
state
is
a
key
input
state
object.
This
is
an
object
with
a
property,
When
required
to
create
a
new
key
input
state
object
,
an
implementation
must
return
a
key
input
state
object
with
the
A
pointer
input
source
’s
input
source
state
is
a
pointer
input
state
object.
This
consists
of
a
When
required
to
create
a
new
pointer
input
state
object
with
arguments
subtype
an
implementation
must
return
a
pointer
input
state
object
with
Each
session
has
an
associated
input
state
table
.
This
is
a
map
between
input
id
and
the
input
source
state
for
that
input
source
,
with
one
entry
for
each
item
in
the
list
of
active
input
sources
.
Each
session
also
has
an
associated
input
cancel
list
,
which
is
a
list
of
actions.
This
list
is
used
to
manage
dispatching
events
when
resetting
the
state
of
the
input
source
s.
For
simplicity
the
algorithms
described
here
only
append
actions
to
the
list
and
rely
on
the
fact
that
the
reset
operations
are
idempotent.
The
calculated
global
key
state
is
the
aggregated
key
state
from
all
key
input
state
objects.
It
can
be
calculated
this
way:
Let
pressed
be
a
new
Set.
Let
alt
,
ctrl
,
meta
,
and
shift
be
the
Boolean
For
enumerable
own
property
in
the
input
state
table
:
Let
source
be
the
value
of
the
property.
If
source
is
not
a
key
input
state
,
continue
to
the
first
step
of
this
loop.
Let
key
state
pressed
be
the
result
of
getting
a
property
named
Add
all
strings
from
key
state
pressed
to
pressed
.
Let
state
be
a
new
JSON
Object
.
Set
a
property
on
state
with
name
pressed
and
value
pressed
.
Set
a
property
on
state
with
name
alt
and
value
alt
.
Set
a
property
on
state
with
name
ctrl
and
value
ctrl
.
Set
a
property
on
state
with
name
meta
and
value
meta
.
Set
a
property
on
state
with
name
shift
and
value
shift
.
Return
state
.
A
tick
is
the
basic
unit
of
time
over
which
actions
can
be
performed.
During
a
tick
,
each
input
source
has
an
assigned
action
—
possibly
a
noop
pause
action
—
which
may
result
in
changes
to
the
user
agent
internal
state
and
eventually
cause
DOM
events
to
be
fired
at
the
page.
The
next
tick
begins
after
the
user
agent
has
had
a
chance
to
process
all
DOM
events
generated
in
the
current
tick
.
Waiting
asynchronously
means
waiting
for
something
to
occur
whilst
allowing
the
browser
to
continue
processing
the
event
loop
.
At
the
lowest
level,
the
behavior
of
actions
is
intended
to
mimic
the
remote
end
’s
behavior
with
an
actual
input
device
as
closely
as
possible,
and
the
implementation
strategy
may
involve
e.g.
injecting
synthesized
events
into
a
browser
event
loop.
Therefore
the
steps
to
dispatch
an
action
will
inevitably
end
up
in
implementation-specific
territory.
However
there
are
certain
content
observable
effects
that
must
be
consistent
across
implementations.
To
accommodate
this,
the
specification
requires
that
remote
ends
perform
implementation-specific
action
dispatch
steps
,
along
with
a
list
of
events
and
their
properties.
This
list
is
not
comprehensive;
in
particular
the
default
action
of
the
input
source
may
cause
additional
events
to
be
generated
depending
on
the
implementation
and
the
state
of
the
browser
(e.g.
input
events
relating
to
key
actions
when
the
focus
is
on
an
editable
element
,
scroll
events,
etc.).
The
algorithm
for
extracting
an
action
sequence
from
a
request
takes
the
JSON
Object
representing
an
action
sequence,
validates
the
input,
and
returns
a
data
structure
that
is
the
transpose
of
the
input
JSON,
such
that
the
actions
to
be
performed
in
a
single
tick
are
grouped
together.
When
required
to
extract
an
action
sequence
with
argument
parameters
,
a
remote
end
must
run
the
following
steps:
Let
actions
be
the
result
of
getting
a
property
from
parameters
named
If
actions
is
undefined
or
is
not
an
Array
,
return
error
with
error
code
invalid
argument
.
Let
actions
by
tick
be
an
empty
List
.
For
each
value
action
sequence
corresponding
to
an
indexed
property
in
actions
:
Let
input
source
actions
be
the
result
of
trying
to
process
an
input
source
action
sequence
with
argument
action
sequence
.
For
each
action
in
input
source
actions
:
Return
success
with
data
actions
by
tick
.
When
required
to
process
an
input
source
action
sequence
,
with
argument
action
sequence
,
a
remote
end
must
run
the
following
steps:
Let
type
be
the
result
of
getting
a
property
named
If
type
is
not
"
Let
id
be
the
result
of
getting
the
property
If
id
is
undefined
or
is
not
a
String
,
return
error
with
error
code
invalid
argument
.
If
type
is
equal
to
"
Let
source
be
the
input
source
in
the
list
of
active
input
sources
where
that
input
source
’s
input
id
is
equal
to
id
,
or
undefined
if
there
is
no
matching
input
source
.
If
source
is
undefined
:
Add
source
to
the
current
session
’s
list
of
active
input
sources
.
Add
source
’s
input
source
state
to
the
current
session
’s
input
state
table
,
keyed
on
source
’s
input
id
.
If
source
’s
source
type
is
not
equal
to
type
return
an
error
with
error
code
invalid
argument
.
If
parameters
is
not
undefined
,
then
if
its
Let
action
items
be
the
result
of
getting
a
property
named
If
action
items
is
not
an
Array
,
return
error
with
error
code
invalid
argument
.
Let
actions
be
a
new
list.
For
each
action
item
in
action
items
:
If
action
item
is
not
an
Object
return
error
with
error
code
invalid
argument
.
If
type
is
"
Otherwise,
if
type
is
"
Otherwise,
if
type
is
"
Append
action
to
actions
.
Return
success
with
data
actions
.
The
default
pointer
parameters
consist
of
an
object
with
property
When
required
to
process
pointer
parameters
with
argument
parameters
data
,
a
remote
end
must
perform
the
following
steps:
Let
parameters
be
the
default
pointer
parameters
.
If
parameters
data
is
undefined
,
return
success
with
data
parameters
.
If
parameters
data
is
not
an
Object
,
return
error
with
error
code
invalid
argument
.
Let
pointer
type
be
the
result
of
getting
a
property
named
If
pointer
type
is
not
undefined
:
If
pointer
type
does
not
have
one
of
the
values
"
Set
the
Return
success
with
data
parameters
.
An
action
object
constructed
with
arguments
id
,
type
,
and
subtype
is
an
object
with
property
When
required
to
process
a
null
action
with
arguments
id
and
action
item
,
a
remote
end
must
perform
the
following
steps:
Let
subtype
be
the
result
of
getting
a
property
named
If
subtype
is
not
"
Let
action
be
an
action
object
constructed
with
arguments
id
,
Let
result
be
the
result
of
trying
to
process
a
pause
action
with
arguments
action
item
and
action
.
Return
result
.
When
required
to
process
a
key
action
with
arguments
id
and
action
item
,
a
remote
end
must
perform
the
following
steps:
Let
subtype
be
the
result
of
getting
a
property
named
If
subtype
is
not
one
of
the
values
"
Let
action
be
an
action
object
constructed
with
arguments
id
,
"
If
subtype
is
"
Let
key
be
the
result
of
getting
a
property
named
If
key
is
not
a
String
containing
a
single
unicode
code
point
or
grapheme
cluster?
return
error
with
error
code
invalid
argument
.
Set
the
Return
success
with
data
action
.
When
required
to
process
a
pointer
action
with
arguments
id
,
parameters
,
and
action
item
,
a
remote
end
must
perform
the
following
steps:
Let
subtype
be
the
result
of
getting
a
property
named
If
subtype
is
not
one
of
the
values
"
Let
action
be
an
action
object
constructed
with
arguments
id
,
"
If
subtype
is
"
Set
the
If
subtype
is
"
If
subtype
is
"
If
subtype
is
"
Return
success
with
data
action
.
When
required
to
process
a
pause
action
with
arguments
action
item
,
and
action
,
a
remote
end
must
run
the
following
steps:
Let
duration
be
the
result
of
getting
the
property
"
If
duration
is
not
undefined
and
duration
is
not
an
Integer
greater
than
or
equal
to
0,
return
error
with
error
code
invalid
argument
.
Set
the
Return
success
with
data
action
.
When
required
to
process
a
pointer
up
or
pointer
down
action
with
arguments
action
item
,
and
action
,
a
remote
end
must
run
the
following
steps:
Let
button
be
the
result
of
getting
the
property
If
button
is
not
an
Integer
greater
than
or
equal
to
0
return
error
with
error
code
invalid
argument
.
Set
the
Return
success
with
data
When
required
to
process
a
pointer
move
action
with
arguments
action
item
,
and
action
,
a
remote
end
must
run
the
following
steps:
Let
duration
be
the
result
of
getting
the
property
If
duration
is
not
undefined
and
duration
is
not
an
Integer
greater
than
or
equal
to
0,
return
error
with
error
code
invalid
argument
.
Set
the
Let
origin
be
the
result
of
getting
the
property
If
origin
is
undefined
let
origin
equal
"
If
origin
is
not
equal
to
"
Set
the
Let
x
be
the
result
of
getting
the
property
If
x
is
not
undefined
and
is
not
an
Integer
,
return
error
with
error
code
invalid
argument
.
Set
the
Let
y
be
the
result
of
getting
the
property
If
y
is
not
undefined
and
is
not
an
Integer
,
return
error
with
error
code
invalid
argument
.
Set
the
Return
success
with
data
The
algorithm
to
dispatch
actions
takes
a
list
of
actions
grouped
by
tick
,
and
then
causes
each
action
to
be
run
at
the
appropriate
point
in
the
sequence.
When
asked
to
dispatch
actions
with
argument
actions
by
tick
,
a
remote
end
must
run
the
following
steps:
For
each
item
tick
actions
in
actions
by
tick
:
Let
tick
duration
be
the
result
of
computing
the
tick
duration
with
argument
tick
actions
.
Dispatch
tick
actions
with
arguments
tick
actions
and
tick
duration
.
If
this
results
in
an
error
return
that
error.
Wait
until
the
following
conditions
are
all
met:
There
are
no
pending
asynchronous
waits
arising
from
the
last
invocation
of
the
dispatch
tick
actions
steps.
The
user
agent
event
loop
has
spun
enough
times
to
process
the
DOM
events
generated
by
the
last
invocation
of
the
dispatch
tick
actions
steps.
At
least
tick
duration
milliseconds
have
passed.
Return
success
with
data
When
required
to
compute
the
tick
duration
with
argument
tick
actions
,
a
remote
end
must
take
the
following
steps:
Let
max
duration
be
0.
For
each
action
object
in
tick
actions
:
let
duration
be
undefined
.
If
action
object
has
If
duration
is
not
undefined
,
and
duration
is
greater
than
max
duration
,
let
max
duration
be
equal
to
duration.
Return
max
duration
.
When
required
to
dispatch
tick
actions
with
arguments
tick
actions
and
tick
duration
,
a
remote
end
must
run
the
following
steps:
For
each
action
object
in
tick
actions
:
Let
source
id
be
equal
to
the
value
of
action
object
’s
Let
source
type
be
equal
to
the
value
of
action
object
’s
If
the
current
session
’s
input
state
table
doesn’t
have
a
property
corresponding
to
source
id
,
then
let
the
property
corresponding
to
source
id
be
a
new
object
of
the
corresponding
input
source
state
type
for
source
type
.
Let
device
state
be
the
input
source
state
corresponding
to
source
id
in
the
current
session
’s
input
state
table
.
Let
algorithm
be
the
value
of
the
column
dispatch
action
algorithm
from
the
following
table
of
dispatch
action
algorithms
that
is
equal
to
the
source
type
and
the
action
object
’s
When
required
to
dispatch
a
pause
action
with
arguments
source
id
,
action
object
,
input
state
and
tick
duration
a
remote
end
must
run
the
following
steps:
The
normalised
key
value
for
a
raw
key
key
is,
if
key
appears
in
the
table
below,
the
string
value
in
the
second
column
on
the
row
containing
key
’s
unicode
code
point
in
the
first
column,
otherwise
it
is
key
.
The
code
for
key
is
the
value
in
the
last
column
of
the
following
table
on
the
row
with
key
in
either
the
first
or
second
column,
if
any
such
row
exists,
otherwise
it
is
undefined
.
A
shifted
character
is
one
that
appears
in
the
second
column
of
the
following
table.
The
key
location
for
key
is
the
value
in
the
last
column
in
the
table
below
on
the
row
with
key
appears
in
the
first
column,
if
such
a
row
exists,
otherwise
it
is
When
required
to
dispatch
a
keyDown
action
with
arguments
source
id
,
action
object
,
input
state
and
tick
duration
a
remote
end
must
run
the
following
steps:
Let
raw
key
be
equal
to
the
action
object
’s
Let
key
be
equal
to
the
normalised
key
value
for
raw
key
.
If
the
input
state
’s
Let
code
be
the
code
for
raw
key
.
Let
location
be
the
key
location
for
raw
key
.
Let
charCode
,
keyCode
and
which
be
the
implementation-specific
values
of
the
If
key
is
If
key
is
If
key
is
If
key
is
Add
key
to
the
set
corresponding
to
input
state
’s
Append
a
copy
of
action
object
with
the
subtype
property
changed
to
keyUp
to
current
session
’s
input
cancel
list
.
Perform
implementation-specific
action
dispatch
steps
equivalent
to
pressing
a
key
on
the
keyboard
in
accordance
with
the
requirements
of
[
UI-EVENTS
],
and
producing
the
following
events,
as
appropriate,
with
the
specified
properties.
This
will
always
produce
events
including
at
least
a
When
required
to
dispatch
a
keyUp
action
with
arguments
source
id
,
action
object
,
input
state
and
tick
duration
a
remote
end
must
run
the
following
steps:
Let
raw
key
be
equal
to
action
object
’s
Let
key
be
equal
to
the
normalised
key
value
for
raw
key
.
If
the
input
state
’s
Let
code
be
the
code
for
raw
key
.
Let
location
be
the
key
location
for
raw
key
.
Let
charCode
,
keyCode
and
which
be
the
implementation-specific
values
of
the
If
key
is
If
key
is
If
key
is
If
key
is
Remove
key
from
the
set
corresponding
to
input
state
’s
Perform
implementation-specific
action
dispatch
steps
equivalent
to
releasing
a
key
on
the
keyboard
in
accordance
with
the
requirements
of
[
UI-EVENTS
],
and
producing
at
least
the
following
events
with
the
specified
properties:
When
required
to
dispatch
a
pointerDown
action
with
arguments
source
id
,
action
object
,
input
state
and
tick
duration
a
remote
end
must
run
the
following
steps:
Let
pointerType
be
equal
to
action
object
’s
Let
button
be
equal
to
action
object
’s
If
the
input
state
’s
Let
x
be
equal
to
input
state
’s
Let
y
be
equal
to
input
state
’s
Add
button
to
the
set
corresponding
to
input
state
’s
Append
a
copy
of
action
object
with
the
subtype
property
changed
to
pointerUp
to
the
current
session
’s
input
cancel
list
.
Perform
implementation-specific
action
dispatch
steps
equivalent
to
pressing
the
button
numbered
button
on
the
pointer
with
ID
source
id
,
having
type
pointerType
at
viewport
x
coordinate
x
,
viewport
y
coordinate
y
,
with
buttons
buttons
depressed
in
accordance
with
the
requirements
of
[
UI-EVENTS
]
and
[
POINTER-EVENTS
].
The
generated
events
must
set
When
required
to
dispatch
a
pointerUp
action
with
arguments
source
id
,
action
object
,
input
state
and
tick
duration
a
remote
end
must
run
the
following
steps:
Let
pointerType
be
equal
to
action
object
’s
Let
button
be
equal
to
action
object
’s
If
the
input
state
’s
Let
x
be
equal
to
input
state
’s
Let
y
be
equal
to
input
state
’s
Remove
button
from
the
set
corresponding
to
input
state
’s
Perform
implementation-specific
action
dispatch
steps
equivalent
to
releasing
the
button
numbered
button
on
the
pointer
of
ID
source
id
having
type
pointerType
at
viewport
x
coordinate
x
,
viewport
y
coordinate
y
,
with
buttons
buttons
depressed,
in
accordance
with
the
requirements
of
[
UI-EVENTS
]
and
[
POINTER-EVENTS
].
The
generated
events
must
set
When
required
to
dispatch
a
pointerMove
action
with
arguments
source
id
,
action
object
,
input
state
and
tick
duration
a
remote
end
must
run
the
following
steps:
Let
x
offset
be
equal
to
the
Let
y
offset
be
equal
to
the
Let
start
x
be
equal
to
the
Let
start
y
be
equal
to
the
Let
origin
be
equal
to
the
Run
the
substeps
of
the
first
matching
value
of
origin
:
Let
x
equal
x
offset
and
y
equal
y
offset
.
Let
x
equal
start
x
+
x
offset
and
y
equal
start
y
+
y
offset
.
Let
element
be
equal
to
the
result
of
trying
to
get
a
known
connected
element
with
argument
origin
.
Let
x
element
and
y
element
be
the
result
of
calculating
the
in-view
center
point
of
element
.
Let
x
equal
x
element
+
x
offset
,
and
y
equal
y
element
+
y
offset
.
If
x
is
less
than
0
or
greater
than
the
width
of
the
viewport
in
CSS
pixels
,
then
return
error
with
error
code
move
target
out
of
bounds
.
If
y
is
less
than
0
or
greater
than
the
height
of
the
viewport
in
CSS
pixels
,
then
return
error
with
error
code
move
target
out
of
bounds
.
Let
duration
be
equal
to
action
object
’s
If
duration
is
greater
than
0
and
inside
any
implementation-defined
bounds,
asynchronously
wait
for
an
implementation
defined
amount
of
time
to
pass.
Perform
a
pointer
move
with
arguments
source
id
,
input
state
,
duration
,
start
x
,
start
y
,
x
,
y
.
When
required
to
perform
a
pointer
move
with
arguments
source
id
,
input
state
,
duration
,
start
x
,
start
y
,
target
x
and
target
y
,
an
implementation
must
run
the
following
steps:
Let
time
delta
be
the
time
since
the
beginning
of
the
current
tick
,
measured
in
milliseconds
on
a
monotonic
clock.
Let
duration
ratio
be
the
ratio
of
time
delta
and
duration
,
if
duration
is
greater
than
0,
or
1
otherwise.
If
duration
ratio
is
1,
or
close
enough
to
1
that
the
implementation
will
not
further
subdivide
the
move
action,
let
last
be
true.
Otherwise
let
last
be
If
last
is
true,
let
x
equal
target
x
and
y
equal
target
y
.
Otherwise
let
x
equal
an
approximation
to
duration
ratio
×
(
target
x
-
start
x
)
+
start
x
,
and
y
equal
an
approximation
to
duration
ratio
×
(
target
y
-
start
y
)
+
start
y
.
Let
current
x
equal
the
Let
current
y
equal
the
If
x
is
not
equal
to
current
x
or
y
is
not
equal
to
current
y
,
run
the
following
steps:
Let
buttons
be
equal
to
input
state’s
Perform
implementation-specific
action
dispatch
steps
equivalent
to
moving
the
pointer
with
ID
source
id
having
type
pointerType
from
viewport
x
coordinate
current
x
,
viewport
y
coordinate
y
to
viewport
x
coordinate
x
and
viewport
y
coordinate
y
,
with
buttons
buttons
depressed,
in
accordance
with
the
requirements
of
[
UI-EVENTS
]
and
[
POINTER-EVENTS
].
The
generated
events
must
set
Let
input
state
’s
If
last
is
true,
return.
Run
the
following
substeps
in
parallel
:
Asynchronously
wait
for
an
implementation
defined
amount
of
time
to
pass.
Perform
a
pointer
move
with
arguments
source
id
,
input
state
,
duration
,
start
x
,
start
y
,
target
x
,
target
y
.
When
required
to
dispatch
a
pointerCancel
action
with
arguments
source
id
,
action
object
,
input
state
and
tick
duration
a
remote
end
must
run
the
following
steps:
Perform
implementation-specific
action
dispatch
steps
equivalent
to
cancelling
the
any
action
of
the
pointer
with
ID
source
id
having
type
pointerType
,
in
accordance
with
the
requirements
of
[
UI-EVENTS
]
and
[
POINTER-EVENTS
].
The
remote
end
steps
are:
Let
actions
by
tick
be
the
result
of
trying
to
extract
an
action
sequence
with
argument
parameters
.
If
the
current
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Handle
any
user
prompts
.
If
this
results
in
an
error
,
return
that
error
.
Dispatch
actions
with
argument
actions
by
tick
.
If
this
results
in
an
error
return
that
error.
The
Release
Actions
command
is
used
to
release
all
the
keys
and
pointer
buttons
that
are
currently
depressed.
This
causes
events
to
be
fired
as
if
the
state
was
released
by
an
explicit
series
of
actions.
It
also
clears
all
the
internal
state
of
the
virtual
devices.
The
remote
end
steps
are:
If
the
current
top-level
browsing
context
is
no
longer
open
,
return
error
with
error
code
no
such
window
.
Let
undo
actions
be
equal
to
the
current
session
’s
input
cancel
list
in
reverse
order.
Dispatch
tick
actions
with
arguments
undo
actions
and
duration
0.
Let
the
current
session
’s
input
cancel
list
be
an
empty
List
.
Let
the
current
session
’s
input
state
table
be
an
empty
map.
Let
the
current
session
’s
active
input
sources
be
an
empty
list
.
15.1
Input
sources
15.1.1
Sources
Action
Non-normative
Description
pause
Used
with
an
integer
argument
to
specify
the
duration
of
a
tick
,
or
as
a
placeholder
to
indicate
that
an
input
source
does
nothing
during
a
particular
tick
.
Action
Non-normative
Description
keyDown
Used
to
indicate
that
a
particular
key
should
be
held
down.
keyUp
Used
to
indicate
that
a
depressed
key
should
be
released.
Action
Non-normative
Description
pointerDown
Used
to
indicate
that
a
pointer
should
be
depressed
in
some
way
e.g.
by
holding
a
button
down
(for
a
mouse)
or
by
coming
into
contact
with
the
active
surface
(for
a
touch
or
pen
device).
pointerUp
Used
to
indicate
that
a
pointer
should
be
released
in
some
way
e.g.
by
releasing
a
mouse
button
or
moving
a
pen
or
touch
device
away
from
the
active
surface.
pointerMove
Used
to
indicate
a
location
on
the
screen
that
a
pointer
should
move
to,
either
in
its
active
(pressed)
or
inactive
state.
pointerCancel
Used
to
cancel
a
pointer
action.
input
id
and
the
value
is
the
input
source
’s
input
source
state
.
When
an
input
source
is
removed
from
the
list
of
active
input
sources
,
the
corresponding
entry
in
the
input
state
table
is
also
removed.
15.1.2
State
Action
type
Input
state
"
none
"
null
input
state
"
key
"
key
input
state
"
pointer
"
pointer
input
state
pressed
,
which
is
a
set
of
strings
representing
currently
pressed
keys
and
properties
alt
,
shift
,
ctrl
,
and
meta
,
which
are
Boolean
s.
pressed
property
set
to
the
empty
set
and
alt
,
shift
,
ctrl
,
and
meta
all
set
to
false
.
subtype
property,
which
has
the
possible
values
"
mouse
",
"
pen
",
and
"
touch
",
a
pressed
property
which
is
a
set
of
unsigned
integers,
an
x
property
which
is
an
unsigned
integer,
and
a
y
property
which
is
an
unsigned
integer.
subtype
set
to
subtype
,
pressed
set
to
an
empty
set
and
both
x
and
y
set
to
0
.
false
value.
pressed
from
source
.
alt
from
source
.
ctrl
from
source
.
meta
from
source
.
shift
from
source
.
15.2
Ticks
15.3
Processing
actions
actions
.
type
from
action
sequence
.
key
",
"
pointer
",
or
"
none
",
return
an
error
with
error
code
invalid
argument
.
id
from
action
sequence
.
pointer
",
let
parameters
data
be
the
result
of
getting
the
property
"
parameters
"
from
action
sequence
.
Then
let
parameters
be
the
result
of
trying
to
process
pointer
parameters
with
argument
parameters
data
.
none
"
key
"
pointer
"
pointerType
property.
pointerType
property
is
not
equal
to
source
’s
pointer
type
,
return
an
error
with
error
code
invalid
argument
.
actions
from
action
sequence
.
none
"
let
action
be
the
result
of
trying
to
process
a
null
action
with
parameters
id
,
and
action
item
.
key
"
let
action
be
the
result
of
trying
to
process
a
key
action
with
parameters
id
,
and
action
item
.
pointer
"
let
action
be
the
result
of
trying
to
process
a
pointer
action
with
parameters
id
,
parameters
,
and
action
item
.
pointerType
set
to
mouse
.
pointerType
from
parameters
data
.
mouse
",
"
pen
",
or
"
touch
",
return
error
with
error
code
invalid
argument
.
pointerType
property
of
parameters
to
pointer
type
.
id
set
to
id
,
type
set
to
type
and
subtype
set
to
subtype
.
Specific
action
objects
have
further
properties
added
by
other
algorithms
in
this
specification.
type
from
action
item
.
pause
",
return
error
with
error
code
invalid
argument
.
"none"
,
and
subtype
.
type
from
action
item
.
keyUp
",
"
keyDown
",
or
"
pause
",
return
an
error
with
error
code
invalid
argument
.
key
",
and
subtype
.
pause
",
let
result
be
the
result
of
trying
to
process
a
pause
action
with
arguments
action
item
and
action
,
and
return
result
.
value
from
action
item
.
value
property
on
action
to
key
.
type
from
action
item
.
pause
",
"
pointerUp
",
"
pointerDown
",
"
pointerMove
",
or
"
pointerCancel
",
return
an
error
with
error
code
invalid
argument
.
pointer
",
and
subtype
.
pause
",
let
result
be
the
result
of
trying
to
process
a
pause
action
with
arguments
action
item
and
action
,
and
return
result
.
pointerType
property
of
action
equal
to
the
pointerType
property
of
parameters
.
pointerUp
"
or
"
pointerDown
",
process
a
pointer
up
or
pointer
down
action
with
arguments
action
item
and
action
.
If
doing
so
results
in
an
error
,
return
that
error
.
pointerMove
"
process
a
pointer
move
action
with
arguments
action
item
and
action
.
If
doing
so
results
in
an
error
,
return
that
error
.
pointerCancel
"
process
a
pointer
cancel
action
.
If
doing
so
results
in
an
error
,
return
that
error
.
duration
"
from
action
item
.
duration
property
of
action
to
duration
.
button
from
action
item
.
button
property
of
action
to
button
.
null
.
duration
from
action
item
.
duration
property
of
action
to
duration
.
origin
from
action
item
.
viewport
".
viewport
"
or
"
pointer
"
and
origin
is
not
an
Object
that
represents
a
web
element
,
return
error
with
error
code
invalid
argument
.
origin
property
of
action
to
origin
.
x
from
action
item
.
x
property
of
action
to
x
.
y
from
action
item
.
y
property
of
action
to
y
.
null
.
15.4
Dispatching
actions
null
.
subtype
property
set
to
"
pause
"
or
action
object
has
type
property
set
to
"
pointer
"
and
subtype
property
set
to
"
pointerMove
",
let
duration
be
equal
to
the
duration
property
of
action
object
.
id
property.
type
property.
subtype
property,
to
a
dispatch
action
algorithm.
source
type
subtype
property
Dispatch
action
algorithm
"
none
"
"
pause
"
Dispatch
a
pause
action
"
key
"
"
pause
"
Dispatch
a
pause
action
"
key
"
"
keyDown
"
Dispatch
a
keyDown
action
"
key
"
"
keyUp
"
Dispatch
a
keyUp
action
"
pointer
"
"
pause
"
Dispatch
a
pause
action
"
pointer
"
"
pointerDown
"
Dispatch
a
pointerDown
action
"
pointer
"
"
pointerUp
"
Dispatch
a
pointerUp
action
"
pointer
"
"
pointerMove
Dispatch
a
pointerMove
action
"
pointer
"
"
pointerCancel
Dispatch
a
pointerCancel
action
15.4.1
General
actions
15.4.2
Keyboard
actions
key
’s
codepoint
Normalised
key
value
\uE000
"Unidentified"
\uE001
"Cancel"
\uE002
"Help"
\uE003
"Backspace"
\uE004
"Tab"
\uE005
"Clear"
\uE006
"Return"
\uE007
"Enter"
\uE008
"Shift"
\uE009
"Control"
\uE00A
"Alt"
\uE00B
"Pause"
\uE00C
"Escape"
\uE00D
"
"
\uE00E
"PageUp"
\uE00F
"PageDown"
\uE010
"End"
\uE011
"Home"
\uE012
"ArrowLeft"
\uE013
"ArrowUp"
\uE014
"ArrowRight"
\uE015
"ArrowDown"
\uE016
"Insert"
\uE017
"Delete"
\uE018
";"
\uE019
"="
\uE01A
"0"
\uE01B
"1"
\uE01C
"2"
\uE01D
"3"
\uE01E
"4"
\uE01F
"5"
\uE020
"6"
\uE021
"7"
\uE022
"8"
\uE023
"9"
\uE024
"*"
\uE025
"+"
\uE026
","
\uE027
"-"
\uE028
"."
\uE029
"/"
\uE031
"F1"
\uE032
"F2"
\uE033
"F3"
\uE034
"F4"
\uE035
"F5"
\uE036
"F6"
\uE037
"F7"
\uE038
"F8"
\uE039
"F9"
\uE03A
"F10"
\uE03B
"F11"
\uE03C
"F12"
\uE03D
"Meta"
\uE040
"ZenkakuHankaku"
\uE050
"Shift"
\uE051
"Control"
\uE052
"Alt"
\uE053
"Meta"
\uE054
"PageUp"
\uE055
"PageDown"
\uE056
"End"
\uE057
"Home"
\uE058
"ArrowLeft"
\uE059
"ArrowUp"
\uE05A
"ArrowRight"
\uE05B
"ArrowDown"
\uE05C
"Insert"
\uE05D
"Delete"
Key
Alternate
Key
code
"`"
"~"
"Backquote"
"\"
"|"
"Backslash"
"\uE003"
"Backspace"
"["
"{"
"BracketLeft"
"]"
"}"
"BracketRight"
","
"<"
"Comma"
"0"
")"
"Digit0"
"1"
"!"
"Digit1"
"2"
"@"
"Digit2"
"3"
"#"
"Digit3"
"4"
"$"
"Digit4"
"5"
"%"
"Digit5"
"6"
"^"
"Digit6"
"7"
"&"
"Digit7"
"8"
"*"
"Digit8"
"9"
"("
"Digit9"
"="
"+"
"Equal"
"<"
">"
"IntlBackslash"
"a"
"A"
"KeyA"
"b"
"B"
"KeyB"
"c"
"C"
"KeyC"
"d"
"D"
"KeyD"
"e"
"E"
"KeyE"
"f"
"F"
"KeyF"
"g"
"G"
"KeyG"
"h"
"H"
"KeyH"
"i"
"I"
"KeyI"
"j"
"J"
"KeyJ"
"k"
"K"
"KeyK"
"l"
"L"
"KeyL"
"m"
"M"
"KeyM"
"n"
"N"
"KeyN"
"o"
"O"
"KeyO"
"p"
"P"
"KeyP"
"q"
"Q"
"KeyQ"
"r"
"R"
"KeyR"
"s"
"S"
"KeyS"
"t"
"T"
"KeyT"
"u"
"U"
"KeyU"
"v"
"V"
"KeyV"
"w"
"W"
"KeyW"
"x"
"X"
"KeyX"
"y"
"Y"
"KeyY"
"z"
"Z"
"KeyZ"
"-"
"_"
"Minus"
"."
">"
"Period"
"'"
"""
"Quote"
";"
":"
"Semicolon"
"/"
"?"
"Slash"
"\uE00A"
"AltLeft"
"\uE052"
"AltRight"
"\uE009"
"ControlLeft"
"\uE051"
"ControlRight"
"\uE006"
"Enter"
"\uE03D"
"OSLeft"
"\uE053"
"OSRight"
"\uE008"
"ShiftLeft"
"\uE050"
"ShiftRight"
"
"
"\uE00D"
"Space"
"\uE004"
"Tab"
"\uE017"
"Delete"
"\uE010"
"End"
"\uE002"
"Help"
"\uE011"
"Home"
"\uE016"
"Insert"
"\uE00F"
"PageDown"
"\uE00E"
"PageUp"
"\uE015"
"ArrowDown"
"\uE012"
"ArrowLeft"
"\uE014"
"ArrowRight"
"\uE013"
"ArrowUp"
"\uE00C"
"Escape"
"\uE031"
"F1"
"\uE032"
"F2"
"\uE033"
"F3"
"\uE034"
"F4"
"\uE035"
"F5"
"\uE036"
"F6"
"\uE037"
"F7"
"\uE038"
"F8"
"\uE039"
"F9"
"\uE03A"
"F10"
"\uE03B"
"F11"
"\uE03C"
"F12"
"\uE01A"
"\uE05C"
"Numpad0"
"\uE01B"
"\uE056"
"Numpad1"
"\uE01C"
"\uE05B"
"Numpad2"
"\uE01D"
"\uE055"
"Numpad3"
"\uE01E"
"\uE058"
"Numpad4"
"\uE01F"
"Numpad5"
"\uE020"
"\uE05A"
"Numpad6"
"\uE021"
"\uE057"
"Numpad7"
"\uE022"
"\uE059"
"Numpad8"
"\uE023"
"\uE054"
"Numpad9"
"\uE025"
"NumpadAdd"
"\uE026"
"NumpadComma"
"\uE028"
"\uE05D"
"NumpadDecimal"
"\uE029"
"NumpadDivide"
"\uE007"
"NumpadEnter"
"\uE024"
"NumpadMultiply"
"\uE027"
"NumpadSubtract"
0
.
key
’s
codepoint
Description
Location
\uE007
Enter
1
\uE008
Left
Shift
1
\uE009
Left
Control
1
\uE00A
Left
Alt
1
\uE01A
Numpad
0
3
\uE01B
Numpad
1
3
\uE01C
Numpad
2
3
\uE01D
Numpad
3
3
\uE01E
Numpad
4
3
\uE01F
Numpad
5
3
\uE020
Numpad
6
3
\uE021
Numpad
7
3
\uE022
Numpad
8
3
\uE023
Numpad
9
3
\uE024
Numpad
*
3
\uE025
Numpad
+
3
\uE026
Numpad
,
3
\uE027
Numpad
-
3
\uE028
Numpad
.
3
\uE029
Numpad
/
3
\uE03D
Left
Meta
1
\uE050
Right
Shift
2
\uE051
Right
Control
2
\uE052
Right
Alt
2
\uE053
Right
Meta
2
\uE054
Numpad
PageUp
3
\uE055
Numpad
PageDown
3
\uE056
Numpad
End
3
\uE057
Numpad
Home
3
\uE058
Numpad
ArrowLeft
3
\uE059
Numpad
ArrowUp
3
\uE05A
Numpad
ArrowRight
3
\uE05B
Numpad
ArrowDown
3
\uE05C
Numpad
Insert
3
\uE05D
Numpad
Delete
3
value
property.
pressed
property
contains
key
,
let
repeat
be
true,
otherwise
let
repeat
be
false.
charCode
,
keyCode
and
which
properties
appropriate
for
a
key
with
key
key
and
location
location
on
a
102
key
US
keyboard,
following
the
guidelines
in
[
UI-EVENTS
].
"Alt"
,
let
device
state’s
alt
property
be
true.
"Shift"
,
let
device
state’s
shift
property
be
true.
"Control"
,
let
device
state’s
ctrl
property
be
true.
"Meta"
,
let
device
state’s
meta
property
be
true.
pressed
property.
keyDown
event.
keyDown
with
properties:
Attribute
Value
key
key
code
code
location
location
altKey
device
state
’s
alt
property
shiftKey
device
state
’s
shift
property
ctrlKey
device
state
’s
ctrl
property
metaKey
device
state
’s
meta
property
repeat
repeat
isComposing
false
charCode
charCode
keyCode
keyCode
which
which
keyPress
with
properties:
Attribute
Value
key
key
code
code
location
location
altKey
device
state
’s
alt
property
shiftKey
device
state
’s
shift
property
ctrlKey
device
state
’s
ctrl
property
metaKey
device
state
’s
meta
property
repeat
repeat
isComposing
false
charCode
charCode
keyCode
keyCode
which
which
value
property.
pressed
property
does
not
contain
key
,
return.
charCode
,
keyCode
and
which
properties
appropriate
for
a
key
with
key
key
and
location
location
on
a
102
key
US
keyboard,
following
the
guidelines
in
[
UI-EVENTS
].
"Alt"
,
let
device
state’s
alt
property
be
false.
"Shift"
,
let
device
state’s
shift
property
be
false.
"Control"
,
let
device
state’s
ctrl
property
be
false.
"Meta"
,
let
device
state’s
meta
property
be
false.
pressed
property.
keyup
,
with
properties:
Attribute
Value
key
key
code
code
location
location
altKey
device
state
’s
alt
property
shiftKey
device
state
’s
shift
property
ctrlKey
device
state
’s
ctrl
property
metaKey
device
state
’s
meta
property
repeat
false
isComposing
false
charCode
charCode
keyCode
keyCode
which
which
15.4.3
Pointer
actions
pointerType
property.
button
property.
pressed
property
contains
button
return
success
with
data
null
.
x
property.
y
property.
pressed
property,
and
let
buttons
be
the
resulting
value
of
that
property.
ctrlKey
,
shiftKey
,
altKey
,
and
metaKey
from
the
calculated
global
key
state
.
Type
specific
properties
for
the
pointer
that
are
not
exposed
through
the
webdriver
API
must
be
set
to
the
default
value
specified
for
hardware
that
doesn’t
support
that
property.
pointerType
property.
button
property.
pressed
property
does
not
contain
button
,
return
success
with
data
null
.
x
property.
y
property.
pressed
property,
and
let
buttons
be
the
resulting
value
of
that
property.
ctrlKey
,
shiftKey
,
altKey
,
and
metaKey
from
the
calculated
global
key
state
.
Type
specific
properties
for
the
pointer
that
are
not
exposed
through
the
webdriver
API
must
be
set
to
the
default
value
specified
for
hardware
that
doesn’t
support
that
property.
x
property
of
action
object
.
y
property
of
action
object
.
x
property
of
input
state
.
y
property
of
input
state
.
origin
property
of
action
object
.
viewport
"
pointer
"
duration
property
if
it
is
not
undefined
,
or
tick
duration
otherwise.
false
.
x
property
of
input
state
.
y
property
of
input
state
.
buttons
property.
ctrlKey
,
shiftKey
,
altKey
,
and
metaKey
from
the
calculated
global
key
state
.
Type
specific
properties
for
the
pointer
that
are
not
exposed
through
the
WebDriver
API
must
be
set
to
the
default
value
specified
for
hardware
that
doesn’t
support
that
property.
In
the
case
where
the
pointerType
is
"
pen
"
or
"
touch
",
and
buttons
is
empty,
this
may
be
a
no-op.
For
a
pointer
of
type
"
mouse
"
this
will
always
produce
events
including
at
least
a
pointerMove
event.
x
property
equal
x
and
y
property
equal
y
.
15.5
Perform
Actions
HTTP
Method
URI
Template
POST
/session/{
session
id
}/actions
15.6
Release
Actions
HTTP
Method
URI
Template
DELETE
/session/{
session
id
}/actions
This chapter describes interaction with various types of user prompts . The common denominator for user prompts is that they are modal windows requiring users to interact with them before the event loop is unpaused and control is returned to the current top-level browsing context .
By default user prompts are not handled automatically unless a user prompt handler has been defined. When a user prompt appears, it is the task of the subsequent command to handle it. If the subsequent requested command is not one listed in this chapter, an unexpected alert open error will be returned.
User
prompts
that
are
spawned
from
beforeunload
event
handlers,
are
dismissed
implicitly
upon
navigation
or
close
window
,
regardless
of
the
defined
user
prompt
handler
.
A
user
prompt
has
an
associated
user
prompt
message
that
is
the
string
message
shown
to
the
user,
or
null
if
the
message
length
is
0
.
The following table of simple dialogs enumerates all supported simple dialogs , along with the commands that are allowed to interact with it as a non-normative reference:
Definition | Dialog | Interactions |
---|---|---|
Alert |
window.
alert
|
Accept
Alert
Dismiss Alert Get Alert Text |
Confirm |
window.
confirm
|
Dismiss
Alert
Accept Alert Get Alert Text |
Prompt |
window.
prompt
|
Dismiss
Alert
Accept Alert Get Alert Text Send Alert Text |
The current user prompt is said to be the active user prompt , which can be one of the entries on the table of simple dialogs .
To dismiss the current user prompt , do so as if the user would click the Cancel or OK button, whichever is present, in that order.
To accept the current user prompt , do so as if the user would click the OK button.
The user prompt handler defines what action the remote end must take when a user prompt is encountered. This is defined by the unhandled prompt behavior capability. The following known prompt handling approaches table lists the keywords and states for the attribute:
Keyword | State | Description |
---|---|---|
"
dismiss
"
| Dismiss state | All simple dialogs encountered should be dismissed . |
"
accept
"
| Accept state | All simple dialogs encountered should be accepted . |
"
dismiss
and
notify
"
| Dismiss and notify state | All simple dialogs encountered should be dismissed , and an error returned that the dialog was handled. |
"
accept
and
notify
"
| Accept and notify state | All simple dialogs encountered should be accepted , and an error returned that the dialog was handled. |
"
ignore
"
| Ignore state | All simple dialogs encountered should be left to the user to handle. |
When required to deserialize as an unhandled prompt behavior an argument value :
If value is not a string return an error with error code invalid argument .
If
value
is
not
present
as
a
keyword
in
the
known
prompt
handling
approaches
table
return
an
error
with
error
code
invalid
argument
.
Return success with data value .
An annotated unexpected alert open error is an error with error code unexpected alert open and an optional error data dictionary with the following entries:
text
"
In order to handle any user prompts a remote end must take the following steps:
If there is no current user prompt , abort these steps and return success .
Perform the following substeps based on the current session ’s user prompt handler :
Dismiss the current user prompt .
Accept the current user prompt .
Dismiss the current user prompt .
Return an annotated unexpected alert open error .
Accept the current user prompt .
Return an annotated unexpected alert open error .
Return an annotated unexpected alert open error .
Return success .
HTTP Method | URI Template |
---|---|
POST | /session/{ session id }/alert/dismiss |
The Dismiss Alert command dismisses a simple dialog if present . A request to dismiss an alert user prompt , which may not necessarily have a dismiss button, has the same effect as accepting it.
The remote end steps are:
If the current top-level browsing context is no longer open , return error with error code no such window .
If there is no current user prompt , return error with error code no such alert .
Dismiss the current user prompt .
HTTP Method | URI Template |
---|---|
POST | /session/{ session id }/alert/accept |
The remote end steps are:
If the current top-level browsing context is no longer open , return error with error code no such window .
If there is no current user prompt , return error with error code no such alert .
Accept the current user prompt .
HTTP Method | URI Template |
---|---|
GET | /session/{ session id }/alert/text |
The remote end steps are:
If the current top-level browsing context is no longer open , return error with error code no such window .
If there is no current user prompt , return error with error code no such alert .
Let
message
be
the
text
message
associated
with
the
current
user
prompt
,
or
otherwise
be
null
.
Return success with data message .
HTTP Method | URI Template |
---|---|
POST | /session/{ session id }/alert/text |
The
Send
Alert
Text
command
sets
the
text
field
of
a
window.
prompt
user
prompt
to
the
given
value.
The remote end steps are:
Let
text
be
the
result
of
getting
the
property
"
text
"
from
parameters
.
If text is not a String , return error with error code invalid argument .
If the current top-level browsing context is no longer open , return error with error code no such window .
If there is no current user prompt , return error with error code no such alert .
Run the substeps of the first matching current user prompt :
Return error with error code element not interactable .
Do nothing.
Return error with error code unsupported operation .
Perform user agent dependent steps to set the value of current user prompt ’s text field to text .
Screenshots are a mechanism for providing additional visual diagnostic information. They work by dumping a snapshot of the initial viewport ’s framebuffer as a lossless PNG image. It is returned to the local end as a Base64 encoded string.
WebDriver provides the Take Screenshot command to capture the top-level browsing context ’s initial viewport , and a command Take Element Screenshot for doing the same with the visible region of an element ’s bounding rectangle after it has been scrolled into view .
In order to draw a bounding box from the framebuffer , given a rectangle :
If either the initial viewport ’s width or height is 0 CSS pixels , return error with error code unable to capture screen .
Let paint width be the initial viewport ’s width – min ( rectangle x coordinate , rectangle x coordinate + rectangle width dimension ).
Let paint height be the initial viewport ’s height – min ( rectangle y coordinate , rectangle y coordinate + rectangle height dimension ).
Let
canvas
be
a
new
canvas
element
,
and
set
its
width
and
height
to
paint
width
and
paint
height
,
respectively.
Let context , a canvas context mode , be the result of invoking the 2D context creation algorithm given canvas as the target.
Complete implementation specific steps equivalent to drawing the region of the framebuffer specified by the following coordinates onto context :
Return success with canvas .
To
encode
as
Base64
a
canvas
element
:
If
the
canvas
element
’s
bitmap’s
origin-clean
flag
is
set
to
false,
return
error
with
error
code
unable
to
capture
screen
.
If
the
canvas
element
’s
bitmap
has
no
pixels
(i.e.
either
its
horizontal
dimension
or
vertical
dimension
is
zero)
then
return
error
with
error
code
unable
to
capture
screen
.
Let
file
be
a
serialization
of
the
canvas
element’s
bitmap
as
a
file
,
using
"
image/png
"
as
an
argument.
Let
index
be
the
index
of
"
,
"
in
data
url
.
Let encoded string be a substring of data url using ( index + 1) as the start argument.
Return success with data encoded string .
HTTP Method | URI Template |
---|---|
GET | /session/{ session id }/screenshot |
The remote end steps are:
If the current top-level browsing context is no longer open , return error with error code no such window .
Handle any user prompts and return its value if it is an error .
When the user agent is next to run the animation frame callbacks :
Let root rect be the current top-level browsing context ’s document element ’s rectangle .
Let screenshot be the result of trying to call draw a bounding box from the framebuffer , given root rect as an argument.
Let
canvas
be
a
canvas
element
of
screenshot
result
’s
data.
Let encoding be the result of trying encoding as Base64 canvas .
Let encoded string be encoding result ’s data.
Return success with data encoded string .
HTTP Method | URI Template |
---|---|
GET | /session/{ session id }/element/{ element id }/screenshot |
The
Take
Element
Screenshot
command
takes
a
screenshot
of
the
visible
region
encompassed
by
the
bounding
rectangle
of
an
element
.
If
given
a
parameter
argument
scroll
that
evaluates
to
false,
the
element
will
not
be
scrolled
into
view
.
The remote end steps are:
Let
scroll
be
the
result
of
getting
the
property
scroll
from
parameters
if
it
is
not
undefined
.
Otherwise
let
it
be
true.
If the current browsing context is no longer open , return error with error code no such window .
Handle any user prompts and return its value if it is an error .
Let element be the result of trying to get a known connected element with url variable element id .
If asked to scroll , scroll into view the element .
When the user agent is next to run the animation frame callbacks :
Let element rect be element ’s rectangle .
Let screenshot result be the result of trying to call draw a bounding box from the framebuffer , given element rect as an argument.
Let
canvas
be
a
canvas
element
of
screenshot
result
’s
data.
Let encoding result be the result of trying encoding as Base64 canvas .
Let encoded string be encoding result ’s data.
Return success with data encoded string .
It is advisable that remote ends create a new profile when creating a new session . This prevents potentially sensitive session data from being accessible to new sessions , ensuring both privacy and preventing state from bleeding through to the next session.
A user agent can rely on a command-line flag or a configuration option to test whether to enable WebDriver, or alternatively make the user agent initiate or confirm the connection through a privileged content document or control widget, in case the user agent does not directly implement the HTTP endpoints.
It is strongly suggested that user agents require users to take explicit action to enable WebDriver, and that WebDriver remains disabled in publicly consumed versions of the user agent.
To prevent arbitrary machines on the network from connecting and creating sessions , it is suggested that only connections from loopback devices are allowed by default.
The
remote
end
can
include
a
configuration
option
to
limit
the
accepted
IP
range
allowed
to
connect
and
make
requests.
The
default
setting
for
this
might
be
to
limit
connections
to
the
IPv4
localhost
CIDR
range
127.0.0.0/8
and
the
IPv6
localhost
address
::1
.
[
RFC4632
]
It is also suggested that user agents make an effort to visually distinguish a user agent session that is under control of WebDriver from those used for normal browsing sessions. This can be done through a browser chrome element such as a “door hanger”, colorful decoration of the OS window, or some widget element that is prevalent in the window so that it easy to identify automation windows.
Although WebDriver does not define a primitive to ascertain the visibility of an element in the viewport , we acknowledge that it is an important feature for many users. Here we include a recommended approach which will give a simplified approximation of an element ’s visibility, but please note that it relies only on tree-traversal, and only covers a subset of visibility checks.
The
visibility
of
an
element
is
guided
by
what
is
perceptually
visible
to
the
human
eye.
In
this
context,
an
element
’s
displayedness
does
not
relate
to
the
visibility
or
display
style
properties.
The approach recommended to implementors to ascertain an element ’s visibility was originally developed by the Selenium project, and is based on crude approximations about an element 's nature and relationship in the tree. An element is in general to be considered visible if any part of it is drawn on the canvas within the boundaries of the viewport.
The
element
displayed
algorithm
is
a
boolean
state
where
true
signifies
that
the
element
is
displayed
and
false
signifies
that
the
element
is
not
displayed.
To
compute
the
state
on
element
,
invoke
the
Call
(
bot.dom.isShown
,
null
,
element
).
If
doing
so
does
not
produce
an
error,
return
the
return
value
from
this
function
call.
Otherwise
return
an
error
with
error
code
unknown
error
.
This
function
is
typically
exposed
to
GET
requests
with
a
URI
Template
of
/session/{session
id}/element/{element
id}/displayed
.
There have been a lot of people that have helped make browser automation possible over the years and thereby furthered the goals of this standard. In particular, thanks goes to the Selenium Open Source community, without which this standard would never have been possible.
This standard is authored by Aleksey Chemakin, Andreas Tolfsen , Andrey Botalov, Brian Burg, Christian Bromann, Clayton Martin, Daniel Wagner-Hall, David Burns , Dominique Hazael-Massieux, Eran Messeri, Erik Wilde, Gábor Csárdi, Henrik Skupin, James Graham, Jason Juang, Jason Leyba, Jim Evans, John Chen, John Jansen, Jonathan Lipps, Jonathon Kereliuk, Luke Inman-Semerau, Maja Frydrychowicz , Malini Das, Manoj Kumar, Marc Fisher, Mike Pennisi, Ondřej Machulda, Randall Kent, Sam Sneddon, Seva Lotoshnikov, Simon Stewart , Titus Fortner, and Vangelis Katsikaros. The work is coordinated and edited by David Burns and Simon Stewart .
Thanks to Berge Schwebs Bjørlo, Lukas Tetzlaff, Malcolm Rowe, Michael[tm] Smith, Nathan Bloomfield, Philippe Le Hégaret, Robin Berjon, Ross Patterson, and Wilhelm Joys Andersen for proofreading and suggesting areas for improvement.
This specification relies on several other underlying specifications.
The following terms are defined in the Content Security Policy Level 3 specification: [ CSP3 ]
The following terms are defined in the Document Object Model specification: [ DOM ]
getElementsByTagName
HTMLCollection
isTrusted
NodeList
querySelectorAll
querySelector
Text
node
The following attributes are defined in the Document Object Model specification: [ DOM ]
The following attributes are defined in the DOM Parsing and Serialisation specification: [ DOM-PARSING ]
The following attributes are defined in the UI Events specification: [ UI-EVENTS ]
The following attributes are defined in the UI Events Code specification: [ UIEVENTS-CODE ]
The following attributes are defined in the UI Events Code specification: [ UIEVENTS-KEY ]
The following terms are defined in the DOM Parsing and Serialization Specification: [ DOMPARSING ]
The following terms are defined in the ECMAScript Language Specification: [ ECMA-262 ]
The following terms are defined in the WHATWG Encoding specification: [ ENCODING ]
The following terms are defined in the WHATWG Fetch specification: [ FETCH ]
The following interfaces are defined in the W3C File API specification: [ FILEAPI ]
The following terms are defined in the WHATWG Fullscreen specification: [ FULLSCREEN ]
The following terms are defined in the HTML specification: [ HTML ]
activeElement
attribute
on
Document
body
element
Document
object
[[GetOwnProperty]]
of
a
Window
object
HTMLAllCollection
HTMLFormControlsCollection
HTMLOptionsCollection
input
event
applies
Window
object
WindowProxy
exotic
object
setSelectionRange
confirm
alert
prompt
The HTML specification also defines a number of elements which this specification has special-cased behavior for:
a
element
area
element
canvas
element
datalist
element
frame
element
html
element
iframe
element
input
element
map
element
optgroup
element
option
element
output
element
select
element
textarea
element
The
HTML
specification
also
defines
states
of
the
input
element
:
The HTML specification also defines a range of different attributes:
canvas
’s
height
attribute
canvas
’
width
attribute
multiple
attribute
readOnly
attribute
type
attribute
value
attribute
The HTML Editing APIs specification defines the following terms: [ EDITING ]
The following events are also defined in the HTML specification:
The “data” URL scheme specification defines the following terms: [ RFC2397 ]
To be HTTP compliant , it is supposed that the implementation supports the relevant subsets of [ RFC7230 ], [ RFC7231 ], [ RFC7232 ], [ RFC7234 ], and [ RFC7235 ].
The following terms are defined in the Cookie specification: [ RFC6265 ]
The following terms are defined in the Hypertext Transfer Protocol (HTTP) Status Code Registry:
The specification uses URI Templates . [ URI-TEMPLATE ]
hidden
visibilityState
attribute
on
Document
visible
1721e627e3b5ab90a06e82df1b088a33a8d11c20
.
visibility
property
display
property
DOMRect
ScrollIntoViewOptions
block
"
inline
"
To be SOCKS Proxy and SOCKS authentication compliant, it is supposed that the implementation supports the relevant subsets of [ RFC1928 ] and [ RFC1929 ].
The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [ WEBIDL ]
The following terms are defined in the Promises Guide. [ PROMISES-GUIDE ]
The following terms are defined in the Namespaces in XML [ XML-NAMES ]
The following terms are defined in the Document Object Model XPath standard [ XPATH ]