瀏覽情境

命令

本節包含與瀏覽情境命令相關的 API。

開啟新視窗

在新視窗中建立新的瀏覽情境。

    void testCreateAWindow() {
        BrowsingContext browsingContext = new BrowsingContext(driver, WindowType.WINDOW);
        Assertions.assertNotNull(browsingContext.getId());
    }

在 GitHub 上查看完整範例

新增範例

Selenium v4.8

    const browsingContext = await BrowsingContext(driver, {
      type: 'window',
    })

在 GitHub 上查看完整範例

新增範例

開啟新分頁

在新分頁中建立新的瀏覽情境。

Selenium v4.8

    void testCreateATab() {
        BrowsingContext browsingContext = new BrowsingContext(driver, WindowType.TAB);
        Assertions.assertNotNull(browsingContext.getId());
    }

在 GitHub 上查看完整範例

新增範例

Selenium v4.8

    const browsingContext = await BrowsingContext(driver, {
      type: 'tab',
    })

在 GitHub 上查看完整範例

新增範例

使用現有的視窗控制代碼

為現有的分頁/視窗建立瀏覽情境以執行命令。

Selenium v4.8

    void testCreateABrowsingContextForGivenId() {
        String id = driver.getWindowHandle();
        BrowsingContext browsingContext = new BrowsingContext(driver, id);
        Assertions.assertEquals(id, browsingContext.getId());
    }

在 GitHub 上查看完整範例

新增範例

Selenium v4.8

    const id = await driver.getWindowHandle()
    const browsingContext = await BrowsingContext(driver, {
      browsingContextId: id,
    })

在 GitHub 上查看完整範例

新增範例

使用參考瀏覽情境開啟視窗

參考瀏覽情境是一個頂層瀏覽情境。此 API 允許傳遞參考瀏覽情境，用於建立新視窗。實作方式與作業系統相關。

Selenium v4.8

    void testCreateAWindowWithAReferenceContext() {
        BrowsingContext
                browsingContext =
                new BrowsingContext(driver, WindowType.WINDOW, driver.getWindowHandle());
        Assertions.assertNotNull(browsingContext.getId());
    }

在 GitHub 上查看完整範例

新增範例

Selenium v4.8

    const browsingContext = await BrowsingContext(driver, {
      type: 'window',
      referenceContext: await driver.getWindowHandle(),
    })

在 GitHub 上查看完整範例

新增範例

使用參考瀏覽情境開啟分頁

參考瀏覽情境是一個頂層瀏覽情境。此 API 允許傳遞參考瀏覽情境，用於建立新分頁。實作方式與作業系統相關。

Selenium v4.8

    void testCreateATabWithAReferenceContext() {
        BrowsingContext
                browsingContext =
                new BrowsingContext(driver, WindowType.TAB, driver.getWindowHandle());
        Assertions.assertNotNull(browsingContext.getId());
    }

在 GitHub 上查看完整範例

新增範例

Selenium v4.8

    const browsingContext = await BrowsingContext(driver, {
      type: 'tab',
      referenceContext: await driver.getWindowHandle(),
    })

在 GitHub 上查看完整範例

新增範例

導航至 URL

Selenium v4.8

    void testNavigateToAUrl() {
        BrowsingContext browsingContext = new BrowsingContext(driver, WindowType.TAB);

        NavigationResult info = browsingContext.navigate("https://selenium.dev.org.tw/selenium/web/bidi/logEntryAdded.html");

        Assertions.assertNotNull(browsingContext.getId());
        Assertions.assertNotNull(info.getNavigationId());
        Assertions.assertTrue(info.getUrl().contains("/bidi/logEntryAdded.html"));
    }

在 GitHub 上查看完整範例

新增範例

Selenium v4.8

    let info = await browsingContext.navigate('https://selenium.dev.org.tw/selenium/web/bidi/logEntryAdded.html')

在 GitHub 上查看完整範例

新增範例

導航至具有就緒狀態的 URL

Selenium v4.8

    void testNavigateToAUrlWithReadinessState() {
        BrowsingContext browsingContext = new BrowsingContext(driver, WindowType.TAB);

        NavigationResult info = browsingContext.navigate("https://selenium.dev.org.tw/selenium/web/bidi/logEntryAdded.html",
                ReadinessState.COMPLETE);

        Assertions.assertNotNull(browsingContext.getId());
        Assertions.assertNotNull(info.getNavigationId());
        Assertions.assertTrue(info.getUrl().contains("/bidi/logEntryAdded.html"));
    }

在 GitHub 上查看完整範例

