BiDirectional API (W3C compliant)
Page being translated from
English to Portuguese. Do you speak Portuguese? Help us to translate
it by sending us pull requests!
The following list of APIs will be growing as the WebDriver BiDirectional Protocol grows
and browser vendors implement the same.
Additionally, Selenium will try to support real-world use cases that internally use a combination of W3C BiDi protocol APIs.
If there is additional functionality you’d like to see, please raise a
feature request .
1 - Browsing Context
Page being translated from
English to Portuguese. Do you speak Portuguese? Help us to translate
it by sending us pull requests!
Commands This section contains the APIs related to browsing context commands.
Open a new window Creates a new browsing context in a new window.
Java
Ruby
JavaScript
Kotlin Selenium v4.8
Assertions . assertNotNull ( browsingContext . getId ());
}
@Test
Selenium v4.8
})
assert . notEqual ( browsingContext . id , null )
})
Open a new tab Creates a new browsing context in a new tab.
Java
Ruby
JavaScript
Kotlin Selenium v4.8
Assertions . assertNotNull ( browsingContext . getId ());
}
@Test
Selenium v4.8
})
assert . notEqual ( browsingContext . id , null )
})
Use existing window handle Creates a browsing context for the existing tab/window to run commands.
Java
Ruby
JavaScript
Kotlin Selenium v4.8
}
@Test
void testCreateAWindowWithAReferenceContext () {
BrowsingContext
Selenium v4.8
browsingContextId : id ,
})
assert . equal ( browsingContext . id , id )
})
Open a window with a reference browsing context A reference browsing context is a top-level browsing context .
The API allows to pass the reference browsing context, which is used to create a new window. The implementation is operating system specific.
Java
Ruby
JavaScript
Kotlin Selenium v4.8
Assertions . assertNotNull ( browsingContext . getId ());
}
@Test
void testCreateATabWithAReferenceContext () {
BrowsingContext
Selenium v4.8
referenceContext : await driver . getWindowHandle (),
})
assert . notEqual ( browsingContext . id , null )
})
Open a tab with a reference browsing context A reference browsing context is a top-level browsing context .
The API allows to pass the reference browsing context, which is used to create a new tab. The implementation is operating system specific.
Java
Ruby
JavaScript
Kotlin Selenium v4.8
NavigationResult info = browsingContext . navigate ( "https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html" );
Assertions . assertNotNull ( browsingContext . getId ());
Assertions . assertNotNull ( info . getNavigationId ());
Assertions . assertTrue ( info . getUrl (). contains ( "/bidi/logEntryAdded.html" ));
Selenium v4.8
referenceContext : await driver . getWindowHandle (),
})
assert . notEqual ( browsingContext . id , null )
})
Navigate to a URL
Java
Ruby
JavaScript
Kotlin Selenium v4.8
@Test
void testNavigateToAUrlWithReadinessState () {
BrowsingContext browsingContext = new BrowsingContext ( driver , WindowType . TAB );
NavigationResult info = browsingContext . navigate ( "https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html" ,
ReadinessState . COMPLETE );
Assertions . assertNotNull ( browsingContext . getId ());
Assertions . assertNotNull ( info . getNavigationId ());
Selenium v4.8
assert . notEqual ( browsingContext . id , null )
Navigate to a URL with readiness state
Java
Ruby
JavaScript
Kotlin Selenium v4.8
@Test
void testGetTreeWithAChild () {
String referenceContextId = driver . getWindowHandle ();
BrowsingContext parentWindow = new BrowsingContext ( driver , referenceContextId );
parentWindow . navigate ( "https://www.selenium.dev/selenium/web/iframes.html" , ReadinessState . COMPLETE );
List < BrowsingContextInfo > contextInfoList = parentWindow . getTree ();
Selenium v4.8
'complete'
)
assert . notEqual ( browsingContext . id , null )
Get browsing context tree Provides a tree of all browsing contexts descending from the parent browsing context, including the parent browsing context.
Java
Ruby
JavaScript
Kotlin Selenium v4.8
Assertions . assertEquals ( 1 , info . getChildren (). size ());
Assertions . assertEquals ( referenceContextId , info . getId ());
Assertions . assertTrue ( info . getChildren (). get ( 0 ). getUrl (). contains ( "formPage.html" ));
}
@Test
void testGetTreeWithDepth () {
String referenceContextId = driver . getWindowHandle ();
BrowsingContext parentWindow = new BrowsingContext ( driver , referenceContextId );
parentWindow . navigate ( "https://www.selenium.dev/selenium/web/iframes.html" , ReadinessState . COMPLETE );
List < BrowsingContextInfo > contextInfoList = parentWindow . getTree ( 0 );
Selenium v4.8
browsingContextId : browsingContextId ,
})
await parentWindow . navigate ( 'https://www.selenium.dev/selenium/web/iframes.html' , 'complete' )
const contextInfo = await parentWindow . getTree ( 0 )
assert . equal ( contextInfo . children , null )
assert . equal ( contextInfo . id , browsingContextId )
Get browsing context tree with depth Provides a tree of all browsing contexts descending from the parent browsing context, including the parent browsing context upto the depth value passed.
Java
Ruby
JavaScript
Kotlin Selenium v4.8
Assertions . assertNull ( info . getChildren ()); // since depth is 0
Assertions . assertEquals ( referenceContextId , info . getId ());
}
@Test
void testGetAllTopLevelContexts () {
BrowsingContext window1 = new BrowsingContext ( driver , driver . getWindowHandle ());
BrowsingContext window2 = new BrowsingContext ( driver , WindowType . WINDOW );
List < BrowsingContextInfo > contextInfoList = window1 . getTopLevelContexts ();
Assertions . assertEquals ( 2 , contextInfoList . size ());
}
Selenium v4.8
browsingContextId : browsingContextId ,
})
await parentWindow . navigate ( 'https://www.selenium.dev/selenium/web/iframes.html' , 'complete' )
const contextInfo = await parentWindow . getTree ( 0 )
assert . equal ( contextInfo . children , null )
assert . equal ( contextInfo . id , browsingContextId )
Get All Top level browsing contexts
Java
Ruby
JavaScript
Kotlin Selenium v4.8
void testCloseAWindow () {
BrowsingContext window1 = new BrowsingContext ( driver , WindowType . WINDOW );
BrowsingContext window2 = new BrowsingContext ( driver , WindowType . WINDOW );
window2 . close ();
Assertions . assertThrows ( BiDiException . class , window2 :: getTree );
}
Close a tab/window
Java
Ruby
JavaScript
Kotlin Selenium v4.8
void testCloseATab () {
BrowsingContext tab1 = new BrowsingContext ( driver , WindowType . TAB );
BrowsingContext tab2 = new BrowsingContext ( driver , WindowType . TAB );
tab2 . close ();
Assertions . assertThrows ( BiDiException . class , tab2 :: getTree );
}
}
Selenium v4.8
await window2 . close ()
assert . doesNotThrow ( async function () {
Activate a browsing context
Java
Ruby
JavaScript
Kotlin Selenium v4.15
})
await BrowsingContext ( driver , {
Reload a browsing context
Java
Ruby
JavaScript
Kotlin Handle user prompt
Java
Ruby
JavaScript
Kotlin Selenium v4.15
const result = await driver . getPageSource ()
Capture Screenshot
Java
Ruby
JavaScript
Kotlin Capture Viewport Screenshot
Java
Ruby
JavaScript
Kotlin Selenium v4.15
})
const response = await browsingContext . captureBoxScreenshot ( 5 , 5 , 10 , 10 )
const base64code = response . slice ( 0 , 5 )
Capture Element Screenshot
Java
Ruby
JavaScript
Kotlin Selenium v4.15
const base64code = response . slice ( 0 , 5 )
Set Viewport
Java
Ruby
JavaScript
Kotlin Selenium v4.15
const result = await driver . executeScript ( 'return [window.innerWidth, window.innerHeight];' )
Print page
Java
Ruby
JavaScript
Kotlin Selenium v4.10
scale : 1 ,
background : true ,
width : 30 ,
height : 30 ,
top : 1 ,
bottom : 1 ,
left : 1 ,
right : 1 ,
shrinkToFit : true ,
pageRanges : [ '1-2' ],
})
let base64Code = result . data . slice ( 0 , 5 )
Navigate back
Java
Ruby
JavaScript
Kotlin Navigate forward
Java
Ruby
JavaScript
Kotlin Traverse history
Java
Ruby
JavaScript
Kotlin Events This section contains the APIs related to browsing context events.
Browsing Context Created Event
Java
Ruby
JavaScript
Kotlin Selenium v4.10
try ( BrowsingContextInspector inspector = new BrowsingContextInspector ( driver )) {
CompletableFuture < BrowsingContextInfo > future = new CompletableFuture <> ();
inspector . onBrowsingContextCreated ( future :: complete );
String windowHandle = driver . switchTo (). newWindow ( WindowType . WINDOW ). getWindowHandle ();
BrowsingContextInfo browsingContextInfo = future . get ( 5 , TimeUnit . SECONDS );
Selenium v4.9.2
let contextInfo = null
const browsingContextInspector = await BrowsingContextInspector ( driver )
await browsingContextInspector . onBrowsingContextCreated (( entry ) => {
contextInfo = entry
})
Dom Content loaded Event
Java
Ruby
JavaScript
Kotlin Selenium v4.10
String windowHandle = driver . switchTo (). newWindow ( WindowType . TAB ). getWindowHandle ();
BrowsingContextInfo browsingContextInfo = future . get ( 5 , TimeUnit . SECONDS );
Assertions . assertEquals ( windowHandle , browsingContextInfo . getId ());
}
}
@Test
void canListenToDomContentLoadedEvent ()
Selenium v4.9.2
it ( 'can listen to dom content loaded event' , async function () {
const browsingContextInspector = await BrowsingContextInspector ( driver )
let navigationInfo = null
await browsingContextInspector . onDomContentLoaded (( entry ) => {
navigationInfo = entry
})
const browsingContext = await BrowsingContext ( driver , {
browsingContextId : await driver . getWindowHandle (),
})
Browsing Context Loaded Event
Java
Ruby
JavaScript
Kotlin Selenium v4.10
try ( BrowsingContextInspector inspector = new BrowsingContextInspector ( driver )) {
CompletableFuture < NavigationInfo > future = new CompletableFuture <> ();
inspector . onBrowsingContextLoaded ( future :: complete );
BrowsingContext context = new BrowsingContext ( driver , driver . getWindowHandle ());
context . navigate ( "https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html" , ReadinessState . COMPLETE );
NavigationInfo navigationInfo = future . get ( 5 , TimeUnit . SECONDS );
Selenium v4.9.2
let navigationInfo = null
const browsingContextInspector = await BrowsingContextInspector ( driver )
await browsingContextInspector . onBrowsingContextLoaded (( entry ) => {
navigationInfo = entry
})
const browsingContext = await BrowsingContext ( driver , {
browsingContextId : await driver . getWindowHandle (),
})
Navigated Started Event
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( BrowsingContextInspector inspector = new BrowsingContextInspector ( driver )) {
CompletableFuture < NavigationInfo > future = new CompletableFuture <> ();
inspector . onNavigationStarted ( future :: complete );
BrowsingContext context = new BrowsingContext ( driver , driver . getWindowHandle ());
context . navigate ( "https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html" , ReadinessState . COMPLETE );
NavigationInfo navigationInfo = future . get ( 5 , TimeUnit . SECONDS );
Fragment Navigated Event
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( BrowsingContextInspector inspector = new BrowsingContextInspector ( driver )) {
CompletableFuture < NavigationInfo > future = new CompletableFuture <> ();
BrowsingContext context = new BrowsingContext ( driver , driver . getWindowHandle ());
context . navigate ( "https://www.selenium.dev/selenium/web/linked_image.html" , ReadinessState . COMPLETE );
inspector . onFragmentNavigated ( future :: complete );
context . navigate ( "https://www.selenium.dev/selenium/web/linked_image.html#linkToAnchorOnThisPage" , ReadinessState . COMPLETE );
NavigationInfo navigationInfo = future . get ( 5 , TimeUnit . SECONDS );
Selenium v4.15.0
let navigationInfo = null
const browsingContextInspector = await BrowsingContextInspector ( driver )
const browsingContext = await BrowsingContext ( driver , {
browsingContextId : await driver . getWindowHandle (),
})
await browsingContext . navigate ( 'https://www.selenium.dev/selenium/web/linked_image.html' , 'complete' )
await browsingContextInspector . onFragmentNavigated (( entry ) => {
navigationInfo = entry
})
User Prompt Opened Event
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( BrowsingContextInspector inspector = new BrowsingContextInspector ( driver )) {
CompletableFuture < NavigationInfo > future = new CompletableFuture <> ();
BrowsingContext context = new BrowsingContext ( driver , driver . getWindowHandle ());
context . navigate ( "https://www.selenium.dev/selenium/web/linked_image.html" , ReadinessState . COMPLETE );
inspector . onFragmentNavigated ( future :: complete );
context . navigate ( "https://www.selenium.dev/selenium/web/linked_image.html#linkToAnchorOnThisPage" , ReadinessState . COMPLETE );
NavigationInfo navigationInfo = future . get ( 5 , TimeUnit . SECONDS );
User Prompt Closed Event
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( BrowsingContextInspector inspector = new BrowsingContextInspector ( driver )) {
CompletableFuture < UserPromptClosed > future = new CompletableFuture <> ();
BrowsingContext context = new BrowsingContext ( driver , driver . getWindowHandle ());
inspector . onUserPromptClosed ( future :: complete );
driver . get ( "https://www.selenium.dev/selenium/web/alerts.html" );
driver . findElement ( By . id ( "prompt" )). click ();
context . handleUserPrompt ( true , "selenium" );
UserPromptClosed userPromptClosed = future . get ( 5 , TimeUnit . SECONDS );
Assertions . assertEquals ( context . getId (), userPromptClosed . getBrowsingContextId ());
Browsing Context Destroyed Event
Java
Ruby
JavaScript
Kotlin Selenium v4.18
try ( BrowsingContextInspector inspector = new BrowsingContextInspector ( driver )) {
CompletableFuture < BrowsingContextInfo > future = new CompletableFuture <> ();
inspector . onBrowsingContextDestroyed ( future :: complete );
String windowHandle = driver . switchTo (). newWindow ( WindowType . WINDOW ). getWindowHandle ();
driver . close ();
BrowsingContextInfo browsingContextInfo = future . get ( 5 , TimeUnit . SECONDS );
Assertions . assertEquals ( windowHandle , browsingContextInfo . getId ());
Selenium v4.18.0
let contextInfo = null
const browsingContextInspector = await BrowsingContextInspector ( driver )
await browsingContextInspector . onBrowsingContextDestroyed (( entry ) => {
contextInfo = entry
})
await driver . switchTo (). newWindow ( 'window' )
const windowHandle = await driver . getWindowHandle ()
2 - Browsing Context
Page being translated from
English to Portuguese. Do you speak Portuguese? Help us to translate
it by sending us pull requests!
This section contains the APIs related to input commands.
Java
Ruby
JavaScript
Kotlin Selenium v4.17
Actions selectThreeOptions =
actions . click ( options . get ( 1 )). keyDown ( Keys . SHIFT ). click ( options . get ( 3 )). keyUp ( Keys . SHIFT );
input . perform ( windowHandle , selectThreeOptions . getSequences ());
Selenium v4.17
let options = await driver . findElements ( By . tagName ( 'option' ))
const actions = driver . actions (). click ( options [ 1 ]). keyDown ( Key . SHIFT ). click ( options [ 3 ]). keyUp ( Key . SHIFT ). getSequences ()
Release Actions
Java
Ruby
JavaScript
Kotlin Selenium v4.17
Actions sendLowercase =
new Actions ( driver ). keyDown ( inputTextBox , "a" ). keyDown ( inputTextBox , "b" );
input . perform ( windowHandle , sendLowercase . getSequences ());
(( JavascriptExecutor ) driver ). executeScript ( "resetEvents()" );
input . release ( windowHandle );
Selenium v4.17
await driver . executeScript ( 'resetEvents()' )
3 - Network
Page being translated from
English to Portuguese. Do you speak Portuguese? Help us to translate
it by sending us pull requests!
Commands This section contains the APIs related to network commands.
Add network intercept
Java
Ruby
JavaScript
Kotlin Selenium v4.18
try ( Network network = new Network ( driver )) {
String intercept =
network . addIntercept ( new AddInterceptParameters ( InterceptPhase . BEFORE_REQUEST_SENT ));
Selenium v4.18
const intercept = await network . addIntercept ( new AddInterceptParameters ( InterceptPhase . BEFORE_REQUEST_SENT ))
Remove network intercept
Java
Ruby
JavaScript
Kotlin Selenium v4.18
try ( Network network = new Network ( driver )) {
String intercept =
network . addIntercept ( new AddInterceptParameters ( InterceptPhase . BEFORE_REQUEST_SENT ));
Assertions . assertNotNull ( intercept );
network . removeIntercept ( intercept );
Selenium v4.18
const network = await Network ( driver )
const intercept = await network . addIntercept ( new AddInterceptParameters ( InterceptPhase . BEFORE_REQUEST_SENT ))
Continue request blocked at authRequired phase with credentials
Java
Ruby
JavaScript
Kotlin Selenium v4.18
try ( Network network = new Network ( driver )) {
network . addIntercept ( new AddInterceptParameters ( InterceptPhase . AUTH_REQUIRED ));
network . onAuthRequired (
responseDetails ->
network . continueWithAuth (
responseDetails . getRequest (). getRequestId (),
new UsernameAndPassword ( "admin" , "admin" )));
driver . get ( "https://the-internet.herokuapp.com/basic_auth" );
Selenium v4.18
await network . addIntercept ( new AddInterceptParameters ( InterceptPhase . AUTH_REQUIRED ))
await network . authRequired ( async ( event ) => {
await network . continueWithAuth ( event . request . request , 'admin' , 'admin' )
})
Continue request blocked at authRequired phase without credentials
Java
Ruby
JavaScript
Kotlin Selenium v4.18
try ( Network network = new Network ( driver )) {
network . addIntercept ( new AddInterceptParameters ( InterceptPhase . AUTH_REQUIRED ));
network . onAuthRequired (
responseDetails ->
// Does not handle the alert
network . continueWithAuthNoCredentials ( responseDetails . getRequest (). getRequestId ()));
driver . get ( "https://the-internet.herokuapp.com/basic_auth" );
Selenium v4.18
await network . addIntercept ( new AddInterceptParameters ( InterceptPhase . AUTH_REQUIRED ))
await network . authRequired ( async ( event ) => {
await network . continueWithAuthNoCredentials ( event . request . request )
})
Cancel request blocked at authRequired phase
Java
Ruby
JavaScript
Kotlin Selenium v4.18
try ( Network network = new Network ( driver )) {
network . addIntercept ( new AddInterceptParameters ( InterceptPhase . AUTH_REQUIRED ));
network . onAuthRequired (
responseDetails ->
// Does not handle the alert
network . cancelAuth ( responseDetails . getRequest (). getRequestId ()));
driver . get ( "https://the-internet.herokuapp.com/basic_auth" );
Selenium v4.18
await network . addIntercept ( new AddInterceptParameters ( InterceptPhase . AUTH_REQUIRED ))
await network . authRequired ( async ( event ) => {
await network . cancelAuth ( event . request . request )
})
Fail request
Java
Ruby
JavaScript
Kotlin Selenium v4.18
try ( Network network = new Network ( driver )) {
network . addIntercept ( new AddInterceptParameters ( InterceptPhase . BEFORE_REQUEST_SENT ));
network . onBeforeRequestSent (
responseDetails -> network . failRequest ( responseDetails . getRequest (). getRequestId ()));
driver . manage (). timeouts (). pageLoadTimeout ( Duration . of ( 5 , ChronoUnit . SECONDS ));
Events This section contains the APIs related to network events.
Before Request Sent
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( Network network = new Network ( driver )) {
CompletableFuture < BeforeRequestSent > future = new CompletableFuture <> ();
network . onBeforeRequestSent ( future :: complete );
driver . get ( "https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html" );
BeforeRequestSent requestSent = future . get ( 5 , TimeUnit . SECONDS );
Selenium v4.18
let beforeRequestEvent = null
const network = await Network ( driver )
await network . beforeRequestSent ( function ( event ) {
beforeRequestEvent = event
})
await driver . get ( 'https://www.selenium.dev/selenium/web/blank.html' )
Response Started
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( Network network = new Network ( driver )) {
CompletableFuture < ResponseDetails > future = new CompletableFuture <> ();
network . onResponseStarted ( future :: complete );
driver . get ( "https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html" );
ResponseDetails response = future . get ( 5 , TimeUnit . SECONDS );
String windowHandle = driver . getWindowHandle ();
Selenium v4.18
let onResponseStarted = []
const network = await Network ( driver )
await network . responseStarted ( function ( event ) {
onResponseStarted . push ( event )
})
await driver . get ( 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html' )
Response Completed
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( Network network = new Network ( driver )) {
CompletableFuture < ResponseDetails > future = new CompletableFuture <> ();
network . onResponseCompleted ( future :: complete );
driver . get ( "https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html" );
ResponseDetails response = future . get ( 5 , TimeUnit . SECONDS );
String windowHandle = driver . getWindowHandle ();
Selenium v4.18
let onResponseCompleted = []
const network = await Network ( driver )
await network . responseCompleted ( function ( event ) {
onResponseCompleted . push ( event )
})
await driver . get ( 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html' )
Auth Required
Java
Ruby
JavaScript
Kotlin Selenium v4.17
try ( Network network = new Network ( driver )) {
CompletableFuture < ResponseDetails > future = new CompletableFuture <> ();
network . onAuthRequired ( future :: complete );
driver . get ( "https://the-internet.herokuapp.com/basic_auth" );
ResponseDetails response = future . get ( 5 , TimeUnit . SECONDS );
4 - Script
Page being translated from
English to Portuguese. Do you speak Portuguese? Help us to translate
it by sending us pull requests!
Commands This section contains the APIs related to script commands.
Call function in a browsing context
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( Script script = new Script ( id , driver )) {
List < LocalValue > arguments = new ArrayList <> ();
arguments . add ( PrimitiveProtocolValue . numberValue ( 22 ));
Map < Object , LocalValue > value = new HashMap <> ();
value . put ( "some_property" , LocalValue . numberValue ( 42 ));
LocalValue thisParameter = LocalValue . objectValue ( value );
arguments . add ( thisParameter );
EvaluateResult result =
script . callFunctionInBrowsingContext (
id ,
"function processWithPromise(argument) {\n"
+ " return new Promise((resolve, reject) => {\n"
+ " setTimeout(() => {\n"
+ " resolve(argument + this.some_property);\n"
+ " }, 1000)\n"
+ " })\n"
+ "}" ,
true ,
Optional . of ( arguments ),
Optional . of ( thisParameter ),
Optional . of ( ResultOwnership . ROOT ));
Selenium v4.9
const manager = await ScriptManager ( id , driver )
let argumentValues = []
let value = new ArgumentValue ( LocalValue . createNumberValue ( 22 ))
argumentValues . push ( value )
let mapValue = { some_property : LocalValue . createNumberValue ( 42 )}
let thisParameter = new ArgumentValue ( LocalValue . createObjectValue ( mapValue )). asMap ()
const result = await manager . callFunctionInBrowsingContext (
id ,
'function processWithPromise(argument) {' +
'return new Promise((resolve, reject) => {' +
'setTimeout(() => {' +
'resolve(argument + this.some_property);' +
'}, 1000)' +
'})' +
'}' ,
true ,
argumentValues ,
thisParameter ,
ResultOwnership . ROOT )
Call function in a sandbox
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( Script script = new Script ( id , driver )) {
EvaluateResult result =
script . callFunctionInBrowsingContext (
id ,
"sandbox" ,
"() => window.foo" ,
true ,
Optional . empty (),
Optional . empty (),
Optional . empty ());
Selenium v4.9
const manager = await ScriptManager ( id , driver )
await manager . callFunctionInBrowsingContext ( id , '() => { window.foo = 2; }' , true , null , null , null , 'sandbox' )
Call function in a realm
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( Script script = new Script ( tab , driver )) {
List < RealmInfo > realms = script . getAllRealms ();
String realmId = realms . get ( 0 ). getRealmId ();
EvaluateResult result = script . callFunctionInRealm (
realmId ,
"() => { window.foo = 3; }" ,
true ,
Optional . empty (),
Optional . empty (),
Optional . empty ());
Selenium v4.9
const manager = await ScriptManager ( firstTab , driver )
const realms = await manager . getAllRealms ()
const realmId = realms [ 0 ]. realmId
await manager . callFunctionInRealm ( realmId , '() => { window.foo = 3; }' , true )
Evaluate script in a browsing context
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( Script script = new Script ( id , driver )) {
EvaluateResult result =
script . evaluateFunctionInBrowsingContext ( id , "1 + 2" , true , Optional . empty ());
Selenium v4.9
const manager = await ScriptManager ( id , driver )
const result = await manager . evaluateFunctionInBrowsingContext ( id , '1 + 2' , true )
Evaluate script in a sandbox
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( Script script = new Script ( id , driver )) {
EvaluateResult result =
script . evaluateFunctionInBrowsingContext (
id , "sandbox" , "window.foo" , true , Optional . empty ());
Selenium v4.9
const manager = await ScriptManager ( id , driver )
await manager . evaluateFunctionInBrowsingContext ( id , 'window.foo = 2' , true , null , 'sandbox' )
const resultInSandbox = await manager . evaluateFunctionInBrowsingContext ( id , 'window.foo' , true , null , 'sandbox' )
Evaluate script in a realm
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( Script script = new Script ( tab , driver )) {
List < RealmInfo > realms = script . getAllRealms ();
String realmId = realms . get ( 0 ). getRealmId ();
EvaluateResult result =
script . evaluateFunctionInRealm (
realmId , "window.foo" , true , Optional . empty ());
Selenium v4.9
const manager = await ScriptManager ( firstTab , driver )
const realms = await manager . getAllRealms ()
const realmId = realms [ 0 ]. realmId
await manager . evaluateFunctionInRealm ( realmId , 'window.foo = 3' , true )
const result = await manager . evaluateFunctionInRealm ( realmId , 'window.foo' , true )
Disown handles in a browsing context
Java
Ruby
JavaScript
Kotlin Selenium v4.15
script . disownBrowsingContextScript (
Selenium v4.9
await manager . disownBrowsingContextScript ( id , boxId )
Disown handles in a realm
Java
Ruby
JavaScript
Kotlin Selenium v4.15
script . disownRealmScript ( realmId , List . of ( boxId ));
Selenium v4.9
await manager . disownRealmScript ( realmId , boxId )
Get all realms
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( Script script = new Script ( firstWindow , driver )) {
List < RealmInfo > realms = script . getAllRealms ();
Selenium v4.9
const manager = await ScriptManager ( firstWindow , driver )
const realms = await manager . getAllRealms ()
Get realm by type
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( Script script = new Script ( firstWindow , driver )) {
List < RealmInfo > realms = script . getRealmsByType ( RealmType . WINDOW );
Selenium v4.9
const manager = await ScriptManager ( firstWindow , driver )
const realms = await manager . getRealmsByType ( RealmType . WINDOW )
Get browsing context realms
Java
Ruby
JavaScript
Kotlin Selenium v4.15
try ( Script script = new Script ( windowId , driver )) {
List < RealmInfo > realms = script . getRealmsInBrowsingContext ( tabId );
Selenium v4.9
const manager = await ScriptManager ( windowId , driver )
const realms = await manager . getRealmsInBrowsingContext ( tabId )
Get browsing context realms by type
Java
Ruby
JavaScript
Kotlin Selenium v4.15
List < RealmInfo > windowRealms =
script . getRealmsInBrowsingContextByType ( windowId , RealmType . WINDOW );
Selenium v4.9
const realms = await manager . getRealmsInBrowsingContextByType ( windowId , RealmType . WINDOW )
Preload a script
Java
Ruby
JavaScript
Kotlin Selenium v4.15
String id = script . addPreloadScript ( "() => { window.bar=2; }" , "sandbox" );
Selenium v4.10
const manager = await ScriptManager ( id , driver )
const scriptId = await manager . addPreloadScript ( '() => {{ console.log(\'{preload_script_console_text}\') }}' )
Remove a preloaded script
Java
Ruby
JavaScript
Kotlin Selenium v4.15
script . removePreloadScript ( id );
Selenium v4.10
await manager . removePreloadScript ( scriptId )
Events This section contains the APIs related to script events.
Message
Java
Ruby
JavaScript
Kotlin Selenium v4.16
script . onMessage ( future :: complete );
script . callFunctionInBrowsingContext (
driver . getWindowHandle (),
"(channel) => channel('foo')" ,
false ,
Optional . of ( List . of ( LocalValue . channelValue ( "channel_name" ))),
Optional . empty (),
Optional . empty ());
Message message = future . get ( 5 , TimeUnit . SECONDS );
Assertions . assertEquals ( "channel_name" , message . getChannel ());
}
}
Selenium v4.18
const manager = await ScriptManager ( undefined , driver )
let message = null
await manager . onMessage (( m ) => {
message = m
})
let argumentValues = []
let value = new ArgumentValue ( LocalValue . createChannelValue ( new ChannelValue ( 'channel_name' )))
argumentValues . push ( value )
const result = await manager . callFunctionInBrowsingContext (
await driver . getWindowHandle (),
'(channel) => channel("foo")' ,
false ,
argumentValues ,
)
Realm Created
Java
Ruby
JavaScript
Kotlin Selenium v4.16
BrowsingContext context = new BrowsingContext ( driver , driver . getWindowHandle ());
context . navigate ( "https://www.selenium.dev/selenium/blankPage" );
RealmInfo realmInfo = future . get ( 5 , TimeUnit . SECONDS );
Assertions . assertNotNull ( realmInfo . getRealmId ());
Assertions . assertEquals ( RealmType . WINDOW , realmInfo . getRealmType ());
}
}
@Test
Selenium v4.18
const manager = await ScriptManager ( undefined , driver )
let realmInfo = null
await manager . onRealmCreated (( result ) => {
realmInfo = result
})
const id = await driver . getWindowHandle ()
const browsingContext = await BrowsingContext ( driver , {
browsingContextId : id ,
})
await browsingContext . navigate ( 'https://www.selenium.dev/selenium/web/blank' , 'complete' )
Realm Destroyed
Java
Ruby
JavaScript
Kotlin Selenium v4.16
BrowsingContext context = new BrowsingContext ( driver , driver . getWindowHandle ());
context . close ();
RealmInfo realmInfo = future . get ( 5 , TimeUnit . SECONDS );
Assertions . assertNotNull ( realmInfo . getRealmId ());
Assertions . assertEquals ( RealmType . WINDOW , realmInfo . getRealmType ());
}
}
}
Selenium v4.19
const manager = await ScriptManager ( undefined , driver )
let realmInfo = null
await manager . onRealmDestroyed (( result ) => {
realmInfo = result
})
const id = await driver . getWindowHandle ()
const browsingContext = await BrowsingContext ( driver , {
browsingContextId : id ,
})
await browsingContext . close ()
5 - BiDirectional API (W3C compliant)
Page being translated from
English to Portuguese. Do you speak Portuguese? Help us to translate
it by sending us pull requests!
This section contains the APIs related to logging.
Console logs Listen to the console.log
events and register callbacks to process the event.
Java
Ruby
JavaScript
Kotlin Selenium v4.8
try ( LogInspector logInspector = new LogInspector ( driver )) {
logInspector . onConsoleEntry ( logs :: add );
}
driver . get ( "https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html" );
driver . findElement ( By . id ( "consoleLog" )). click ();
const inspector = await LogInspector ( driver )
await inspector . onConsoleEntry ( function ( log ) {
logEntry = log
})
await driver . get ( 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html' )
await driver . findElement ({ id : 'consoleLog' }). click ()
assert . equal ( logEntry . text , 'Hello, world!' )
assert . equal ( logEntry . realm , null )
assert . equal ( logEntry . type , 'console' )
assert . equal ( logEntry . level , 'info' )
assert . equal ( logEntry . method , 'log' )
assert . equal ( logEntry . stackTrace , null )
assert . equal ( logEntry . args . length , 1 )
JavaScript exceptions Listen to the JS Exceptions
and register callbacks to process the exception details.
Java
Ruby
JavaScript
Kotlin driver . findElement ( By . id ( "jsException" )). click ();
JavascriptLogEntry logEntry = future . get ( 5 , TimeUnit . SECONDS );
Assertions . assertEquals ( "Error: Not working" , logEntry . getText ());
Assertions . assertEquals ( "javascript" , logEntry . getType ());
const inspector = await LogInspector ( driver )
await inspector . onJavascriptException ( function ( log ) {
logEntry = log
})
await driver . get ( 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html' )
await driver . findElement ({ id : 'jsException' }). click ()
assert . equal ( logEntry . text , 'Error: Not working' )
assert . equal ( logEntry . type , 'javascript' )
assert . equal ( logEntry . level , 'error' )
Listen to JS Logs Listen to all JS logs at all levels and register callbacks to process the log.
Java
Ruby
JavaScript
Kotlin Selenium v4.8
Assertions . assertEquals ( "Hello, world!" , logEntry . getText ());
Assertions . assertNull ( logEntry . getRealm ());
Assertions . assertEquals ( 1 , logEntry . getArgs (). size ());
Assertions . assertEquals ( "console" , logEntry . getType ());
Assertions . assertEquals ( "log" , logEntry . getMethod ());