Copyright © 2022 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and permissive document license rules apply.
This document defines a set of extension commands to the WebDriver specification for controlling mock capture devices and access rules to these devices.
This section describes the status of this document at the time of its publication. 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/.
This document is not complete. It is subject to major changes and, while early experimentations are encouraged, it is therefore not intended for implementation.
This document was published by the Web Real-Time Communications Working Group as an Editor's Draft.
Publication as an Editor's Draft does not imply endorsement by W3C and its Members.
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 . 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 2 November 2021 W3C Process Document .
This section is non-normative.
This document defines a set of extension commands to the [ WebDriver2 ] specification for controlling mock capture devices and access rules to these devices.
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.
The key words MAY and MUST in this document are to be interpreted as described in BCP 14 [ RFC2119 ] [ RFC8174 ] when, and only when, they appear in all capitals, as shown here.
This specification defines conformance criteria that apply to a single product: the User Agent that implements the interfaces that it contains.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
Implementations that use ECMAScript [ ECMA-262 ] to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [ WEBIDL ], as this specification uses that specification and terminology.
A WebDriver session handles two prompt result values:
A
getUserMedia
prompt
result
which
is
either
"granted"
or
"denied"
.
This
value
is
used
when
MediaDevices
.
getUserMedia
()
is
executing
the
request
permission
to
use
step.
If
the
permission
state
is
"
prompt
",
the
request
permission
to
use
step
will
return
the
value
of
the
getUserMedia
prompt
result
.
The
default
value
of
getUserMedia
prompt
result
is
"granted"
.
A
getDisplayMedia
prompt
result
which
is
either
"granted"
or
"denied"
.
This
value
is
used
when
MediaDevices
.
getDisplayMedia
()
is
executing
the
prompt
the
user
to
choose
step.
If
the
permission
state
is
"
prompt
",
the
prompt
the
user
to
choose
step
will
return:
"denied"
if
the
value
of
the
getDisplayMedia
prompt
result
is
"denied"
.
"granted"
.
"granted"
.
Another approach is to use [ Permissions ] automation. The [ Permissions ] specification defines permissions to camera and microphone as well as display. It defines in particular the extension command to set each permission of the browsing contexts of a WebDriver session .
[
Permissions
]
automation
is
not
well
suited
for
getUserMedia
()
and
getDisplayMedia
APIs.
While
the
[
Permissions
]
automation
API
allows
to
set
each
context
indepdendently,
user
agents
may
grant/deny
automatically
requests
based
on
past
getUserMedia
calls
of
the
given
or
related
contexts.
The
"
prompt
"
value
is
also
not
useful
for
automation
purposes
and
the
value
"granted"
cannot
be
used
for
getDisplayMedia.
| HTTP Method | URI Template |
|---|---|
| POST | /session/{session id}/capture-devices/prompt-result |
The set capture prompt result extension command sets the getUserMedia prompt result and getDisplayMedia prompt result values.
WebIDLenum MockCapturePromptResult {
"granted",
"denied"
};
dictionary MockCapturePromptResultConfiguration {
MockCapturePromptResult getUserMedia;
MockCapturePromptResult getDisplayMedia;
};
The
MockCapturePromptResultConfiguration
dictionary
is
used
to
get
and
set
the
getUserMedia
prompt
result
and
getDisplayMedia
prompt
result
values.
The remote end steps are:
Let
configuration
be
the
command
parameters
argument,
converted
to
an
IDL
value
of
MockCapturePromptResultConfiguration
.
If
this
throws
an
exception,
return
a
WebDriver
error
with
WebDriver
error
code
invalid
argument
.
If the current browsing context is no longer open , return a WebDriver error with WebDriver error code no such window .
Handle any user prompts , and return its value if it is a WebDriver error .
If
configuration
.
getUserMedia
is
set,
set
getUserMedia
prompt
result
to
configuration
.
getUserMedia
.
If
configuration
.
getDisplayMedia
is
set,
set
getDisplayMedia
prompt
result
to
configuration
.
getDisplayMedia
.
Return
success
with
data
null
.
| HTTP Method | URI Template |
|---|---|
| GET | /session/{session id}/capture-devices/prompt-result |
The get capture prompt result extension command sets the getUserMedia prompt result and getDisplayMedia prompt result values.
The remote end steps are:
If the current browsing context is no longer open , return a WebDriver error with WebDriver error code no such window .
Handle any user prompts , and return its value if it is a WebDriver error .
Let
result
be
a
MockCapturePromptResultConfiguration
.
Set
result
.
getUserMedia
to
getUserMedia
prompt
result
.
Set
result
.
getDisplayMedia
to
getDisplayMedia
prompt
result
.
Return success with data result .
A mock capture device simulates a real capture device or source of data. This specification defines mock camera and microphone devices.
A
session
has
a
set
of
mock
capture
devices
.
This
set
is
used
in
getUserMedia
()
as
available
sources
and
in
enumerateDevices
()
as
available
media
decices.
A set of mock capture devices consists in a list of mock cameras and a list of mock microphones .
Mock capture devices are video or audio sources .
WebIDLdictionary MockCaptureDeviceConfiguration {
DOMString label;
DOMString deviceId;
DOMString groupId;
};
The
MockCaptureDeviceConfiguration
dictionary
is
used
to
create
mock
capture
devices
or
get
the
state
of
mock
capture
devices.
4.1.1
Dictionary
MockCaptureDeviceConfiguration
Members
label
of
type
DOMString
label
.
deviceId
of
type
DOMString
deviceId
values.
groupId
of
type
DOMString
groupId
values.
Mock
cameras
are
video
sources
.
A
mock
camera
provides
video
frames
to
MediaStreamTrack
of
kind
"video"
.
WebIDLdictionary MockCameraConfiguration : MockCaptureDeviceConfiguration {
double defaultFrameRate = 30;
DOMString facingMode = "user";
// TODO: Add more capabilities parameters like:
// ULongRange width;
// ULongRange height;
// DoubleRange frameRate;
};
The
MockCameraConfiguration
dictionary
is
used
to
create
a
mock
camera.
4.2.1
Dictionary
MockCameraConfiguration
Members
defaultFrameRate
of
type
double
frame
rate
frameRate
to
use
by
default
when
creating
a
video
source
if
no
frame
rate
constraint
is
provided
by
MediaDevices
.
getUserMedia
()
.
facingMode
of
type
DOMString
facingMode
value
of
the
mock
camera.
A
mock
camera
supports
a
single
value.
A
mock
camera
device
has
an
associated
configuration
of
type
MockCameraConfiguration
.
A session has a list of mock cameras .
At creation of the session , the list of mock cameras MUST contain one mock camera, whose configuration is:
{
defaultFrameRate = 30;
facingMode = "user";
}
;
The list of mock cameras MAY contain other mock cameras by default.
Mock
microphones
are
audio
sources
.
A
mock
microphone
provides
audio
samples
to
MediaStreamTrack
of
kind
"audio"
.
The
MockMicrophoneConfiguration
dictionary
is
used
to
create
a
mock
microphone.
WebIDLdictionary MockMicrophoneConfiguration : MockCaptureDeviceConfiguration {
unsigned long defaultSampleRate = 44100;
// TODO: Add more capabilities parameters like:
// ULongRange sampleRate;
// sequence echoCancellation;
};
4.3.1
Dictionary
MockMicrophoneConfiguration
Members
defaultSampleRate
of
type
unsigned
long
sample
rate
sampleRate
to
use
by
default
when
creating
an
audio
source
if
no
sample
rate
constraint
exists
when
calling
MediaDevices
.
getUserMedia
()
.
A
mock
microphone
device
has
an
associated
configuration
of
type
MockMicrophoneConfiguration
.
A session has a list of mock microphones .
A session has a default mock microphone .
At creation of the session , the list of mock microphones MUST contain one mock microphone, defined as the default mock microphone , whose configuration is:
{
defaultSampleRate = 44100;
}
;
The list of mock microphones MAY contain other mock microphones at creation of the session .
| HTTP Method | URI Template |
|---|---|
| POST | /session/{session id}/capture-devices/camera |
The add mock camera extension command adds a new mock camera.
The remote end steps are:
Let
configuration
be
the
command
parameters
argument,
converted
to
an
IDL
value
of
type
MockCameraConfiguration
.
If
this
throws
an
exception,
return
a
WebDriver
error
with
WebDriver
error
code
invalid
argument
.
If the current browsing context is no longer open , return a WebDriver error with WebDriver error code no such window .
Handle any user prompts , and return its value if it is a WebDriver error .
Let
mockCamera
be
the
mock
camera
in
the
list
of
mock
cameras
whose
deviceId
is
equal
to
the
url
variable
deviceId
parameter,
or
undefined
otherwise.
If
mockCamera
is
not
undefined
,
set
mockCamera
’s
configuration
to
configuration
.
Otherwise, run the following steps:
Let mockCamera be a new mock camera .
Set mockCamera ’s configuration to configuration .
Add mockCamera to the list of mock cameras .
Run the following step in parallel :
Execute the 'media input device changed' steps.
Return
success
with
data
null
.
| HTTP Method | URI Template |
|---|---|
| DELETE | /session/{session id}/capture-devices/camera/{deviceId} |
The delete mock camera extension command removes a mock camera from the list of mock cameras .
The remote end steps are:
Let
deviceId
be
the
result
of
getting
the
property
deviceId
from
the
parameters
,
converted
to
an
IDL
value
of
type
DOMString
.
If this throws an exception, return a WebDriver error with WebDriver error code invalid argument .
If the current browsing context is no longer open , return a WebDriver error with WebDriver error code no such window .
Handle any user prompts , and return its value if it is a WebDriver error .
Let
mockCamera
be
the
mock
camera
in
the
list
of
mock
cameras
whose
deviceId
is
equal
to
the
url
variable
deviceId
parameter,
or
undefined
otherwise.
If
mockCamera
is
not
undefined
,
run
the
following
steps:
Remove mockCamera from the list of mock cameras .
Run the following step in parallel :
Execute the 'media input device changed' steps.
Return
success
with
data
null
.
| HTTP Method | URI Template |
|---|---|
| POST | /session/{session id}/capture-devices/microphone |
The add mock microphone extension command adds a new mock microphone or updates an existing one.
The remote end steps are:
Let
configuration
be
the
result
of
getting
the
property
configuration
from
the
parameters
,
converted
to
an
IDL
value
of
type
MockMicrophoneConfiguration
.
If this throws an exception, return a WebDriver error with WebDriver error code invalid argument .
If the current browsing context is no longer open , return a WebDriver error with WebDriver error code no such window .
Handle any user prompts , and return its value if it is a WebDriver error .
Let
mockMicrophone
be
the
mock
microphone
in
the
list
of
mock
microphones
whose
deviceId
is
equal
to
the
url
variable
deviceId
parameter,
or
undefined
otherwise.
If
mockMicrophone
is
not
undefined
,
set
mockMicrophone
’s
configuration
to
configuration
.
Otherwise, run the following steps:
Let mockMicrophone be a new mock microphone .
Set mockMicrophone ’s configuration to configuration .
Add mockMicrophone to the list of mock devices.
If
the
default
microphone
is
undefined
,
set
default
microphone
to
mockMicrophone
.
Run the following step in parallel :
Execute the 'media input device changed' steps.
Return
success
with
data
null
.
| HTTP Method | URI Template |
|---|---|
| DELETE | /session/{session id}/capture-devices/{deviceId} |
The delete mock capture device extension command deletes a new mock capture device.
The remote end steps are:
Let
deviceId
be
the
result
of
getting
the
property
deviceId
from
the
parameters
,
converted
to
an
IDL
value
of
type
DOMString
.
If this throws an exception, return a WebDriver error with WebDriver error code invalid argument .
If the current browsing context is no longer open , return a WebDriver error with WebDriver error code no such window .
Handle any user prompts , and return its value if it is a WebDriver error .
Let
mockMicrophone
be
the
mock
microphone
in
the
list
of
mock
microphones
whose
deviceId
is
equal
to
the
url
variable
deviceId
parameter,
or
undefined
otherwise.
If
mockMicrophone
is
not
undefined
,
run
the
following
steps:
Remove mockMicrophone from the list of mock microphones .
If
mockMicrophone
is
the
default
microphone
,
set
the
default
microphone
to
the
first
microphone
in
the
list
of
mock
microphones
if
not
empty
and
to
undefined
otherwise.
Run the following step in parallel :
Execute the 'media input device changed' steps.
Return
success
with
data
null
.
| HTTP Method | URI Template |
|---|---|
| POST | /session/{session id}/capture-devices/default-microphone |
The set default mock microphone device extension command sets the default mock microphone device.
The remote end steps are:
Let
deviceId
be
the
result
of
getting
the
property
deviceId
from
the
parameters
,
converted
to
an
IDL
value
of
type
DOMString
.
If this throws an exception, return a WebDriver error with WebDriver error code invalid argument .
If the current browsing context is no longer open , return a WebDriver error with WebDriver error code no such window .
Handle any user prompts , and return its value if it is a WebDriver error .
Let
mockMicrophone
be
the
mock
microphone
in
the
list
of
mock
microphones
whose
deviceId
is
equal
to
deviceId
or
undefined
otherwise.
If
mockMicrophone
is
not
undefined
,
run
the
following
steps:
Set the default mock microphone to mockMicrophone .
Run the following step in parallel :
Execute the 'media input device changed' steps.
Return
success
with
data
null
.
| HTTP Method | URI Template |
|---|---|
| DELETE | /session/{session id}/capture-devices |
The reset mock capture devices extension command resets the list of mock capture devices to the default list of mock capture devices.
The remote end steps are:
If the current browsing context is no longer open , return a WebDriver error with WebDriver error code no such window .
Handle any user prompts , and return its value if it is a WebDriver error .
Set the the mock capture device set to the default mock capture device set.
Run the following step in parallel :
Execute the 'media input device changed' steps.
Return
success
with
data
null
.
| HTTP Method | URI Template |
|---|---|
| GET | /session/{session id}/capture-devices |
The get mock capture devices extension command gets the list of mock capture devices.
The remote end steps are:
If the current browsing context is no longer open , return a WebDriver error with WebDriver error code no such window .
Handle any user prompts , and return its value if it is a WebDriver error .
Return success with data as the mock capture device set , serialized as JSON.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: