withFrame

Select a frame by its (zero-based) index and switch the driver's context to it.

Once the frame has been selected, all subsequent calls on the WebDriver interface are made to that frame till the end of iFrameContext.

If a exception is thrown inside iFrameContext, the driver will return to its default context.

Browser.drive(driverFactory) {
    // Given I navigate to the page under test, which contains three IFrames
    to(pageWithIFramesUrl)

    // And I'm in the context of the page
    assertEquals(`$`("h1", 0).text, "Page with IFrames")

    // When I change the driver's context to the second IFrame
    withFrame(1) {
        // Then I should be able to interact with such IFrame
        assertEquals(
            `$`(".tag-home__item", 0).text.trim(),
            "The search engine that doesn't track you. Learn More.")
    }

    // And I should return into the context of the page at the end of the `withFrame` method
    assertEquals(`$`("h1", 0).text, "Page with IFrames")
}

Parameters

index - (zero-based) index.

iFrameContext - here you can interact with the given IFrame.

Exceptions

org.openqa.selenium.NoSuchFrameException - If the frame cannot be found.

Select a frame by its name or ID. Frames located by matching name attributes are always given precedence over those matched by ID.

Once the frame has been selected, all subsequent calls on the WebDriver interface are made to that frame till the end of iFrameContext.

If a exception is thrown inside iFrameContext, the driver will return to its default context.

Browser.drive(driverFactory) {
    // Given I navigate to the page under test, which contains three IFrames
    to(pageWithIFramesUrl)

    // And I'm in the context of the page
    assertEquals(`$`("h1", 0).text, "Page with IFrames")

    // When I change the driver's context to the searx.me IFrame
    withFrame("searx-iframe") {
        // Then I should be able to interact with such IFrame
        assertEquals(`$`("#main-logo", 0).text.trim(), "searx")
    }

    // And I should return into the context of the page at the end of the `withFrame` method
    assertEquals(`$`("h1", 0).text, "Page with IFrames")
}

Parameters

nameOrId - the name of the frame window, the id of the <frame> or <iframe> element, or the (zero-based) index.

iFrameContext - here you can interact with the given IFrame.

Exceptions

org.openqa.selenium.NoSuchFrameException - If the frame cannot be found.

Select a frame using its previously located WebElement.

Once the frame has been selected, all subsequent calls on the WebDriver interface are made to that frame till the end of iFrameContext.

If a exception is thrown inside iFrameContext, the driver will return to its default context.

Browser.drive(driverFactory) {
    // Given I navigate to the page under test, which contains three IFrames
    to(pageWithIFramesUrl)

    // And I'm in the context of the page
    assertEquals(`$`("h1", 0).text, "Page with IFrames")

    // When I change the driver's context to the first IFrame
    withFrame(`$`("iframe", 0)) {
        // Then I should be able to interact with such IFrame
        assertEquals(`$`(".overview-header", 0).text, "Try Kotlin")
    }

    // And I should return into the context of the page at the end of the `withFrame` method
    assertEquals(`$`("h1", 0).text, "Page with IFrames")
}

Parameters

webElement - the frame element to switch to.

iFrameContext - here you can interact with the given IFrame.

Exceptions

org.openqa.selenium.NoSuchFrameException - If the frame cannot be found.

Select a frame by its (zero-based) index and switch the driver's context to it.

Once the frame has been selected, all subsequent calls on the WebDriver interface are made to that frame via a Page Object of type T till the end of iFrameContext.

If a exception is thrown inside iFrameContext, the driver will return to its default context.

// Given a Page Object for the page under test, which contains three IFrames
class IndexPage(browser: Browser) : Page(browser) {

    override val url = pageWithIFramesUrl

    override val at = at {
        title == "Page with IFrames"
    }

    val headerText
        get() = `$`("h1", 0).text
}

// And a Page Object for the DuckDuckGo IFrame
class DuckDuckGoHomePage(browser: Browser) : Page(browser) {

    override val at = at {
        `$`(".cw--c > div > a", 0).text.trim() == "About DuckDuckGo"
    }

    val homeFooterText
        get() = `$`(".tag-home__item", 0).text.trim()
}

