Skip to content

User Agent Automation and WebDriver test support #381

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

User Agent Automation and WebDriver test support #381

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6175ccf
user agent automation section and update the algorithms
mohamedamir Sep 24, 2025
783df7d
define "next wallet behavior"
mohamedamir Sep 24, 2025
4c1c17c
tidy
mohamedamir Sep 24, 2025
deaa4c6
Merge branch 'main' into user-agent-automation
marcoscaceres Oct 2, 2025
8300b5c
Reverting updates to the algorithms
mohamedamir Oct 6, 2025
9b60592
tidy
mohamedamir Oct 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
294 changes: 294 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -856,6 +856,22 @@ <h3>
</li>
</ol>
</li>
<li>If the session's [=next wallet behavior=] is set:
<ol>
<li>If the mode is "respond", resolve the promise with a new
`DigitalCredential` object whose `data` member is set to the stored
`data`.
</li>
<li>If the mode is "wait", the promise never resolves.
</li>
<li>If the mode is "decline", reject the promise with a
"NotAllowedError" `DOMException`.
</li>
</ol>
</li>
<li>Otherwise (if [=next wallet behavior=] is not set), proceed with the
normal user-interactive flow to select and use a digital credential.
</li>
<li>
<aside class="issue">
Details of how to actually get the [=digital credential=] are
Expand Down Expand Up @@ -917,6 +933,22 @@ <h3>
</li>
</ol>
</li>
<li>If the session's [=next wallet behavior=] is set:
<ol>
<li>If the mode is "respond", resolve the promise with a new
`DigitalCredential` object whose `data` member is set to the stored
`data`.
</li>
<li>If the mode is "wait", the promise never resolves.
</li>
<li>If the mode is "decline", reject the promise with a
"NotAllowedError" `DOMException`.
</li>
</ol>
</li>
<li>Otherwise (if [=next wallet behavior=] is not set), proceed with the
normal user-interactive flow to select and use a digital credential.
</li>
<li>
<aside class="issue">
Details of how to actually issue the [=digital credential=] are
Expand Down Expand Up @@ -2141,6 +2173,268 @@ <h2>
This section is a work in progress as this document evolves.
</p>
</section>
<section id="user-agent-automation" data-cite="webdriver">
Copy link
Collaborator

@marcoscaceres marcoscaceres Oct 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: let ReSpec handle the id generation.

Suggested change
<section id="user-agent-automation" data-cite="webdriver">
<section data-cite="webdriver">

<h2>
User Agent Automation
</h2>
<p>
For the purposes of user agent automation and web application testing,
this document defines a number of [[WebDriver]] [=extension commands=].
</p>
<section id="webdriver-extension-capability">
<h3>
Digital Credentials WebDriver Extension Capability
</h3>
<p>
In order to advertise the availability of [=extension commands=]
defined below, a new extension capability is defined.
</p>
<table class="data">
<thead>
<tr>
<th>
Capability
</th>
<th>
Key
</th>
<th>
Value Type
</th>
<th>
Description
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Virtual Wallet Support
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Virtual Wallet Support
Virtual Credential Manager Support

Copy link
Collaborator

@marcoscaceres marcoscaceres Oct 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We haven't really used "wallet" formally... we've stuck to holder... so I wonder if this should be "virtual holder"

Copy link
Contributor Author

@mohamedamir mohamedamir Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@timcappalli I am aware of your preferences to use "Credential Manager" instead of holder or wallet, but I think we should do this holistically in the whole spec at one time if we decide to. I won't start with the testing.

@marcoscaceres Yes, I can see we haven't used wallet formally, but given this API is exposed to web developers as well as browser engineers, I believe "wallet" is the more widely-used term in the ecosystem.
"holder" might be even more confusing IMHO.
We can also add a definition to wallet in this section. WDYT?

Copy link
Collaborator

@marcoscaceres marcoscaceres Oct 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Discussed with @mohamedamir and drafted:
#386

And hopefully that covers the "manager" aspect that @timcappalli would like included in the definition, while giving us a well understood concept by developer and implementers.

Copy link
Contributor

@TallTed TallTed Oct 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "virtual (whatever)" is not accurate and will be misunderstood.

Better might be "software (whatever)" (even if it's implemented on hardware, it's still software doing the lifting).

Rather than Virtual Credential Manager Support, I would suggest Support for Software Credential Managers or perhaps Support for Agentic Credential Managers.

</td>
<td>
<code>digital-credentials:virtualWallet</code>
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<code>digital-credentials:virtualWallet</code>
<code>digital-credentials:virtualCredentialManager</code>

</td>
<td>
[=boolean=]
</td>
<td>
Indicates whether the endpoint node supports all Virtual Wallet
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Indicates whether the endpoint node supports all Virtual Wallet
Indicates whether the endpoint node supports all Virtual Credential Manager

