Use Browser Window

The Use Browser Window building block switches focus to a specific web browser window during web automation. This block only works with browser windows opened using Start Web Browser. Multiple browser windows are not supported by Selenium Grid or external cloud providers such as Sauce Labs and BrowserStack.

Note: The screenshot on this page uses the Elegance Design, introduced in 2025.3. If you are using an earlier version, your layout may look different.

Quick-start

1. Drag Use Browser Window onto the canvas.
2. Connect the block in the flow and specify Get window method, Condition, and Text to find. Optionally add Text fields for dynamic values, and set Use occurred if more than one matching window may exist.
3. Run the flow when it’s ready.

Building block parameters

Parameters

• Block header: The green input connector triggers the block to start executing. The green output connector triggers when the desired browser window has been found and focus has been set on it. You can rename the block by double-clicking the header text and typing a new title.

• Get window method: Selects how the block finds the desired browser window. After selecting a method, you must also set Condition and Text to find.

  • By page title: Finds a window based on the loaded page’s title.
  • By page URL: Finds a window based on the loaded page’s URL.
  • By page content: Finds a window based on the loaded page’s content.

• Condition: Defines how the selected Get window method is matched against Text to find.

  • Equals: Requires an exact match.
  • Contains: Matches when the field contains the entered text.
  • Starts with: Matches when the field starts with the entered text.

• Text to find: The text used to find the desired window. This field can contain tokens from Text fields. To insert tokens, right-click and select Insert token.

• Text fields: Stores key–value pairs that can be inserted into Text to find via Insert token. Fields can be renamed by double-clicking them, and the corresponding tokens update automatically.

• Add field: Adds a new field that can be used as a token in Text to find.

• Browser window: Outputs a handle to the browser window once it is found and focus is set. Use this handle to direct other web building blocks to operate on a specific window.

• Not found: Triggers if the browser window is not found before the timeout behavior completes. This is typically used to branch the flow or explicitly fail a case by linking it to a Fail block.

• Use occurred: Selects which occurrence to use if more than one browser window matches the criteria. Select All to iterate through all occurrences; when All is selected, Current index and Completed are shown.

• Current index: Outputs the current index while iterating through all matching browser windows.

• Completed: Triggers when iteration through all matching browser windows has completed.

• Default timeout: Controls whether the block uses the default timeout from the flow settings or a custom timeout value.

• Timeout (sec): Sets the maximum time spent finding and setting focus on the browser window before the block gives up and triggers Not found. This field is used when Default timeout is not selected.

Note: All cases have a global timeout configured in the Settings panel. This is unrelated to the timeout of a single building block. However, a running case will automatically be cancelled if it runs for longer than the global timeout.

Resources