新增範例

Selenium v4.8

    const info = await browsingContext.navigate(
      'https://selenium.dev.org.tw/selenium/web/bidi/logEntryAdded.html',
      'complete'
    )

在 GitHub 上查看完整範例

新增範例

取得瀏覽情境樹狀結構

提供從父瀏覽情境向下延伸的所有瀏覽情境的樹狀結構，包含父瀏覽情境。

Selenium v4.8

    void testGetTreeWithAChild() {
        String referenceContextId = driver.getWindowHandle();
        BrowsingContext parentWindow = new BrowsingContext(driver, referenceContextId);

        parentWindow.navigate("https://selenium.dev.org.tw/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"));
    }

在 GitHub 上查看完整範例

新增範例

Selenium v4.8

    const browsingContextId = await driver.getWindowHandle()
    const parentWindow = await BrowsingContext(driver, {
      browsingContextId: browsingContextId,
    })
    await parentWindow.navigate('https://selenium.dev.org.tw/selenium/web/iframes.html', 'complete')

    const contextInfo = await parentWindow.getTree()

在 GitHub 上查看完整範例

新增範例

取得具有深度的瀏覽情境樹狀結構

提供從父瀏覽情境向下延伸的所有瀏覽情境的樹狀結構，包含父瀏覽情境，直到傳遞的深度值。

Selenium v4.8

    void testGetTreeWithDepth() {
        String referenceContextId = driver.getWindowHandle();
        BrowsingContext parentWindow = new BrowsingContext(driver, referenceContextId);

        parentWindow.navigate("https://selenium.dev.org.tw/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());
    }

在 GitHub 上查看完整範例

新增範例

Selenium v4.8

    const browsingContextId = await driver.getWindowHandle()
    const parentWindow = await BrowsingContext(driver, {
      browsingContextId: browsingContextId,
    })
    await parentWindow.navigate('https://selenium.dev.org.tw/selenium/web/iframes.html', 'complete')

    const contextInfo = await parentWindow.getTree(0)

在 GitHub 上查看完整範例

新增範例

取得所有頂層瀏覽情境

Selenium v4.8

    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());
    }

在 GitHub 上查看完整範例

新增範例

Selenium v4.20.0

    const id = await driver.getWindowHandle()
    const window1 = await BrowsingContext(driver, {
      browsingContextId: id,
    })
    await BrowsingContext(driver, { type: 'window' })
    const res = await window1.getTopLevelContexts()

在 GitHub 上查看完整範例

新增範例

關閉分頁/視窗

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);
    }

    @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);
    }

在 GitHub 上查看完整範例

新增範例

Selenium v4.8

    const window1 = await BrowsingContext(driver, {type: 'window'})
    const window2 = await BrowsingContext(driver, {type: 'window'})

    await window2.close()

在 GitHub 上查看完整範例

新增範例

啟用瀏覽情境

Selenium v4.14.1

        BrowsingContext window1 = new BrowsingContext(driver, driver.getWindowHandle());
        BrowsingContext window2 = new BrowsingContext(driver, WindowType.WINDOW);

        window1.activate();

在 GitHub 上查看完整範例

新增範例

Selenium v4.15

    const window1 = await BrowsingContext(driver, {
      browsingContextId: id,
    })

在 GitHub 上查看完整範例

    await window1.activate()

在 GitHub 上查看完整範例

新增範例

重新載入瀏覽情境

Selenium v4.13.0

        BrowsingContext browsingContext = new BrowsingContext(driver, WindowType.TAB);

        browsingContext.navigate("https://selenium.dev.org.tw/selenium/web/bidi/logEntryAdded.html", ReadinessState.COMPLETE);

        NavigationResult reloadInfo = browsingContext.reload(ReadinessState.INTERACTIVE);

在 GitHub 上查看完整範例

新增範例

Selenium v4.15

    await browsingContext.reload(undefined, 'complete')

在 GitHub 上查看完整範例

新增範例

處理使用者提示

Selenium v4.13.0

        BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());

        driver.get("https://selenium.dev.org.tw/selenium/web/alerts.html");

        driver.findElement(By.id("prompt-with-default")).click();

        String userText = "Selenium automates browsers";
        browsingContext.handleUserPrompt(true, userText);

在 GitHub 上查看完整範例

新增範例

Selenium v4.15

    await browsingContext.handleUserPrompt(true, userText)

在 GitHub 上查看完整範例

新增範例

擷取螢幕截圖

Selenium v4.13.0

        BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());

        driver.get("https://selenium.dev.org.tw/selenium/web/alerts.html");

        String screenshot = browsingContext.captureScreenshot();

