com.shaft.gui.browser.internal.BrowserActionsHelper

public class BrowserActionsHelper extends Object

Internal helper class for browser actions within the SHAFT framework. Provides utility methods for navigating URLs, reporting pass/fail results, maximizing browser windows, capturing page snapshots, and formatting URLs for basic authentication.

Instances are typically created per action with a isSilent flag that suppresses Allure report entries when set to true.

Example usage:

BrowserActionsHelper helper = new BrowserActionsHelper(false);
helper.navigateToNewUrl(driver, currentUrl, "https://example.com", "");

Field Summary

Fields

Modifier and Type

Field

Description

static final int

NAVIGATION_TIMEOUT_INTEGER

The navigation timeout in seconds, sourced from SHAFT.Properties.timeouts.browserNavigationTimeout().
Constructor Summary

Constructors

Constructor

Description

BrowserActionsHelper(boolean isSilent)

Creates a new BrowserActionsHelper.
Method Summary

Modifier and Type

Method

Description

org.openqa.selenium.Dimension

attemptMaximizeUsingSeleniumWebDriver(org.openqa.selenium.WebDriver driver, String executionAddress, String targetBrowserName, String targetOperatingSystem)

Attempts to maximize the browser window using the Selenium WebDriver WebDriver.Window.maximize() method.

org.openqa.selenium.Dimension

attemptMaximizeUsingSeleniumWebDriverManageWindow(org.openqa.selenium.WebDriver driver, int width, int height)

Maximizes the browser window by explicitly setting its position to (0, 0) and its size to the provided dimensions using the WebDriver.Window API.

org.openqa.selenium.Dimension

attemptMaximizeUsingToolkitAndJavascript(org.openqa.selenium.WebDriver driver, int width, int height)

Attempts to maximize the browser window by reading the physical screen dimensions from Toolkit and resizing the window accordingly.

String

capturePageSnapshot(org.openqa.selenium.WebDriver driver)

Captures a snapshot of the current page.

void

checkNavigationWasSuccessful(org.openqa.selenium.WebDriver driver, String initialURL, String targetUrl, String targetUrlAfterRedirection)

Waits until the browser URL reflects a successful navigation away from the initial URL, and optionally waits until it contains the expected target URL.

void

confirmThatWebsiteIsNotDown(org.openqa.selenium.WebDriver driver, String targetUrl)

Verifies that the page currently loaded in the browser is not a network-error page.

void

failAction(Exception... rootCauseException)

Reports a failed browser action without a WebDriver instance or test data.

void

failAction(org.openqa.selenium.WebDriver driver, String testData, Exception... rootCauseException)

Reports a failed browser action, capturing a screenshot when a driver is provided.

void

failAction(org.openqa.selenium.WebDriver driver, String actionName, String testData, Exception... rootCauseException)

Reports a failed browser action with an explicit action name, then throws a test failure.

String

formatUrlForBasicAuthentication(String username, String password, String targetUrl)

Embeds Basic-Authentication credentials into a URL so that the browser submits them automatically on navigation without requiring an interactive prompt.

String

getDomainNameFromUrl(String url)

Extracts the registrable (top-private) domain name from a full URL.

void

navigateToNewUrl(org.openqa.selenium.WebDriver driver, String initialURL, String targetUrl, String targetUrlAfterRedirection)

Navigates the browser to a new URL.

void

passAction(String testData)

Reports a successful browser action without a WebDriver instance.

void

passAction(org.openqa.selenium.WebDriver driver, String testData)

Reports a successful browser action, attaching a screenshot when a driver is provided.

void

passAction(org.openqa.selenium.WebDriver driver, String actionName, String testData)

Reports a successful browser action with an explicit action name.

void

waitUntilUrlIsNot(org.openqa.selenium.WebDriver driver, String initialURL)

Waits until the browser URL is no longer equal to the given initial URL.

Methods inherited from class Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- NAVIGATION_TIMEOUT_INTEGER
  
  public static final int NAVIGATION_TIMEOUT_INTEGER
  
  The navigation timeout in seconds, sourced from SHAFT.Properties.timeouts.browserNavigationTimeout(). Used as the maximum wait duration for URL-change conditions.
Constructor Details
- BrowserActionsHelper
  
  public BrowserActionsHelper(boolean isSilent)
  
  Creates a new BrowserActionsHelper.
  
  Parameters:
  
  isSilent - when true, action results are not written to the Allure report; useful for internal/utility navigations that should not appear in test output
Method Details
- passAction
  public void passAction(String testData)
  
  Reports a successful browser action without a WebDriver instance. The action name is derived from the caller's method name.
  Example:
  passAction("https://example.com");
  
  Parameters:
  
  testData - descriptive data associated with the action (e.g. the URL navigated to)
