Class BrowserActions

java.lang.Object
com.shaft.driver.internal.FluentWebDriverAction
com.shaft.gui.browser.BrowserActions
All Implemented Interfaces:
BrowserActionsContract
public class BrowserActions extends FluentWebDriverAction implements BrowserActionsContract
Provides a fluent API for performing browser-level actions such as navigation, window management, cookie handling, network interception, and accessibility validation. Instances are typically obtained via driver.browser() on a SHAFT.GUI.WebDriver instance.

Example usage: 

SHAFT.GUI.WebDriver driver = new SHAFT.GUI.WebDriver();
driver.browser()
      .navigateToURL("https://example.com")
      .and().maximizeWindow();

  • Constructor Details

    • BrowserActions

      public BrowserActions()
      Creates a new BrowserActions instance and initializes the underlying driver using the framework's default driver factory configuration.

    • BrowserActions

      public BrowserActions(org.openqa.selenium.WebDriver driver)
      Creates a new BrowserActions instance wrapping the provided WebDriver.
      Parameters:
      driver - the WebDriver instance to use for browser actions

    • BrowserActions

      public BrowserActions(org.openqa.selenium.WebDriver driver, boolean isSilent)
      Creates a new BrowserActions instance wrapping the provided WebDriver, with control over whether reporting output is suppressed.
      Parameters:
      driver - the WebDriver instance to use for browser actions
      isSilent - when true, step reporting is suppressed for this instance

    • BrowserActions

      public BrowserActions(DriverFactoryHelper helper)
      Creates a new BrowserActions instance backed by an existing DriverFactoryHelper. Use this constructor when integrating with the internal driver lifecycle management.
      Parameters:
      helper - the DriverFactoryHelper that manages the underlying driver instance

  • Method Details

    • and

      public BrowserActions and()
      Description copied from class: FluentWebDriverAction
      Returns this instance to allow fluent (method-chaining) syntax between successive actions. Using .and() improves readability by making multi-step test sequences read like natural language.

      Example: 

      driver.element().type(searchBox, "query")
      .and().browser().captureScreenshot();
      Specified by:
      and in interface BrowserActionsContract
      Overrides:
      and in class FluentWebDriverAction
      Returns:
      this FluentWebDriverAction instance, enabling continued method chaining

    • assertThat

      public WebDriverBrowserValidationsBuilder assertThat()
      Opens a hard-assertion builder scoped to the current browser state. Any assertion failure immediately stops the test.

      Example: 

      driver.browser().assertThat().title().contains("Dashboard");
      Specified by:
      assertThat in interface BrowserActionsContract
      Returns:
      a WebDriverBrowserValidationsBuilder for chaining browser assertions

    • verifyThat

      public WebDriverBrowserValidationsBuilder verifyThat()
      Opens a soft-assertion (verification) builder scoped to the current browser state. Failures are collected and reported at the end of the test rather than stopping it immediately.

      Example: 

      driver.browser().verifyThat().title().contains("Dashboard");
      Specified by:
      verifyThat in interface BrowserActionsContract
      Returns:
      a WebDriverBrowserValidationsBuilder for chaining browser verifications

    • capturePageSnapshot

      public BrowserActions capturePageSnapshot()
      Attempts to capture a page snapshot archive in the format of a .mht file Works only for Chromium based driver instances For other driver types attempts to attach the current page source (for web) or accessibility tree (for mobile)
      Specified by:
      capturePageSnapshot in interface BrowserActionsContract
      Returns:
      a self-reference to be used to chain actions

    • getCurrentURL

      public String getCurrentURL()
      Gets the current page URL and returns it as a string
      Specified by:
      getCurrentURL in interface BrowserActionsContract
      Returns:
      the URL that's currently open in the current page

    • getCurrentWindowTitle

      public String getCurrentWindowTitle()
      Gets the current window title and returns it as a string
      Specified by:
      getCurrentWindowTitle in interface BrowserActionsContract
      Returns:
      the title of the current window

    • getPageSource

      public String getPageSource()
      Gets the current page source and returns it as a string
      Specified by:
      getPageSource in interface BrowserActionsContract
      Returns:
      the source of the current page

    • getWindowHandle

      public String getWindowHandle()
      Gets the current window handle and returns it as a string
      Specified by:
      getWindowHandle in interface BrowserActionsContract
      Returns:
      the window handle for the current window

    • getWindowPosition

      public String getWindowPosition()
      Gets the current window position and returns it as a string
      Specified by:
      getWindowPosition in interface BrowserActionsContract
      Returns:
      the position of the current window

    • getWindowSize

      public String getWindowSize()
      Gets the current window size and returns it as a string
      Specified by:
      getWindowSize in interface BrowserActionsContract
      Returns:
      the size of the current window

    • getWindowHeight

      public String getWindowHeight()
      Gets the current window size and returns it as a string
      Specified by:
      getWindowHeight in interface BrowserActionsContract
      Returns:
      the height of the current window

    • getWindowWidth

      public String getWindowWidth()
      Gets the current window size and returns it as a string
      Specified by:
      getWindowWidth in interface BrowserActionsContract
      Returns:
      the width of the current window

    • openNewTab

      public BrowserActions openNewTab(String targetUrl)
      Opens the target URL in a new browser tab and switches focus to it.
      Specified by:
      openNewTab in interface BrowserActionsContract
      Parameters:
      targetUrl - target URL to open
      Returns:
      a self-reference to be used to chain actions

    • openNewWindow

      public BrowserActions openNewWindow(String targetUrl)
      Opens the target URL in a new browser window and switches focus to it.
      Specified by:
      openNewWindow in interface BrowserActionsContract
      Parameters:
      targetUrl - target URL to open
      Returns:
      a self-reference to be used to chain actions

    • refreshCurrentPage

      public BrowserActions refreshCurrentPage()
      Attempts to refresh the current page
      Specified by:
      refreshCurrentPage in interface BrowserActionsContract
      Returns:
      a self-reference to be used to chain actions

    • closeCurrentWindow

      public void closeCurrentWindow()
      Closes the current browser window
      Specified by:
      closeCurrentWindow in interface BrowserActionsContract

    • maximizeWindow

      public BrowserActions maximizeWindow()
      Maximizes current window size based on screen size minus 5%
      Specified by:
      maximizeWindow in interface BrowserActionsContract
      Returns:
      a self-reference to be used to chain actions

    • setWindowSize

      public BrowserActions setWindowSize(int width, int height)
      Resizes the current window size based on the provided width and height
      Specified by:
      setWindowSize in interface BrowserActionsContract
      Parameters:
      width - the desired new width of the target window
      height - the desired new height of the target window
      Returns:
      a self-reference to be used to chain actions

    • mock

      @Step("Mock HTTP Request") public BrowserActions mock(Predicate<org.openqa.selenium.remote.http.HttpRequest> requestPredicate, org.openqa.selenium.remote.http.HttpResponse mockedResponse)
      Intercepts outgoing HTTP requests matching the given predicate and replaces the actual network response with the provided HttpResponse. Only supported for drivers that implement HasDevTools.

      Example: 

      HttpResponse mocked = new HttpResponse();