Browser.drive(driverFactory) {
    // And I navigate to the page under test
    val indexPage = to(::IndexPage)

    // And I'm in the context of such page
    assertEquals(indexPage.headerText, "Page with IFrames")

    // When I change the driver's context to DuckDuckGo IFrame
    withFrame<DuckDuckGoHomePage>(1) {
        // Then I should be able to interact with such IFrame via its Page Object
        assertEquals(homeFooterText, "The search engine that doesn't track you. Learn More.")
    }

    // And I should return into the context of the page under test at the end of the `withFrame` method
    assertEquals(indexPage.headerText, "Page with IFrames")
}

Parameters

T - the Page Object's type.

index - (zero-based) index.

iFrameContext - here you can interact with the given IFrame via a Page Object.

Exceptions

org.openqa.selenium.NoSuchFrameException - If the frame cannot be found.

Select a frame by its name or ID. Frames located by matching name attributes are always given precedence over those matched by ID.

Once the frame has been selected, all subsequent calls on the WebDriver interface are made to that frame via a Page Object of type T till the end of iFrameContext.

If a exception is thrown inside iFrameContext, the driver will return to its default context.

// Given a Page Object for the page under test, which contains three IFrames
class IndexPage(browser: Browser) : Page(browser) {

    override val url = pageWithIFramesUrl

    override val at = at {
        title == "Page with IFrames"
    }

    val headerText
        get() = `$`("h1", 0).text
}

// And a Page Object for the searx.me IFrame
class SearxHomePage(browser: Browser) : Page(browser) {

    override val at = at {
        `$`(".instance > a", 0).text.trim() == "searx.me"
    }

    val logoImageText
        get() = `$`("#main-logo", 0).text
}

Browser.drive(driverFactory) {
    // And I navigate to the page under test
    val indexPage = to(::IndexPage)

    // And I'm in the context of such page
    assertEquals(indexPage.headerText, "Page with IFrames")

    // When I change the driver's context to searx.me IFrame
    withFrame<SearxHomePage>("searx-iframe") {
        // Then I should be able to interact with such IFrame via its Page Object
        assertEquals(logoImageText, "searx")
    }

    // And I should return into the context of the page under test at the end of the `withFrame` method
    assertEquals(indexPage.headerText, "Page with IFrames")
}

Parameters

T - the Page Object's type.

nameOrId - the name of the frame window, the id of the <frame> or <iframe> element, or the (zero-based) index.

iFrameContext - here you can interact with the given IFrame via a Page Object.

Exceptions

org.openqa.selenium.NoSuchFrameException - If the frame cannot be found.

Select a frame using its previously located WebElement.

Once the frame has been selected, all subsequent calls on the WebDriver interface are made to that frame via a Page Object of type T till the end of iFrameContext.

If a exception is thrown inside iFrameContext, the driver will return to its default context.

// Given a Page Object for the page under test, which contains three IFrames
class IndexPage(browser: Browser) : Page(browser) {

    override val url = pageWithIFramesUrl

    override val at = at {
        title == "Page with IFrames"
    }

    val headerText
        get() = `$`("h1", 0).text
}

// And a Page Object for the KotlinLang IFrame
class KotlinLangIndexPage(browser: Browser) : Page(browser) {

    override val at = at {
        `$`("a.global-header-logo", 0).text == "Kotlin"
    }

    val tryKotlinHeaderText
        get() = `$`(".overview-header", 0).text
}

Browser.drive(driverFactory) {
    // And I navigate to the page under test
    val indexPage = to(::IndexPage)

    // And I'm in the context of such page
    assertEquals(indexPage.headerText, "Page with IFrames")

    // When I change the driver's context to KotlinLang IFrame
    withFrame<KotlinLangIndexPage>(`$`("iframe", 0)) {
        // Then I should be able to interact with such IFrame via its Page Object
        assertEquals(tryKotlinHeaderText, "Try Kotlin")
    }

    // And I should return into the context of the page under test at the end of the `withFrame` method
    assertEquals(indexPage.headerText, "Page with IFrames")
}

Parameters

T - the Page Object's type.

webElement - the frame element to switch to.

iFrameContext - here you can interact with the given IFrame via a Page Object.

Exceptions

org.openqa.selenium.NoSuchFrameException - If the frame cannot be found.