在 GitHub 上查看完整範例

新增範例

Selenium v4.15

    const response = await browsingContext.captureScreenshot()

在 GitHub 上查看完整範例

新增範例

擷取視口螢幕截圖

Selenium v4.14.0

        BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());

        driver.get("https://selenium.dev.org.tw/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);

在 GitHub 上查看完整範例

新增範例

Selenium v4.15

    const browsingContext = await BrowsingContext(driver, {
      browsingContextId: id,
    })

    const response = await browsingContext.captureBoxScreenshot(5, 5, 10, 10)

在 GitHub 上查看完整範例

新增範例

擷取元素螢幕截圖

Selenium v4.14.0

        BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());

        driver.get("https://selenium.dev.org.tw/selenium/web/formPage.html");
        WebElement element = driver.findElement(By.id("checky"));

        String screenshot = browsingContext.captureElementScreenshot(((RemoteWebElement) element).getId());

在 GitHub 上查看完整範例

新增範例

Selenium v4.15

    const response = await browsingContext.captureElementScreenshot(elementId)

在 GitHub 上查看完整範例

新增範例

設定視口

Selenium v4.14.1

        BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());
        driver.get("https://selenium.dev.org.tw/selenium/web/formPage.html");

        browsingContext.setViewport(250, 300, 5);

在 GitHub 上查看完整範例

新增範例

Selenium v4.15

    await browsingContext.setViewport(250, 300)

在 GitHub 上查看完整範例

新增範例

列印頁面

Selenium v4.14.1

        BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());

        driver.get("https://selenium.dev.org.tw/selenium/web/formPage.html");
        PrintOptions printOptions = new PrintOptions();

        String printPage = browsingContext.print(printOptions);

在 GitHub 上查看完整範例

新增範例

Selenium v4.10

    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'],
    })

在 GitHub 上查看完整範例

新增範例

Selenium v4.16.0

        BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());
        browsingContext.navigate("https://selenium.dev.org.tw/selenium/web/formPage.html", ReadinessState.COMPLETE);

        wait.until(visibilityOfElementLocated(By.id("imageButton"))).submit();
        wait.until(titleIs("We Arrive Here"));

        browsingContext.back();

在 GitHub 上查看完整範例

新增範例

Selenium v4.17

    await browsingContext.back()

在 GitHub 上查看完整範例

新增範例

前進

Selenium v4.16.0

    void canNavigateForwardInTheBrowserHistory() {
        BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());
        browsingContext.navigate("https://selenium.dev.org.tw/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();

在 GitHub 上查看完整範例

新增範例

Selenium v4.17

    await browsingContext.forward()

在 GitHub 上查看完整範例

新增範例

瀏覽歷史記錄

Selenium v4.16.0

        BrowsingContext browsingContext = new BrowsingContext(driver, driver.getWindowHandle());
        browsingContext.navigate("https://selenium.dev.org.tw/selenium/web/formPage.html", ReadinessState.COMPLETE);

        wait.until(visibilityOfElementLocated(By.id("imageButton"))).submit();
        wait.until(titleIs("We Arrive Here"));

        browsingContext.traverseHistory(-1);

在 GitHub 上查看完整範例

新增範例

Selenium v4.17

    await browsingContext.traverseHistory(-1)

在 GitHub 上查看完整範例

新增範例

事件

本節包含與瀏覽情境事件相關的 API。

瀏覽情境建立事件

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);

在 GitHub 上查看完整範例

新增範例

Selenium v4.9.2

    const browsingContextInspector = await BrowsingContextInspector(driver)
    await browsingContextInspector.onBrowsingContextCreated((entry) => {
      contextInfo = entry
    })

    await driver.switchTo().newWindow('window')

在 GitHub 上查看完整範例

新增範例

DOM 內容載入事件

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()

在 GitHub 上查看完整範例

新增範例

Selenium v4.9.2

    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://selenium.dev.org.tw/selenium/web/bidi/logEntryAdded.html', 'complete')

在 GitHub 上查看完整範例

新增範例

瀏覽情境載入事件

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://selenium.dev.org.tw/selenium/web/bidi/logEntryAdded.html", ReadinessState.COMPLETE);

            NavigationInfo navigationInfo = future.get(5, TimeUnit.SECONDS);

在 GitHub 上查看完整範例

新增範例