- passAction
  public void passAction(org.openqa.selenium.WebDriver driver, String testData)
  
  Reports a successful browser action, attaching a screenshot when a driver is provided. The action name is derived from the caller's method name.
  Example:
  passAction(driver, "Page title was correct");
  
  Parameters:
  
  driver - the active WebDriver instance used to capture a screenshot, or null
  
  testData - descriptive data associated with the action
- passAction
  public void passAction(org.openqa.selenium.WebDriver driver, String actionName, String testData)
  
  Reports a successful browser action with an explicit action name.
  Example:
  passAction(driver, "navigateToURL", "https://example.com");
  
  Parameters:
  
  driver - the active WebDriver instance used to capture a screenshot, or null
  
  actionName - the display name of the action as it should appear in the report
  
  testData - descriptive data associated with the action
- failAction
  public void failAction(Exception... rootCauseException)
  
  Reports a failed browser action without a WebDriver instance or test data. The action name is derived from the caller's method name.
  Example:
  failAction(rootCauseException);
  
  Parameters:
  
  rootCauseException - optional root-cause exception(s) to include in the report
- failAction
  public void failAction(org.openqa.selenium.WebDriver driver, String testData, Exception... rootCauseException)
  
  Reports a failed browser action, capturing a screenshot when a driver is provided. The action name is derived from the caller's method name.
  Example:
  failAction(driver, "Navigation failed", rootCauseException);
  
  Parameters:
  
  driver - the active WebDriver instance used to capture a screenshot, or null
  
  testData - descriptive data associated with the failure
  
  rootCauseException - optional root-cause exception(s) to include in the report
- failAction
  public void failAction(org.openqa.selenium.WebDriver driver, String actionName, String testData, Exception... rootCauseException)
  
  Reports a failed browser action with an explicit action name, then throws a test failure.
  Example:
  failAction(driver, "navigateToURL", "https://example.com", rootCauseException);
  
  Parameters:
  
  driver - the active WebDriver instance used to capture a screenshot, or null
  
  actionName - the display name of the action as it should appear in the report
  
  testData - descriptive data associated with the failure
  
  rootCauseException - optional root-cause exception(s) to include in the report
- confirmThatWebsiteIsNotDown
  public void confirmThatWebsiteIsNotDown(org.openqa.selenium.WebDriver driver, String targetUrl)
  
  Verifies that the page currently loaded in the browser is not a network-error page. Waits up to NAVIGATION_TIMEOUT_INTEGER seconds using a fluent wait, checking well-known browser error message strings (e.g. "This site can't be reached").
  Example:
  helper.confirmThatWebsiteIsNotDown(driver, "https://example.com");
  
  Parameters:
  
  driver - the active WebDriver instance
  
  targetUrl - the URL that was navigated to, used in the failure message if an error page is detected
- navigateToNewUrl
  public void navigateToNewUrl(org.openqa.selenium.WebDriver driver, String initialURL, String targetUrl, String targetUrlAfterRedirection)
  
  Navigates the browser to a new URL. Handles local file paths by prepending the file:// scheme, and prefers the W3C BiDi BrowsingContext API for navigation when available. Falls back to the classic WebDriver.navigate() API for non-BiDi drivers or on timeout.
  Example:
  helper.navigateToNewUrl(driver, "about:blank", "https://example.com", "https://example.com/home");
  
  Parameters:
  
  driver - the active WebDriver instance
  
  initialURL - the URL the browser was at before navigation (used for wait conditions)
  
  targetUrl - the URL to navigate to
  
  targetUrlAfterRedirection - the expected final URL after any server-side redirects; pass the same value as targetUrl if no redirect is expected
- checkNavigationWasSuccessful
  public void checkNavigationWasSuccessful(org.openqa.selenium.WebDriver driver, String initialURL, String targetUrl, String targetUrlAfterRedirection)
  
  Waits until the browser URL reflects a successful navigation away from the initial URL, and optionally waits until it contains the expected target URL.
  Example:
  helper.checkNavigationWasSuccessful(driver, "about:blank", "https://example.com", "https://example.com/home");
  
  Parameters:
  
  driver - the active WebDriver instance
  
  initialURL - the URL before navigation began
  
  targetUrl - the URL that was requested
  
  targetUrlAfterRedirection - the expected final URL after any server-side redirect; when different from targetUrl, the method also waits for the URL to contain this value
- waitUntilUrlIsNot
  public void waitUntilUrlIsNot(org.openqa.selenium.WebDriver driver, String initialURL)
  
  Waits until the browser URL is no longer equal to the given initial URL. Times out after NAVIGATION_TIMEOUT_INTEGER seconds, failing the test if the URL does not change.
  Example:
  helper.waitUntilUrlIsNot(driver, "about:blank");
  
  Parameters:
  
  driver - the active WebDriver instance
  
  initialURL - the URL that the browser should navigate away from