commands.
</td>
</tr>
</tbody>
</table>
<p>
When <a data-cite="webdriver#dfn-validate-capabilities">validating
Copy link
Collaborator

@marcoscaceres marcoscaceres Sep 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: avoid using data-cite... if something hasn't been exported from Web Driver, we should send a PR to web driver to export the definition we need.

capabilities</a>, the extension-specific substeps to validate
<code>digital-credentials:virtualWallet</code> with
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<code>digital-credentials:virtualWallet</code> with
<code>digital-credentials:virtualCredentialManager</code> with

<code>value</code> are the following:
</p>
<ol class="algorithm">
<li>If <code>value</code> is not a [=boolean=], return a
[=error|WebDriver error=] with a [=error code|WebDriver error code=]
[=invalid argument=].
</li>
<li>Otherwise, let <code>deserialized</code> be set to
<code>value</code>.
</li>
</ol>
<p>
When <a data-cite="webdriver#dfn-matching-capabilities">matching
capabilities</a>, the extension-specific steps to match
<code>digital-credentials:virtualWallet</code> with
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<code>digital-credentials:virtualWallet</code> with
<code>digital-credentials:virtualCredentialManager</code> with

<code>value</code> are the following:
</p>
<ol class="algorithm">
<li>If <code>value</code> is <code>true</code> and the
<a data-cite="webdriver#dfn-endpoint-node">endpoint node</a> does
not support any of the Virtual Wallet commands, the match is
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
not support any of the Virtual Wallet commands, the match is
not support any of the Virtual Credential Manager commands, the match is

unsuccessful.
</li>
<li>Otherwise, the match is successful.
</li>
</ol>
</section>
<section id="virtual-wallet-commands">
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<section id="virtual-wallet-commands">
<section id="virtual-cm-commands">

Copy link
Collaborator

@marcoscaceres marcoscaceres Oct 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Best to avoid acronyms 🙏

Copy link
Contributor

@TallTed TallTed Oct 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know how much acronym avoidance matters in fragment identifiers, but it still might be better to abbreviate somewhat less, perhaps as —

Suggested change
<section id="virtual-wallet-commands">
<section id="virtual-cred-mgr-commands">

Copy link
Collaborator

@marcoscaceres marcoscaceres Oct 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can leave ReSpec to generate the ids. It knows best.

Copy link
Collaborator

@marcoscaceres marcoscaceres Oct 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pro-tip: you can also omit the section tag (ReSpec adds it automatically)

<h3>
Virtual Wallet Commands
</h3>
<p>
The following commands allow controlling the behavior of a virtual
wallet for testing purposes. These commands affect the <dfn>next
wallet behavior</dfn> of the next
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The following commands allow controlling the behavior of a virtual
wallet for testing purposes. These commands affect the <dfn>next
wallet behavior</dfn> of the next
The following commands allow controlling the behavior of a virtual
credential manager for testing purposes. These commands affect the <dfn>next
credential manager behavior</dfn> of the next

<code>navigator.credentials.get({digital: ...})</code> or
<code>navigator.credentials.create({digital: ...})</code> call.
Copy link
Collaborator

@marcoscaceres marcoscaceres Sep 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These should probably link to the algorithms, not to the methods themselves.

</p>
<section id="set-wallet-response">
<h4>
<dfn>Set Wallet Response</dfn>
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<section id="set-wallet-response">
<h4>
<dfn>Set Wallet Response</dfn>
<section id="set-cm-response">
<h4>
<dfn>Set Credential Manager Response</dfn>

</h4>
<p>
The [=Set Wallet Response=] [[WebDriver]] [=extension command=]
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The [=Set Wallet Response=] [[WebDriver]] [=extension command=]
The [=Set Credential Manager Response=] [[WebDriver]] [=extension command=]

configures the virtual wallet to respond with a specific data
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
configures the virtual wallet to respond with a specific data
configures the virtual credential manager to respond with a specific data

payload, simulating a user successfully completing the flow.
</p>
<table class="data">
<thead>
<tr>
<th>
HTTP Method
</th>
<th>
URI Template
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>POST</code>
</td>
<td>
<code>/session/{session
id}/digital-credentials/response</code>
</td>
</tr>
</tbody>
</table>
<p>
The parameters object is a JSON <a data-cite=
"webdriver#dfn-object">Object</a> with the following key:
Copy link
Collaborator

@marcoscaceres marcoscaceres Sep 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

as above... we should get "object" exported from Web Driver.

</p>
<table class="data">
<thead>
<tr>
<th>
Key
</th>
<th>
Value Type
</th>
<th>
Description
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>data</code>
</td>
<td>
string
</td>
<td>
The data to be returned by the wallet.
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The data to be returned by the wallet.
The data to be returned by the credential manager.

