Skip to content

Commit b130f8e

Browse files
titusfortnertitusfortner
committed
update all BiDi documentation
1 parent b68d0b8 commit b130f8e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+579
-8272
lines changed

‎website_and_docs/content/documentation/webdriver/bidi/_index.en.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: "BiDirectional functionality"
3+
linkTitle: "BiDi"
4+
weight: 16
5+
aliases: [
6+
"/documentation/en/webdriver/bidi_apis/",
7+
"/documentation/webdriver/bidi_apis/",
8+
"/documentation/webdriver/bidirectional/bidi_api_remotewebdriver",
9+
"/documentation/webdriver/bidirectional/webdriver_bidi",
10+
"/documentation/webdriver/bidirectional/webdriver_bidi/browsing_context",
11+
"/documentation/webdriver/bidirectional/webdriver_bidi/input"
12+
]
13+
---
14+
15+
BiDirectional means that communication is happening in two directions simultaneously.
16+
The traditional WebDriver model involves strict request/response commands which only allows for communication to
17+
happen in one direction at any given time. In most cases this is what you want; it ensures that the browser is
18+
doing the expected things in the right order, but there are a number of interesting things that can be done with
19+
asynchronous interactions.
20+
21+
This functionality is currently available in a limited fashion with the [Chrome DevTools Protocol] (CDP),
22+
but to address some of its drawbacks, the Selenium team, along with the major
23+
browser vendors, have worked to create the new [WebDriver BiDi Protocol](https://w3c.github.io/webdriver-bidi/).
24+
This specification aims to create a stable, cross-browser API that leverages bidirectional
25+
communication for enhanced browser automation and testing functionality,
26+
including streaming events from the user agent to the controlling software via WebSockets.
27+
Users will be able to listen for and record or manipulate events as they happen during the course of a Selenium session.
28+
29+
To use WebDriver BiDi, you must [enable it in Options](http://www.example.com)
30+
31+
Note that Selenium is updating its entire implementation from WebDriver Classic to WebDriver BiDi (while
32+
maintaining backwards compatibility as much as possible), but this section of documentation focuses on the new
33+
functionality that bidirectional communication allows.
34+
The low-level BiDi domains will be accessible in the code to the end user, but the goal is to provide
35+
high-level APIs that are straightforward methods of real-world use cases. As such, the low-level
36+
components will not be documented, and this section will focus only on the user-friendly
37+
features that we encourage users to take advantage of.
38+
39+
If there is additional functionality you'd like to see, please raise a
40+
[feature request](https://github.com/SeleniumHQ/selenium/issues/new?assignees=&labels=&template=feature.md).
41+

‎website_and_docs/content/documentation/webdriver/bidi/cdp/_index.en.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: "Chrome DevTools Protocol"
3+
linkTitle: "CDP"
4+
weight: 10
5+
description: >
6+
Examples of working with Chrome DevTools Protocol in Selenium.
7+
CDP support is temporary until WebDriver BiDi has been implemented.
8+
aliases: [
9+
"/documentation/en/support_packages/chrome_devtools/",
10+
"/documentation/support_packages/chrome_devtools/",
11+
"/documentation/webdriver/bidirectional/chrome_devtools/",
12+
"documentation/webdriver/bidirectional/chrome_devtools/cdp_endpoint/",
13+
"documentation/webdriver/bidirectional/chrome_devtools/bidi_api/",
14+
"documentation/webdriver/bidirectional/chrome_devtools/cdp_api/",
15+
]
16+
---
17+
18+
Many browsers provide "DevTools" -- a set of tools that are integrated with the browser that
19+
developers can use to debug web apps and explore the performance of their pages. Google Chrome's
20+
DevTools make use of a protocol called the Chrome DevTools Protocol (or "CDP" for short).
21+
As the name suggests, this is not designed for testing, nor to have a stable API, so functionality
22+
is highly dependent on the version of the browser.
23+
24+
Selenium is working to implement a standards-based, cross-browser, stable alternative to CDP called
25+
[WebDriver BiDi]. Until the support for this new protocol has finished, Selenium plans to provide access
26+
to CDP features where applicable.
27+
28+
### Using Chrome DevTools Protocol with Selenium
29+
30+
Chrome and Edge have a method to send basic CDP commands.
31+
This does not work for features that require bidirectional communication, and you need to know what domains to enable when
32+
and the exact names and types of domains/methods/parameters.
33+
34+
{{< tabpane text=true >}}
35+
{{% tab header="Java" %}}
36+
{{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/bidi/cdp/CdpTest.java#L22-L27" >}}
37+
{{% /tab %}}
38+
{{% tab header="Python" %}}
39+
{{< gh-codeblock path="/examples/python/tests/bidi/cdp/test_cdp.py#L2-L7" >}}
40+
{{% /tab %}}
41+
{{% tab header="CSharp" %}}
42+
{{< gh-codeblock path="/examples/dotnet/SeleniumDocs/BiDi/CDP/CDPTest.cs#L14-L21" >}}
43+
{{% /tab %}}
44+
{{% tab header="Ruby" %}}
45+
{{< gh-codeblock path="/examples/ruby/spec/bidi/cdp/cdp_spec.rb#L9-L13" >}}
46+
{{% /tab %}}
47+
{{% tab header="JavaScript" %}}
48+
{{< badge-code >}}
49+
{{% /tab %}}
50+
{{% tab header="Kotlin" %}}
51+
{{< badge-code >}}
52+
{{% /tab %}}
53+
{{< /tabpane >}}
54+
55+
56+
To make working with CDP easier, and to provide access to the more advanced features, Selenium bindings
57+
automatically generate classes and methods for the most common domains.
58+
CDP methods and implementations can change from version to version, though, so you want to keep the
59+
version of Chrome and the version of DevTools matching. Selenium supports the 3 most
60+
recent versions of Chrome at any given time,
61+
and tries to time releases to ensure that access to the latest versions are available.
62+
63+
This limitation provides additional challenges for several bindings, where dynamically
64+
generated CDP support requires users to regularly update their code to reference the proper version of CDP.
65+
In some cases an idealized implementation has been created that should work for any version of CDP without the
66+
user needing to change their code, but that is not always available.
67+
68+
Examples of how to use CDP in your Selenium tests can be found on the following pages, but
69+
we want to call out a couple commonly cited examples that are of limited practical value.
70+
* **Geo Location** — almost all sites use the IP address to determine physical location,
71+
so setting an emulated geolocation rarely has the desired effect.
72+
* **Overriding Device Metrics** — Chrome provides a great API for setting [Mobile Emulation](https://chromedriver.chromium.org/mobile-emulation)
73+
in the Options classes, which is generally superior to attempting to do this with CDP.

‎website_and_docs/content/documentation/webdriver/bidi/cdp/logging.en.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: "Chrome DevTools Logging Features"
3+
linkTitle: "Logging"
4+
weight: 2
5+
description: >
6+
Logging features using CDP.
7+
---
8+
9+
{{% pageinfo color="warning" %}}
10+
While Selenium 4 provides direct access to the Chrome DevTools Protocol, these
11+
methods will eventually be removed when WebDriver BiDi implemented.
12+
{{% /pageinfo %}}
13+
14+
15+
## Console Logs
16+
17+
{{< tabpane text=true >}}
18+
{{% tab header="Java" %}}
19+
{{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/bidi/cdp/LoggingTest.java#L31" >}}
20+
{{% /tab %}}
21+
{{% tab header="Python" %}}
22+
{{< gh-codeblock path="/examples/python/tests/bidi/cdp/test_logs.py#L11-12" >}}
23+
{{% /tab %}}
24+
{{% tab header="CSharp" %}}
25+
{{< gh-codeblock path="/examples/dotnet/SeleniumDocs/BiDi/CDP/LoggingTest.cs#L19-L25" >}}
26+
{{% /tab %}}
27+
{{% tab header="Ruby" %}}
28+
{{< gh-codeblock path="/examples/ruby/spec/bidi/cdp/logging_spec.rb#L12" >}}
29+
{{% /tab %}}
30+
{{% tab header="JavaScript" %}}
31+
{{< badge-implementation >}}
32+
{{% /tab %}}
33+
{{% tab header="Kotlin" %}}
34+
{{< badge-code >}}
35+
{{% /tab %}}
36+
{{< /tabpane >}}
37+
38+
## JavaScript Exceptions
39+
40+
{{< tabpane text=true >}}
41+
{{% tab header="Java" %}}
42+
{{< badge-implementation >}}
43+
{{% /tab %}}
44+
{{% tab header="Python" %}}
45+
{{< gh-codeblock path="/examples/python/tests/bidi/cdp/test_logs.py#L22-L23" >}}
46+
{{% /tab %}}
47+
{{% tab header="CSharp" %}}
48+
{{< gh-codeblock path="/examples/dotnet/SeleniumDocs/BiDi/CDP/LoggingTest.cs#L41-L47" >}}
49+
{{% /tab %}}
50+
{{% tab header="Ruby" %}}
51+
{{< gh-codeblock path="/examples/ruby/spec/bidi/cdp/logging_spec.rb#L26" >}}
52+
{{% /tab %}}
53+
{{% tab header="JavaScript" %}}
54+
{{< badge-implementation >}}
55+
{{% /tab %}}
56+
{{% tab header="Kotlin" %}}
57+
{{< badge-code >}}
58+
{{% /tab %}}
59+
{{< /tabpane >}}

‎website_and_docs/content/documentation/webdriver/bidi/cdp/network.en.md

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: "Chrome DevTools Network Features"
3+
linkTitle: "Network"
4+
weight: 4
5+
description: >
6+
Network features using CDP.
7+
---
8+
9+
{{% pageinfo color="warning" %}}
10+
While Selenium 4 provides direct access to the Chrome DevTools Protocol, these
11+
methods will eventually be removed when WebDriver BiDi implemented.
12+
{{% /pageinfo %}}
13+
14+
15+
## Basic authentication
16+
17+
Some applications make use of browser authentication to secure pages.
18+
It used to be common to handle them in the URL, but browsers stopped supporting this.
19+
With this code you can insert the credentials into the header when necessary
20+
21+
{{< tabpane text=true >}}
22+
{{% tab header="Java" %}}
23+
{{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/bidi/cdp/NetworkTest.java#L41-L43" >}}
24+
{{% /tab %}}
25+
{{% tab header="Python" %}}
26+
{{< gh-codeblock path="/examples/python/tests/bidi/cdp/test_network.py#L13-15" >}}
27+
{{% /tab %}}
28+
{{% tab header="CSharp" %}}
29+
{{< gh-codeblock path="/examples/dotnet/SeleniumDocs/BiDi/CDP/NetworkTest.cs#L25-L32" >}}
30+
{{% /tab %}}
31+
{{% tab header="Ruby" %}}
32+
{{< gh-codeblock path="/examples/ruby/spec/bidi/cdp/network_spec.rb#L9-L11" >}}
33+
{{% /tab %}}
34+
{{% tab header="JavaScript" %}}
35+
{{< badge-implementation >}}
36+
{{% /tab %}}
37+
{{% tab header="Kotlin" %}}
38+
{{< badge-implementation >}}
39+
{{% /tab %}}
40+
{{< /tabpane >}}
41+
42+
43+
## Network Interception
44+
45+
Both requests and responses can be recorded or transformed.
46+
47+
#### Response information
48+
49+
{{< tabpane text=true >}}
50+
{{% tab header="Java" %}}
51+
{{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/bidi/cdp/NetworkTest.java#L56-L65" >}}
52+
{{% /tab %}}
53+
{{% tab header="Python" %}}
54+
{{< badge-implementation >}}
55+
{{% /tab %}}
56+
{{% tab header="CSharp" %}}
57+
{{< gh-codeblock path="/examples/dotnet/SeleniumDocs/BiDi/CDP/NetworkTest.cs#L46-L51" >}}
58+
{{% /tab %}}
59+
{{% tab header="Ruby" %}}
60+
{{< gh-codeblock path="/examples/ruby/spec/bidi/cdp/network_spec.rb#L20-L24" >}}
61+
{{% /tab %}}
62+
{{% tab header="JavaScript" %}}
63+
{{< badge-implementation >}}
64+
{{% /tab %}}
65+
{{% tab header="Kotlin" %}}
66+
{{< badge-code >}}
67+
{{% /tab %}}
68+
{{< /tabpane >}}
69+
70+
#### Response transformation
71+
72+
{{< tabpane text=true >}}
73+
{{% tab header="Java" %}}
74+
{{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/bidi/cdp/NetworkTest.java#L75-L85" >}}
75+
{{% /tab %}}
76+
{{% tab header="Python" %}}
77+
{{< badge-implementation >}}
78+
{{% /tab %}}
79+
{{% tab header="CSharp" %}}
80+
{{< gh-codeblock path="/examples/dotnet/SeleniumDocs/BiDi/CDP/NetworkTest.cs#L62-L73" >}}
81+
{{% /tab %}}
82+
{{% tab header="Ruby" %}}
83+
{{< gh-codeblock path="/examples/ruby/spec/bidi/cdp/network_spec.rb#L31-L35" >}}
84+
{{% /tab %}}
85+
{{% tab header="JavaScript" %}}
86+
{{< badge-implementation >}}
87+
{{% /tab %}}
88+
{{% tab header="Kotlin" %}}
89+
{{< badge-code >}}
90+
{{% /tab %}}
91+
{{< /tabpane >}}
92+
93+
94+
#### Request interception
95+
96+
{{< tabpane text=true >}}
97+
{{% tab header="Java" %}}
98+
{{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/bidi/cdp/NetworkTest.java#L97-L110" >}}
99+
{{% /tab %}}
100+
{{% tab header="Python" %}}
101+
{{< badge-implementation >}}
102+
{{% /tab %}}
103+
{{% tab header="CSharp" %}}
104+
{{< gh-codeblock path="/examples/dotnet/SeleniumDocs/BiDi/CDP/NetworkTest.cs#L85-L97" >}}
105+
{{% /tab %}}
106+
{{% tab header="Ruby" %}}
107+
{{< gh-codeblock path="/examples/ruby/spec/bidi/cdp/network_spec.rb#L42-L46" >}}
108+
{{% /tab %}}
109+
{{% tab header="JavaScript" %}}
110+
{{< badge-implementation >}}
111+
{{% /tab %}}
112+
{{% tab header="Kotlin" %}}
113+
{{< badge-code >}}
114+
{{% /tab %}}
115+
{{< /tabpane >}}
116+
117+
118+
## Performance Metrics
119+
120+
{{< tabpane text=true >}}
121+
{{% tab header="Java" %}}
122+
{{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/bidi/cdp/NetworkTest.java#L125-L126" >}}
123+
{{% /tab %}}
124+
{{% tab header="Python" %}}
125+
{{< gh-codeblock path="/examples/python/tests/bidi/cdp/test_logging.py#L26-L28" >}}
126+
{{% /tab %}}
127+
{{% tab header="CSharp" %}}
128+
{{< gh-codeblock path="/examples/dotnet/SeleniumDocs/BiDi/CDP/NetworkTest.cs#L114-L118" >}}
129+
{{% /tab %}}
130+
{{% tab header="Ruby" %}}
131+
{{< gh-codeblock path="/examples/ruby/spec/bidi/cdp/network_spec.rb#L56-L57" >}}
132+
{{% /tab %}}
133+
{{% tab header="JavaScript" %}}
134+
{{< badge-implementation >}}
135+
{{% /tab %}}
136+
{{% tab header="Kotlin" %}}
137+
{{< badge-code >}}
138+
{{% /tab %}}
139+
{{< /tabpane >}}
140+
141+
142+
## Setting Cookies
143+
144+
{{< tabpane text=true >}}
145+
{{% tab header="Java" %}}
146+
{{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/bidi/cdp/NetworkTest.java#L142-L157" >}}
147+
{{% /tab %}}
148+
{{% tab header="Python" %}}
149+
{{< gh-codeblock path="/examples/python/tests/bidi/cdp/test_logging.py#L37-L44" >}}
150+
{{% /tab %}}
151+
{{% tab header="CSharp" %}}
152+
{{< gh-codeblock path="/examples/dotnet/SeleniumDocs/BiDi/CDP/NetworkTest.cs#L136-L143" >}}
153+
{{% /tab %}}
154+
{{% tab header="Ruby" %}}
155+
{{< gh-codeblock path="/examples/ruby/spec/bidi/cdp/network_spec.rb#L68-L71" >}}
156+
{{% /tab %}}
157+
{{% tab header="JavaScript" %}}
158+
{{< badge-implementation >}}
159+
{{% /tab %}}
160+
{{% tab header="Kotlin" %}}
161+
{{< badge-code >}}
162+
{{% /tab %}}
163+
{{< /tabpane >}}
164+
165+
166+
## Waiting for Downloads
167+
168+
{{< tabpane text=true >}}
169+
{{% tab header="Java" %}}
170+
{{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/bidi/cdp/NetworkTest.java#L171-L176" >}}
171+
{{% /tab %}}
172+
{{% tab header="Python" %}}
173+
{{< badge-implementation >}}
174+
{{% /tab %}}
175+
{{% tab header="CSharp" %}}
176+
{{< badge-implementation >}}
177+
{{% /tab %}}
178+
{{% tab header="Ruby" %}}
179+
{{< gh-codeblock path="/examples/ruby/spec/bidi/cdp/network_spec.rb#L82-L88" >}}
180+
{{% /tab %}}
181+
{{% tab header="JavaScript" %}}
182+
{{< badge-implementation >}}
183+
{{% /tab %}}
184+
{{% tab header="Kotlin" %}}
185+
{{< badge-code >}}
186+
{{% /tab %}}
187+
{{< /tabpane >}}

0 commit comments

Comments
 (0)