mocked.setStatus(200);
driver.browser().mock(req -> req.getUri().contains("/api/user"), mocked);
      Specified by:
      mock in interface BrowserActionsContract
      Parameters:
      requestPredicate - a Predicate that identifies which requests should be intercepted
      mockedResponse - the HttpResponse to return instead of the real network response
      Returns:
      a self-reference to be used to chain actions

    • interceptRequest

      public NetworkInterceptionRequestBuilder<BrowserActions> interceptRequest()
      Starts a fluent browser network interception builder.

      The configured rule is scoped to the current WebDriver session and is cleared automatically when the driver closes. Call clearNetworkInterceptors() to remove all active rules earlier. Only drivers that implement HasDevTools support network interception.

      Example: 

      driver.browser()
      .interceptRequest()
      .get()
      .urlContains("/api/users")
      .respond()
      .statusCode(200)
      .jsonBody("{\"ok\":true}")
      .perform();
      Specified by:
      interceptRequest in interface BrowserActionsContract
      Returns:
      a browser network interception request builder

    • startContractRecording

      public BrowserActions startContractRecording(String contractFilePath, String... urlContains)
      Starts recording selected browser traffic into an HTTP contract.

      Example: 

      driver.browser().startContractRecording("src/test/resources/contracts/checkout.json", "/api/checkout");