</td>
</tr>
</tbody>
</table>
<p>
The [=remote end steps=] are:
</p>
<ol class="algorithm">
<li>If <code>parameters</code> is not a JSON <a data-cite=
Copy link
Collaborator

@marcoscaceres marcoscaceres Sep 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are JSON object and Web Driver objects different things?

Also, I wonder if this should really be framed in Web Driver 2 terminology, which I think is CBOR.

We should definitely have the Web Driver folks check all this before we merge it too.

"webdriver#dfn-object">Object</a>, or if it does not contain a
<code>data</code> property of type string, return a
[=error|WebDriver error=] with [=error code|WebDriver error code=]
[=invalid argument=].
</li>
<li>Set the session's [=next wallet behavior=] to <code>{ "mode":
"respond", "data": parameters.data }</code>.
</li>
<li>Return [=success=].
</li>
</ol>
</section>
<section id="set-wallet-to-wait">
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<section id="set-wallet-to-wait">
<section id="set-cm-to-wait">

<h4>
<dfn>Set Wallet to Wait</dfn>
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<dfn>Set Wallet to Wait</dfn>
<dfn>Set Credential Manager to Wait</dfn>

</h4>
<p>
The [=Set Wallet to Wait=] [[WebDriver]] [=extension command=]
configures the virtual wallet to simulate a user waiting
indefinitely in the wallet UI.
Comment on lines +2320 to +2322
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The [=Set Wallet to Wait=] [[WebDriver]] [=extension command=]
configures the virtual wallet to simulate a user waiting
indefinitely in the wallet UI.
The [=Set Credential Manager to Wait=] [[WebDriver]] [=extension command=]
configures the virtual credential manager to simulate a user waiting
indefinitely in the credential manager UI.

</p>
<table class="data">
<thead>
<tr>
<th>
HTTP Method
</th>
<th>
URI Template
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>POST</code>
</td>
<td>
<code>/session/{session
id}/digital-credentials/response_wait</code>
</td>
</tr>
</tbody>
</table>
<p>
The [=remote end steps=] are:
</p>
<ol class="algorithm">
<li>Set the session's [=next wallet behavior=] to <code>{ "mode":
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<li>Set the session's [=next wallet behavior=] to <code>{ "mode":
<li>Set the session's [=next credential manager behavior=] to <code>{ "mode":

"wait" }</code>.
</li>
<li>Return [=success=].
</li>
</ol>
</section>
<section id="set-wallet-to-decline">
<h4>
<dfn>Set Wallet to Decline</dfn>
Copy link
Collaborator

@marcoscaceres marcoscaceres Sep 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should say "abort" here to keep terminology consistent? (i.e., affectively this become an AbortError, right)?

Copy link
Contributor Author

@mohamedamir mohamedamir Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

YEs, but it's to simulate a user "declining" the flow.
I feel "decline" is more natural.
Let me know if you feel strongly.

Copy link
Collaborator

@marcoscaceres marcoscaceres Oct 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, "declining" is fine... was mostly an editorial suggestion.

Comment on lines +2358 to +2360
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<section id="set-wallet-to-decline">
<h4>
<dfn>Set Wallet to Decline</dfn>
<section id="set-cm-to-decline">
<h4>
<dfn>Set Credential Manager to Decline</dfn>

</h4>
<p>
The [=Set Wallet to Decline=] [[WebDriver]] [=extension command=]
configures the virtual wallet to simulate a user declining the
request.
Comment on lines +2363 to +2365
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The [=Set Wallet to Decline=] [[WebDriver]] [=extension command=]
configures the virtual wallet to simulate a user declining the
request.
The [=Set Credential Manager to Decline=] [[WebDriver]] [=extension command=]
configures the virtual credential manager to simulate a user declining the
request.

</p>
<table class="data">
<thead>
<tr>
<th>
HTTP Method
</th>
<th>
URI Template
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>POST</code>
</td>
<td>
<code>/session/{session
id}/digital-credentials/response_decline</code>
</td>
</tr>
</tbody>
</table>
<p>
The [=remote end steps=] are:
</p>
<ol class="algorithm">
<li>Set the session's [=next wallet behavior=] to <code>{ "mode":
Copy link
Collaborator

@timcappalli timcappalli Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<li>Set the session's [=next wallet behavior=] to <code>{ "mode":
<li>Set the session's [=next credential manager behavior=] to <code>{ "mode":

"decline" }</code>.
</li>
<li>Return [=success=].
</li>
</ol>
</section>
</section>
</section>
<section id="idl-index"></section>
<section id="conformance"></section>
<h2 class="appendix">
Expand Down