UI.context()

Scopes execution of a block of test commands to a specific DOM subtree or iframe.

UI.context() limits element targeting to the specified scope, making it useful on pages with repeated or similar elements.

It is also necessary for interacting with content inside an iframe, which exists in an isolated context from the top-level page. To interact with nested iframes, UI.context() can be nested.

After the UI.context() block completes, targeting automatically returns to the previous context.

Usage

UI.context(selector, ()=>{
  // test code
})

Parameters

Parameter	Type	Description
selector	string	Element or iframe to scope all commands to (by visible text, CSS selector, or XPath).
fn	function	A function containing the test commands to run within the scoped context.

Example

Interacting with elements in an iframe

I.click("Continue")
I.see("Payment method")

// executes within the iframe
UI.context("#payment-iframe", () => {
  I.fill("Card number", "4242 4242 4242 4242")
  I.fill("Expiry date", "12/28")
  I.fill("CVC", "123")
})

// back at the top-level page
I.click("Continue")

In this example, the test switches execution into the iframe identified by #payment-iframe to fill in the credit card details, and then returns to the top-level page to continue.

Scoping commands to a container element

// click on "Log in" button on the page
// which opens a modal
I.click("Log In")
I.see(".modal")

// fills in the form and 
// clicks on "Log in" button within the modal
UI.context(".modal", () => {
  I.fill("Username", "john")
  I.fill("Password", "password123!")
  I.click("Log In") 
})

In this example, UI.context() scopes all commands to the .modal element, ensuring that the I.click("Log In") command targets the button within the modal rather than a similarly named element elsewhere on the page.