driver.browser().navigateToURL("https://shop.example/checkout");
SHAFT.Contracts.stopRecording();
      Specified by:
      startContractRecording in interface BrowserActionsContract
      Parameters:
      contractFilePath - destination JSON contract path
      urlContains - optional URL fragments used to select recorded traffic
      Returns:
      a self-reference to be used to chain actions

    • assertContract

      public BrowserActions assertContract(String contractFilePath, String... urlContains)
      Starts hard-assert validation of live browser responses against an HTTP contract.
      Specified by:
      assertContract in interface BrowserActionsContract
      Parameters:
      contractFilePath - source JSON contract path
      urlContains - optional URL fragments used to select validated traffic
      Returns:
      a self-reference to be used to chain actions

    • verifyContract

      public BrowserActions verifyContract(String contractFilePath, String... urlContains)
      Starts soft-verify validation of live browser responses against an HTTP contract.
      Specified by:
      verifyContract in interface BrowserActionsContract
      Parameters:
      contractFilePath - source JSON contract path
      urlContains - optional URL fragments used to select validated traffic
      Returns:
      a self-reference to be used to chain actions

    • replayContract

      public BrowserActions replayContract(String contractFilePath)
      Replays recorded contract responses through the browser network interceptor.

      Example: 

      driver.browser().replayContract("src/test/resources/contracts/checkout.json");
driver.browser().navigateToURL("https://shop.example/checkout");
      Specified by:
      replayContract in interface BrowserActionsContract
      Parameters:
      contractFilePath - source JSON contract path
      Returns:
      a self-reference to be used to chain actions

    • routeFromHar

      public BrowserActions routeFromHar(String harFilePath)
      Replays recorded HAR (HTTP Archive) responses through the browser network interceptor.

      Example: 

      driver.browser().routeFromHar("src/test/resources/har/checkout.har");
driver.browser().navigateToURL("https://shop.example/checkout");
      Specified by:
      routeFromHar in interface BrowserActionsContract
      Parameters:
      harFilePath - path to a HAR 1.2 JSON file
      Returns:
      a self-reference to be used to chain actions

    • intercept

      @Step("Intercept HTTP Request") public BrowserActions intercept(Predicate<org.openqa.selenium.remote.http.HttpRequest> requestPredicate, org.openqa.selenium.remote.http.HttpResponse mockedResponse)
      Intercepts outgoing HTTP requests matching the given predicate and substitutes the real network response with the provided HttpResponse. Functionally equivalent to mock(Predicate, HttpResponse) but semantically named for interception use-cases. Only supported for drivers that implement HasDevTools.

      Example: 

      HttpResponse stubbed = new HttpResponse();
