Browsing Context
Commands
This section contains the APIs related to browsing context commands.
Open a new window
Creates a new browsing context in a new window.
void testCreateAWindow() {
BrowsingContext browsingContext = new BrowsingContext(driver, WindowType.WINDOW);
Assertions.assertNotNull(browsingContext.getId());
} const browsingContext = await BrowsingContext(driver, {
type: 'window',
})Open a new tab
Creates a new browsing context in a new tab.
void testCreateATab() {
BrowsingContext browsingContext = new BrowsingContext(driver, WindowType.TAB);
Assertions.assertNotNull(browsingContext.getId());
} const browsingContext = await BrowsingContext(driver, {
type: 'tab',
})Use existing window handle
Creates a browsing context for the existing tab/window to run commands.
void testCreateABrowsingContextForGivenId() {
String id = driver.getWindowHandle();
BrowsingContext browsingContext = new BrowsingContext(driver, id);
Assertions.assertEquals(id, browsingContext.getId());
} const id = await driver.getWindowHandle()
const browsingContext = await BrowsingContext(driver, {
browsingContextId: 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.
void testCreateAWindowWithAReferenceContext() {
BrowsingContext
browsingContext =
new BrowsingContext(driver, WindowType.WINDOW, driver.getWindowHandle());
Assertions.assertNotNull(browsingContext.getId());
} const browsingContext = await BrowsingContext(driver, {
type: 'window',
referenceContext: await driver.getWindowHandle(),
})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.
void testCreateATabWithAReferenceContext() {
BrowsingContext
browsingContext =
new BrowsingContext(driver, WindowType.TAB, driver.getWindowHandle());
Assertions.assertNotNull(browsingContext.getId());
} const browsingContext = await BrowsingContext(driver, {
type: 'tab',
referenceContext: await driver.getWindowHandle(),
})Navigate to a URL
void testNavigateToAUrl() {
BrowsingContext browsingContext = new BrowsingContext(driver, WindowType.TAB);
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"));
} let info = await browsingContext.navigate('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')Navigate to a URL with readiness state
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());
Assertions.assertTrue(info.getUrl().contains("/bidi/logEntryAdded.html"));
} const info = await browsingContext.navigate(
'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html',
'complete'
)Get browsing context tree
Provides a tree of all browsing contexts descending from the parent browsing context, including the parent browsing context.
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();
Assertions.assertEquals(1, contextInfoList.size());
BrowsingContextInfo info = contextInfoList.get(0);
Assertions.assertEquals(1, info.getChildren().size());
Assertions.assertEquals(referenceContextId, info.getId());
Assertions.assertTrue(info.getChildren().get(0).getUrl().contains("formPage.html"));
} const browsingContextId = await driver.getWindowHandle()
const parentWindow = await BrowsingContext(driver, {
browsingContextId: browsingContextId,
})
await parentWindow.navigate('https://www.selenium.dev/selenium/web/iframes.html', 'complete')
const contextInfo = await parentWindow.getTree()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.
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);
Assertions.assertEquals(1, contextInfoList.size());
BrowsingContextInfo info = contextInfoList.get(0);
Assertions.assertNull(info.getChildren()); // since depth is 0
Assertions.assertEquals(referenceContextId, info.getId());
} const browsingContextId = await driver.getWindowHandle()
const parentWindow = await BrowsingContext(driver, {
browsingContextId: browsingContextId,
})
await parentWindow.navigate('https://www.selenium.dev/selenium/web/iframes.html', 'complete')
const contextInfo = await parentWindow.getTree(0)Get All Top level browsing contexts
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());
} const id = await driver.getWindowHandle()
const window1 = await BrowsingContext(driver, {
browsingContextId: id,
})
await BrowsingContext(driver, { type: 'window' })
const res = await window1.getTopLevelContexts()Close a tab/window
void testCloseAWindow() {
BrowsingContext window1 = new BrowsingContext(driver, WindowType.WINDOW);
BrowsingContext window2 = new BrowsingContext(driver, WindowType.WINDOW);
window2.close();
Assertions.assertThrows(BiDiException.class, window2::getTree);
}
@Test
void testCloseATab() {
BrowsingContext tab1 = new BrowsingContext(driver, WindowType.TAB);
BrowsingContext tab2 = new BrowsingContext(driver, WindowType.TAB);
tab2.close();
Assertions.assertThrows(BiDiException.class, tab2::getTree);
} const window1 = await BrowsingContext(driver, {type: 'window'})
const window2 = await BrowsingContext(driver, {type: 'window'})
await window2.close()Activate a browsing context
BrowsingContext window1 = new BrowsingContext(driver, driver.getWindowHandle());
BrowsingContext window2 = new BrowsingContext(driver, WindowType.WINDOW);
window1.activate();
const window1 = await BrowsingContext(driver, {
browsingContextId: id,
})
await BrowsingContext(driver, {
type: 'window',
})
const result = await driver.executeScript('return document.hasFocus();')
assert.equal(result, false)
await window1.activate()Reload a browsing context
BrowsingContext browsingContext = new BrowsingContext(driver, WindowType.TAB);
browsingContext.navigate("https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html", ReadinessState.COMPLETE);
NavigationResult reloadInfo = browsingContext.reload(ReadinessState.INTERACTIVE);Handle user prompt
BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());
driver.get("https://www.selenium.dev/selenium/web/alerts.html");
driver.findElement(By.id("prompt-with-default")).click();
String userText = "Selenium automates browsers";
browsingContext.handleUserPrompt(true, userText);
Capture Screenshot
BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());
driver.get("https://www.selenium.dev/selenium/web/alerts.html");
String screenshot = browsingContext.captureScreenshot(); const response = await browsingContext.captureScreenshot()Capture Viewport Screenshot
BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());
driver.get("https://www.selenium.dev/selenium/web/coordinates_tests/simple_page.html");
WebElement element = driver.findElement(By.id("box"));
Rectangle elementRectangle = element.getRect();
String screenshot =
browsingContext.captureBoxScreenshot(
elementRectangle.getX(), elementRectangle.getY(), 5, 5); const browsingContext = await BrowsingContext(driver, {
browsingContextId: id,
})
const response = await browsingContext.captureBoxScreenshot(5, 5, 10, 10)Capture Element Screenshot
BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());
driver.get("https://www.selenium.dev/selenium/web/formPage.html");
WebElement element = driver.findElement(By.id("checky"));
String screenshot = browsingContext.captureElementScreenshot(((RemoteWebElement) element).getId()); const response = await browsingContext.captureElementScreenshot(elementId)Set Viewport
BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());
driver.get("https://www.selenium.dev/selenium/web/formPage.html");
browsingContext.setViewport(250, 300, 5);Print page
BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());
driver.get("https://www.selenium.dev/selenium/web/formPage.html");
PrintOptions printOptions = new PrintOptions();
String printPage = browsingContext.print(printOptions); const result = await browsingContext.printPage({
orientation: 'landscape',
scale: 1,
background: true,
width: 30,
height: 30,
top: 1,
bottom: 1,
left: 1,
right: 1,
shrinkToFit: true,
pageRanges: ['1-2'],
})Navigate back
BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());
browsingContext.navigate("https://www.selenium.dev/selenium/web/formPage.html", ReadinessState.COMPLETE);
wait.until(visibilityOfElementLocated(By.id("imageButton"))).submit();
wait.until(titleIs("We Arrive Here"));
browsingContext.back();Navigate forward
void canNavigateForwardInTheBrowserHistory() {
BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());
browsingContext.navigate("https://www.selenium.dev/selenium/web/formPage.html", ReadinessState.COMPLETE);
wait.until(visibilityOfElementLocated(By.id("imageButton"))).submit();
wait.until(titleIs("We Arrive Here"));
browsingContext.back();
Assertions.assertTrue(driver.getPageSource().contains("We Leave From Here"));
browsingContext.forward();Traverse history
BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());
browsingContext.navigate("https://www.selenium.dev/selenium/web/formPage.html", ReadinessState.COMPLETE);
wait.until(visibilityOfElementLocated(By.id("imageButton"))).submit();
wait.until(titleIs("We Arrive Here"));
browsingContext.traverseHistory(-1);Events
This section contains the APIs related to browsing context events.
Browsing Context Created Event
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); const browsingContextInspector = await BrowsingContextInspector(driver)
await browsingContextInspector.onBrowsingContextCreated((entry) => {
contextInfo = entry
})
await driver.switchTo().newWindow('window')Dom Content loaded Event
String windowHandle = driver.switchTo().newWindow(WindowType.TAB).getWindowHandle();
BrowsingContextInfo browsingContextInfo = future.get(5, TimeUnit.SECONDS);
Assertions.assertEquals(windowHandle, browsingContextInfo.getId());
}
}
@Test
void canListenToDomContentLoadedEvent() const browsingContextInspector = await BrowsingContextInspector(driver)
let navigationInfo = null
await browsingContextInspector.onDomContentLoaded((entry) => {
navigationInfo = entry
})
const browsingContext = await BrowsingContext(driver, {
browsingContextId: await driver.getWindowHandle(),
})
await browsingContext.navigate('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html', 'complete')Browsing Context Loaded Event
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); const browsingContextInspector = await BrowsingContextInspector(driver)
await browsingContextInspector.onBrowsingContextLoaded((entry) => {
navigationInfo = entry
})
const browsingContext = await BrowsingContext(driver, {
browsingContextId: await driver.getWindowHandle(),
})
await browsingContext.navigate('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html', 'complete')Navigated Started Event
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
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); 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
})
await browsingContext.navigate('https://www.selenium.dev/selenium/web/linked_image.html#linkToAnchorOnThisPage', 'complete')User Prompt Opened Event
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
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
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()); const browsingContextInspector = await BrowsingContextInspector(driver)
await browsingContextInspector.onBrowsingContextDestroyed((entry) => {
contextInfo = entry
})
await driver.switchTo().newWindow('window')
const windowHandle = await driver.getWindowHandle()
await driver.close()