Selenium v4.9.2

    const browsingContextInspector = await BrowsingContextInspector(driver)

    await browsingContextInspector.onBrowsingContextLoaded((entry) => {
      navigationInfo = entry
    })
    const browsingContext = await BrowsingContext(driver, {
      browsingContextId: await driver.getWindowHandle(),
    })
    await browsingContext.navigate('https://selenium.dev.org.tw/selenium/web/bidi/logEntryAdded.html', 'complete')

在 GitHub 上查看完整範例

新增範例

導航開始事件

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://selenium.dev.org.tw/selenium/web/bidi/logEntryAdded.html", ReadinessState.COMPLETE);

            NavigationInfo navigationInfo = future.get(5, TimeUnit.SECONDS);

在 GitHub 上查看完整範例

新增範例

片段導航事件

Selenium v4.15

        try (BrowsingContextInspector inspector = new BrowsingContextInspector(driver)) {
            CompletableFuture<NavigationInfo> future = new CompletableFuture<>();

            BrowsingContext context = new BrowsingContext(driver, driver.getWindowHandle());
            context.navigate("https://selenium.dev.org.tw/selenium/web/linked_image.html", ReadinessState.COMPLETE);

            inspector.onFragmentNavigated(future::complete);

            context.navigate("https://selenium.dev.org.tw/selenium/web/linked_image.html#linkToAnchorOnThisPage", ReadinessState.COMPLETE);

            NavigationInfo navigationInfo = future.get(5, TimeUnit.SECONDS);

在 GitHub 上查看完整範例

新增範例

Selenium v4.15.0

    const browsingContextInspector = await BrowsingContextInspector(driver)

    const browsingContext = await BrowsingContext(driver, {
      browsingContextId: await driver.getWindowHandle(),
    })
    await browsingContext.navigate('https://selenium.dev.org.tw/selenium/web/linked_image.html', 'complete')

    await browsingContextInspector.onFragmentNavigated((entry) => {
      navigationInfo = entry
    })

    await browsingContext.navigate('https://selenium.dev.org.tw/selenium/web/linked_image.html#linkToAnchorOnThisPage', 'complete')

在 GitHub 上查看完整範例

新增範例

使用者提示開啟事件

Selenium v4.15

        try (BrowsingContextInspector inspector = new BrowsingContextInspector(driver)) {
            CompletableFuture<NavigationInfo> future = new CompletableFuture<>();

            BrowsingContext context = new BrowsingContext(driver, driver.getWindowHandle());
            context.navigate("https://selenium.dev.org.tw/selenium/web/linked_image.html", ReadinessState.COMPLETE);

            inspector.onFragmentNavigated(future::complete);

            context.navigate("https://selenium.dev.org.tw/selenium/web/linked_image.html#linkToAnchorOnThisPage", ReadinessState.COMPLETE);

            NavigationInfo navigationInfo = future.get(5, TimeUnit.SECONDS);

在 GitHub 上查看完整範例

新增範例

使用者提示關閉事件

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://selenium.dev.org.tw/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());

在 GitHub 上查看完整範例

新增範例

瀏覽情境銷毀事件

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());

在 GitHub 上查看完整範例

新增範例

Selenium v4.18.0

    const browsingContextInspector = await BrowsingContextInspector(driver)
    await browsingContextInspector.onBrowsingContextDestroyed((entry) => {
      contextInfo = entry
    })

    await driver.switchTo().newWindow('window')

    const windowHandle = await driver.getWindowHandle()
    await driver.close()

在 GitHub 上查看完整範例

新增範例

上次修改時間：2024年8月4日： refactor(js): 更新程式碼範例以使用 mocha 並修正行號 (d4adebb67ba)

SeleniumConf 2025 開放註冊 | 3月26–28日 | 親臨現場參與！立即註冊！

瀏覽情境

命令

開啟新視窗

開啟新分頁

使用現有的視窗控制代碼

使用參考瀏覽情境開啟視窗

使用參考瀏覽情境開啟分頁

導航至 URL

導航至具有就緒狀態的 URL

取得瀏覽情境樹狀結構

取得具有深度的瀏覽情境樹狀結構

取得所有頂層瀏覽情境

關閉分頁/視窗

啟用瀏覽情境

重新載入瀏覽情境

處理使用者提示

擷取螢幕截圖

擷取視口螢幕截圖

擷取元素螢幕截圖

設定視口

列印頁面

返回

前進

瀏覽歷史記錄

事件

瀏覽情境建立事件

DOM 內容載入事件

瀏覽情境載入事件

導航開始事件

片段導航事件

使用者提示開啟事件

使用者提示關閉事件

瀏覽情境銷毀事件

開發夥伴

Selenium 層級贊助商

支持 Selenium 專案