stubbed.setStatus(503);
driver.browser().intercept(req -> req.getUri().contains("/api/search"), stubbed);
      Specified by:
      intercept in interface BrowserActionsContract
      Parameters:
      requestPredicate - a Predicate that identifies which requests should be intercepted
      mockedResponse - the HttpResponse to return instead of the real network response
      Returns:
      a self-reference to be used to chain actions

    • clearNetworkInterceptors

      @Step("Clear Network Interceptors") public BrowserActions clearNetworkInterceptors()
      Removes all browser network interception rules registered for the current WebDriver session.
      Specified by:
      clearNetworkInterceptors in interface BrowserActionsContract
      Returns:
      a self-reference to be used to chain actions

    • fullScreenWindow

      public BrowserActions fullScreenWindow()
      Resize the window to fill the current screen
      Specified by:
      fullScreenWindow in interface BrowserActionsContract
      Returns:
      a self-reference to be used to chain actions

    • switchToWindow

      public BrowserActions switchToWindow(String nameOrHandle)
      Switches focus to another window
      Specified by:
      switchToWindow in interface BrowserActionsContract
      Parameters:
      nameOrHandle - The name of the window or the handle as returned by ElementActions.getWindowHandle(WebDriver driver)
      Returns:
      a self-reference to be used to chain actions

    • isAlertPresent

      public boolean isAlertPresent()
      Checks whether a browser alert, confirm, or prompt dialog is currently present.
      Specified by:
      isAlertPresent in interface BrowserActionsContract
      Returns:
      true when an alert is present; otherwise false

    • acceptAlert

      public BrowserActions acceptAlert()
      Accepts the current browser alert, confirm, or prompt dialog.
      Specified by:
      acceptAlert in interface BrowserActionsContract
      Returns:
      a self-reference to be used to chain actions

    • dismissAlert

      public BrowserActions dismissAlert()
      Dismisses the current browser alert, confirm, or prompt dialog.
      Specified by:
      dismissAlert in interface BrowserActionsContract
      Returns:
      a self-reference to be used to chain actions

    • getAlertText

      public String getAlertText()
      Gets the current browser alert, confirm, or prompt dialog text.
      Specified by:
      getAlertText in interface BrowserActionsContract
      Returns:
      the alert text

    • typeIntoPromptAlert

      public BrowserActions typeIntoPromptAlert(String text)
      Types text into the current browser prompt dialog.
      Specified by:
      typeIntoPromptAlert in interface BrowserActionsContract
      Parameters:
      text - text to type into the prompt
      Returns:
      a self-reference to be used to chain actions

    • addCookie

      public BrowserActions addCookie(String key, String value)
      Adds a cookie to the current browsing context.
      Specified by:
      addCookie in interface BrowserActionsContract
      Parameters:
      key - The cookie's name
      value - The cookie's name
      Returns:
      a self-reference to be used to chain actions

    • importCookiesFrom

      public BrowserActions importCookiesFrom(SHAFT.API api)
      Imports API session cookies into the current browser context.
      Parameters:
      api - the API session to read cookies from
      Returns:
      a self-reference to be used to chain actions

    • importCookiesFrom

      public BrowserActions importCookiesFrom(SHAFT.API api, String domainFilter, String pathFilter)
      Imports matching API session cookies into the current browser context.
      Parameters:
      api - the API session to read cookies from
      domainFilter - optional exact cookie domain filter; pass null or blank to import every domain
      pathFilter - optional exact cookie path filter; pass null or blank to import every path
      Returns:
      a self-reference to be used to chain actions

    • importHeaderToLocalStorage

      public BrowserActions importHeaderToLocalStorage(SHAFT.API api, String headerName, String storageKey)
      Copies a selected API session header into localStorage.
      Parameters:
      api - the API session to read headers from
      headerName - the header name to copy
      storageKey - the localStorage key to write
      Returns:
      a self-reference to be used to chain actions

    • saveStorageState

      public BrowserActions saveStorageState(String filePath)
      Saves the current browser cookies, localStorage, and sessionStorage to a JSON file.

      Example: 

      driver.browser().saveStorageState("target/auth-state.json");
      Parameters:
      filePath - target JSON file path
      Returns:
      a self-reference to be used to chain actions

    • loadStorageState

      public BrowserActions loadStorageState(String filePath)
      Loads browser cookies, localStorage, and sessionStorage from a JSON file.

      Navigate to the target origin before loading storage so browser cookie domain rules can apply. Example: 

      driver.browser()
      .navigateToURL("https://example.com")
      .and().loadStorageState("target/auth-state.json");
      Parameters:
      filePath - source JSON file path
      Returns:
      a self-reference to be used to chain actions

    • goOffline

      public BrowserActions goOffline()
      Enables offline network mode for DevTools-capable browsers.

      Unsupported drivers keep the test running and add deterministic trace metadata. Example: 

      driver.browser().goOffline();
      Returns:
      a self-reference to be used to chain actions

    • restoreNetwork

      public BrowserActions restoreNetwork()
      Restores default network mode and clears blocked URL patterns for DevTools-capable browsers.

      Example: 

      driver.browser().restoreNetwork();
      Returns:
      a self-reference to be used to chain actions

    • throttleNetwork

      public BrowserActions throttleNetwork(long latencyMs, long downloadKbps, long uploadKbps)
      Applies fixed latency and throughput limits for DevTools-capable browsers.

      Example: 

      driver.browser().throttleNetwork(250, 64, 32);
      Parameters:
      latencyMs - network latency in milliseconds
      downloadKbps - download throughput in kilobits per second
      uploadKbps - upload throughput in kilobits per second
      Returns:
      a self-reference to be used to chain actions

    • blockNetworkResources

      public BrowserActions blockNetworkResources(String... urlPatterns)
      Blocks browser requests matching DevTools URL patterns.

      Example: 

      driver.browser().blockNetworkResources("*.png", "*.jpg");
      Parameters:
      urlPatterns - DevTools URL patterns to block
      Returns:
      a self-reference to be used to chain actions

    • getCookie

      public org.openqa.selenium.Cookie getCookie(String cookieName)
      Gets a cookie with a given name.
      Specified by:
      getCookie in interface BrowserActionsContract
      Parameters:
      cookieName - The cookie's name.
      Returns:
      the cookie.

    • getAllCookies

      public Set<org.openqa.selenium.Cookie> getAllCookies()
      Gets all cookies for the current browsing context.
      Specified by:
      getAllCookies in interface BrowserActionsContract
      Returns:
      A Set of cookies for the current browsing context.

    • getCookieDomain

      public String getCookieDomain(String cookieName)
      Gets the cookie domain.
      Specified by:
      getCookieDomain in interface BrowserActionsContract
      Parameters:
      cookieName - The cookie's name.
      Returns:
      te cookie domain;

    • getCookieValue

      public String getCookieValue(String cookieName)
      Gets the cookie value.
      Specified by:
      getCookieValue in interface BrowserActionsContract
      Parameters:
      cookieName - The cookie's name.
      Returns:
      the cookie value;

    • getCookiePath

      public String getCookiePath(String cookieName)
      Gets the cookie path.
      Specified by:
      getCookiePath in interface BrowserActionsContract
      Parameters:
      cookieName - The cookie's name.
      Returns:
      the cookie path;

    • deleteCookie

      public BrowserActions deleteCookie(String cookieName)
      Deletes the cookie data matching with the provided cookie name for the current browsing context.
      Specified by:
      deleteCookie in interface BrowserActionsContract
      Parameters:
      cookieName - The name of the cookie to delete.
      Returns:
      a self-reference to be used to chain actions.

    • deleteAllCookies

      public BrowserActions deleteAllCookies()
      Deletes all the cookies of the current browsing context.
      Specified by:
      deleteAllCookies in interface BrowserActionsContract
      Returns:
      a self-reference to be used to chain actions.

    • captureScreenshot

      public BrowserActions captureScreenshot()
      Use this action to return a full page screenshot. This is a synonym to captureScreenshot(Screenshots type) if you pass `Screenshots.FULL`
      Specified by:
      captureScreenshot in interface BrowserActionsContract
      Returns:
      a self-reference for chainable actions

    • captureScreenshot

      public BrowserActions captureScreenshot(Screenshots type)
      Use this action to return a page screenshot. If you want to capture a screenshot then use this method instead
      Specified by:
      captureScreenshot in interface BrowserActionsContract
      Parameters:
      type - can either be `Screenshots.FULL`, or `Screenshots.VIEWPORT`
      Returns:
      a self-reference for chainable actions

    • captureSnapshot

      public BrowserActions captureSnapshot()
      Use this action to return a page snapshot. A page snapshot is a single .mht file that contains the full page DOM and any related assets to help you view the page as a whole. If you want to capture a screenshot then use this method instead @see FluentBrowserActions#captureScreenshot()
      Specified by:
      captureSnapshot in interface BrowserActionsContract
      Returns:
      a self-reference for chainable actions

    • generateLightHouseReport

      public void generateLightHouseReport()
      Generates a Google Lighthouse performance report for the currently open page. The report is attached to the Allure test report for review after the test run.

      Example: 

      driver.browser().navigateToURL("https://example.com")
      .and().generateLightHouseReport();
      Specified by:
      generateLightHouseReport in interface BrowserActionsContract

    • waitForLazyLoading

      public BrowserActions waitForLazyLoading()
      Waits for the page to finish lazy-loading by polling JavaScript readiness conditions. Use this after actions that trigger dynamic content loading (e.g., infinite scrolling or deferred script execution).

      Example: 

      driver.browser().navigateToURL("https://example.com")
      .and().waitForLazyLoading();
      Specified by:
      waitForLazyLoading in interface BrowserActionsContract
      Returns:
      a self-reference to be used to chain actions

    • scrollToLoadAll

      public BrowserActions scrollToLoadAll()
      Explicitly sweeps the current page with bounded progressive scrolling (viewport-height steps, up to timeouts.lazyLoadingScrollSweepMaxSteps, default 20), waiting for lazy-loading readiness between steps, to force scroll-triggered content (infinite lists, IntersectionObserver sections that only hydrate once visible) to fully load before full-page assertions or screenshots. Stops early once the page stops growing and the viewport bottom has been reached (ScrollSweepPlanner).

      Use this right before assertions or screenshots on pages known to lazy-load additional content on scroll -- it is never invoked automatically from any readiness wait, since sweeping the whole page is not a safe default before an arbitrary action.

      Mutates scroll position while it runs: the page is scrolled down step by step, then restored to its original scroll position when the sweep finishes.

      Example: 

      driver.browser().navigateToURL("https://example.com/infinite-list")
      .and().scrollToLoadAll()
      .and().captureScreenshot();
      Specified by:
      scrollToLoadAll in interface BrowserActionsContract
      Returns:
      a self-reference to be used to chain actions

    • getContext

      public String getContext()
      Returns the handle for currently active context. This can be used to switch to this context at a later time.
      Specified by:
      getContext in interface BrowserActionsContract
      Returns:
      The current context handle

    • setContext

      public BrowserActions setContext(String context)
      Switches focus to another context
      Specified by:
      setContext in interface BrowserActionsContract
      Parameters:
      context - The name of the context or the handle as returned by ElementActions.getContext(WebDriver driver)
      Returns:
      a self-reference to be used to chain actions

    • getWindowHandles

      public List<String> getWindowHandles()
      Returns a list of unique handles for all the currently open windows. This can be used to switch to any of these windows at a later time.
      Specified by:
      getWindowHandles in interface BrowserActionsContract
      Returns:
      list of window handles

    • getContextHandles

      public List<String> getContextHandles()
      Returns a list of unique handles for all the currently open contexts. This can be used to switch to any of these contexts at a later time.
      Specified by:
      getContextHandles in interface BrowserActionsContract
      Returns:
      list of context handles

    • accessibility

      public AccessibilityActions accessibility()
      Provides access to accessibility testing actions for the current browser session.

      This method returns an AccessibilityActions instance that can be used to perform automated accessibility checks and generate reports for the current page.

      Example usage:

      AccessibilityActions actions = browserActions.accessibility();
actions.analyzePageAccessibility("HomePage");
      Specified by:
      accessibility in interface BrowserActionsContract
      Returns:
      an AccessibilityActions object tied to the current browser session