- attemptMaximizeUsingSeleniumWebDriver
  public org.openqa.selenium.Dimension attemptMaximizeUsingSeleniumWebDriver(org.openqa.selenium.WebDriver driver, String executionAddress, String targetBrowserName, String targetOperatingSystem)
  
  Attempts to maximize the browser window using the Selenium WebDriver WebDriver.Window.maximize() method. This is the preferred approach for most browser/OS combinations, but is skipped for Chrome on macOS in local execution (known limitation).
  Example:
  Dimension size = helper.attemptMaximizeUsingSeleniumWebDriver(driver, "local", "GoogleChrome", "Windows");
  
  Parameters:
  
  driver - the active WebDriver instance
  
  executionAddress - the grid/cloud address, or "local" for local execution
  
  targetBrowserName - the browser name (e.g. "GoogleChrome")
  
  targetOperatingSystem - the OS name (e.g. "Windows", "Mac")
  
  Returns:
  
  the window Dimension after the maximize attempt
- attemptMaximizeUsingToolkitAndJavascript
  public org.openqa.selenium.Dimension attemptMaximizeUsingToolkitAndJavascript(org.openqa.selenium.WebDriver driver, int width, int height)
  
  Attempts to maximize the browser window by reading the physical screen dimensions from Toolkit and resizing the window accordingly. Falls back to JavaScript execution when running in a headless environment where Toolkit throws HeadlessException.
  Example:
  Dimension size = helper.attemptMaximizeUsingToolkitAndJavascript(driver, 1920, 1080);
  
  Parameters:
  
  driver - the active WebDriver instance
  
  width - the fallback width to use when the screen size cannot be determined
  
  height - the fallback height to use when the screen size cannot be determined
  
  Returns:
  
  the window Dimension after the resize attempt
- attemptMaximizeUsingSeleniumWebDriverManageWindow
  public org.openqa.selenium.Dimension attemptMaximizeUsingSeleniumWebDriverManageWindow(org.openqa.selenium.WebDriver driver, int width, int height)
  
  Maximizes the browser window by explicitly setting its position to (0, 0) and its size to the provided dimensions using the WebDriver.Window API.
  Example:
  Dimension size = helper.attemptMaximizeUsingSeleniumWebDriverManageWindow(driver, 1920, 1080);
  
  Parameters:
  
  driver - the active WebDriver instance
  
  width - the desired window width in pixels
  
  height - the desired window height in pixels
  
  Returns:
  
  the window Dimension after the resize
- capturePageSnapshot
  public String capturePageSnapshot(org.openqa.selenium.WebDriver driver)
  
  Captures a snapshot of the current page. For Chromium-based browsers the Chrome DevTools Protocol Page.captureSnapshot command is used to produce a full MHTML snapshot; for all other browsers the standard WebDriver.getPageSource() is used as a fallback.
  Example:
  String snapshot = helper.capturePageSnapshot(driver);
  
  Parameters:
  
  driver - the active WebDriver instance, or null to fall back directly to a page-source capture
  
  Returns:
  
  the serialised page data as a String (MHTML or HTML source)
- formatUrlForBasicAuthentication
  public String formatUrlForBasicAuthentication(String username, String password, String targetUrl)
  
  Embeds Basic-Authentication credentials into a URL so that the browser submits them automatically on navigation without requiring an interactive prompt. Credentials are percent-encoded via URLEncoder to handle special characters.
  Example:
  String authUrl = helper.formatUrlForBasicAuthentication("admin", "p@ssw0rd", "https://example.com/secure"); // returns "https://admin:p%40ssw0rd@example.com/secure"
  
  Parameters:
  
  username - the username for Basic Authentication
  
  password - the password for Basic Authentication
  
  targetUrl - the target URL (must start with http:// or https://)
  
  Returns:
  
  the URL with embedded Basic-Auth credentials
- getDomainNameFromUrl
  public String getDomainNameFromUrl(String url)
  
  Extracts the registrable (top-private) domain name from a full URL. Uses the Guava InternetDomainName class to determine the public suffix and top-level domain.
  Example:
  String domain = helper.getDomainNameFromUrl("https://www.example.co.uk/page"); // returns "example.co.uk"
  
  Parameters:
  
  url - the full URL string to extract the domain from
  
  Returns:
  
  the registrable domain name (e.g. "example.co.uk")

Class BrowserActionsHelper

Field Summary

Constructor Summary

Method Summary

Methods inherited from class Object

Field Details

NAVIGATION_TIMEOUT_INTEGER

Constructor Details

BrowserActionsHelper

Method Details

passAction

passAction

passAction

failAction

failAction

failAction

confirmThatWebsiteIsNotDown

navigateToNewUrl

checkNavigationWasSuccessful

waitUntilUrlIsNot

attemptMaximizeUsingSeleniumWebDriver

attemptMaximizeUsingToolkitAndJavascript

attemptMaximizeUsingSeleniumWebDriverManageWindow

capturePageSnapshot

formatUrlForBasicAuthentication

getDomainNameFromUrl