Browser Actions
Getting Started
To interact with web pages, create an instance of SHAFT.GUI.WebDriver:
SHAFT.GUI.WebDriver driver = new SHAFT.GUI.WebDriver();
SHAFT detects your configuration from property files. If no properties are set, SHAFT uses sensible defaults.
To close all running driver instances:
driver.quit();
For trust-gated natural-language browser, element, and touch workflows, see Natural Language Actions.
Navigation
Navigate to URL
driver.browser().navigateToURL("https://www.google.com");
Navigates to the specified URL. If the URL matches the current page, it refreshes instead. You can optionally verify the target URL after navigation:
driver.browser().navigateToURL("https://www.google.com/", "google");
Navigate to URL in a New Tab or Window
import org.openqa.selenium.WindowType;
driver.browser().navigateToURL("https://www.google.com", WindowType.TAB);
driver.browser().navigateToURL("https://www.google.com", WindowType.WINDOW);
Navigate Back
driver.browser().navigateBack();
Navigates one step back in the browser history.
Navigate Forward
driver.browser().navigateForward();
Navigates one step forward in the browser history.
Refresh Page
driver.browser().refreshCurrentPage();
Refreshes the current page.
Get Current URL
String currentUrl = driver.browser().getCurrentURL();
Returns the URL of the current page.
Navigate to URL with Basic Authentication
driver.browser().navigateToURLWithBasicAuthentication(
"https://staging.example.com/secure",
"myUsername",
"myPassword",
"https://staging.example.com/dashboard"
);
Navigates to a URL that requires HTTP Basic Authentication. Provide the target URL, credentials, and the expected URL after a successful login. Useful for staging environments and internal tools protected by basic auth.
Window Management
Maximize Window
driver.browser().maximizeWindow();
Maximizes the current browser window.
Full Screen Window
driver.browser().fullScreenWindow();
Sets the current window to full screen mode.
Resize Window
driver.browser().setWindowSize(1440, 900);
Resizes the current window to the specified width and height.
Get Window Size
String windowSize = driver.browser().getWindowSize();
Returns the current window size as a string.
Get Window Title
String title = driver.browser().getCurrentWindowTitle();
Returns the current window title.
Close Current Window
driver.browser().closeCurrentWindow();
Closes the current browser window.
Switch Windows or Tabs
String windowHandle = driver.browser().getWindowHandle();
// ... code that opens a new window ...
driver.browser().switchToWindow(windowHandle); // switch back to the original window
The getWindowHandle() method returns a unique identifier for the current window, which can be used to switch between tabs and windows.
Get Page Source
String pageSource = driver.browser().getPageSource();
Returns the current page source as a string.
Cookies
Add Cookie
driver.browser().addCookie("cookieName", "cookieValue");
Get Cookie
Cookie cookie = driver.browser().getCookie("cookieName");
Get All Cookies
Set<Cookie> cookies = driver.browser().getAllCookies();
Get Cookie Value
String cookieValue = driver.browser().getCookieValue("cookieName");
Get Cookie Domain
String cookieDomain = driver.browser().getCookieDomain("cookieName");
Get Cookie Path
String cookiePath = driver.browser().getCookiePath("cookieName");
Delete Cookie
driver.browser().deleteCookie("cookieName");
Delete All Cookies
driver.browser().deleteAllCookies();
Storage State
Use storage state when a test needs to reuse an authenticated browser session
without repeating the login flow. SHAFT saves cookies, localStorage, and
sessionStorage to a JSON file. saveStorageState()/loadStorageState() are
implemented identically on SHAFT.GUI.WebDriver and SHAFT.GUI.Playwright, so
a file saved from one backend loads on the other.
driver.browser()
.navigateToURL("https://app.example.com")
.and().saveStorageState("target/auth-state.json");
Load storage state after navigating to a compatible origin so browser cookie domain rules can apply.
driver.browser()
.navigateToURL("https://app.example.com")
.and().loadStorageState("target/auth-state.json")
.and().refreshCurrentPage();
Auto-load storage state on driver init
Set SHAFT.Properties.web.storageStatePath (property key storageStatePath)
to a storage-state JSON file and a freshly-initialized driver loads it
automatically, without an explicit loadStorageState() call:
SHAFT.Properties.web.set().storageStatePath("target/auth-state.json");
SHAFT.GUI.WebDriver driver = new SHAFT.GUI.WebDriver();
SHAFT reads the origin recorded inside the storage-state file (falling back
to SHAFT.Properties.web.baseURL() when the file has none) and navigates the
fresh driver there first, since cookies cannot be added for an arbitrary
domain before any page has loaded. This is fail-soft: a missing file, unreadable
origin, or any other load failure is logged as a warning and never fails driver
initialization. See Authentication and session reuse
for the cached-login helper built on top of this property.
Screenshots and Snapshots
Capture Screenshot
driver.browser().captureScreenshot();
Captures a screenshot and attaches it to the Allure report.
captureSnapshot() vs capturePageSnapshot()
SHAFT provides two distinct snapshot methods — choose the one that fits your reporting needs:
| Method | What it captures | Attached to Allure |
|---|---|---|
captureSnapshot() | Full-page screenshot and page source | Yes — both screenshot and HTML |
capturePageSnapshot() | Serialized DOM/page data only (no image) | Yes — HTML source only |
captureSnapshot()
driver.browser().captureSnapshot();
Captures a full page snapshot including both a screenshot and the page source, and attaches both to the Allure report.
capturePageSnapshot()
driver.browser().capturePageSnapshot();
Captures and serializes the current page DOM data and attaches it to the Allure report as an HTML artifact. Use this when you only need the page structure without a visual screenshot.
generateLightHouseReport()
The managed flow below depends on
SHAFT Engine issue #4884.
It is not yet available on SHAFT_ENGINE main or in a published SHAFT
release. Keep using the current Lighthouse flow until a release that contains
the managed LIGHTHOUSE provider is available.
Install and verify the managed Lighthouse profile before running the test. The report action does not install tools or use a global Node or npm command. Use the default SHAFT roots for this preview so the setup CLI and Browser Actions resolve the same managed installation.
shaft-cli setup status --profile LIGHTHOUSE
shaft-cli setup plan \
--profile LIGHTHOUSE \
--mode MANAGED \
--output /absolute/path/lighthouse-plan.json
shaft-cli setup install \
--plan /absolute/path/lighthouse-plan.json \
--approve sha256:<reviewed-digest>
shaft-cli setup verify --profile LIGHTHOUSE
See Set up local infrastructure for the canonical plan, install, policy, and offline-cache instructions.
SHAFT.Properties.performance.set().isEnabled(true);
driver.browser().generateLightHouseReport();
Run a desktop performance audit on the currently open page. SHAFT invokes its
managed Lighthouse 13.4.1 CLI with managed Node 24.19.0 and connects to the
debugging port of the local Chromium browser owned by WebDriver. SHAFT does not
install Chromium as part of the LIGHTHOUSE profile.
The action writes a validated HTML file under lighthouse-reports/ and attaches
its contents to the Allure output. It creates no executable JavaScript in the
project. A missing or degraded managed toolchain stops the action with the
setup command needed to repair it.
openLighthouseReportWhileExecution defaults to false, which is suitable for
headless and CI runs. Set openLighthouseReportWhileExecution=true only when
you want a desktop test run to open the generated HTML report and Java has a
supported desktop/default-browser handler. If the handler is unavailable or
opening fails, the report action fails before attaching the HTML to Allure.
Wait Actions
Wait for Lazy Loading
driver.browser().waitForLazyLoading();
Waits for lazy-loaded content to finish loading on the page.
Wait for a page condition
Use the element action surface with a Selenium condition when a page state
must settle before the next action. For content loaded after the initial page,
use waitForLazyLoading() above.
import org.openqa.selenium.support.ui.ExpectedConditions;
driver.element().waitUntil(ExpectedConditions.titleContains("Dashboard"));
Network Interception
Intercept and Mock HTTP Requests
driver.browser()
.interceptRequest()
.get()
.urlContains("/api/data")
.respond()
.statusCode(200)
.jsonBody("{}");
Intercepts browser HTTP requests matching the builder criteria and returns the mocked response.
Validate Intercepted Responses
driver.browser()
.interceptRequest()
.get()
.pathEquals("/api/data")
.assertResponse(response -> response
.body()
.contains("{}"));
Use clearNetworkInterceptors() to remove active browser network rules before the driver session ends.
Record, Replay, and Validate Contracts
Contract methods capture matching browser traffic into the same deterministic
contract file used by SHAFT.API. Replay turns captured responses into browser
network mocks. Assert and verify modes compare live traffic with the stored
contract and attach readable Allure diffs for mismatches.
driver.browser().startContractRecording(
"src/test/resources/contracts/search.json",
"/api/search");
driver.browser().navigateToURL("https://example.com/search");
SHAFT.Contracts.stopRecording();
driver.browser().assertContract(
"src/test/resources/contracts/search.json",
"/api/search");
driver.browser().navigateToURL("https://example.com/search");
SHAFT.Contracts.stopValidation();
driver.browser().replayContract("src/test/resources/contracts/search.json");
See UI and API contract replay for combined browser and API examples.
Browser Network Profiles
DevTools-capable Selenium drivers can switch the active browser session offline, throttle throughput, block resource patterns, and restore the default network state. Unsupported drivers keep the test running and add a deterministic observability warning to the trace metadata.
driver.browser()
.goOffline()
.and().restoreNetwork()
.and().throttleNetwork(250, 64, 32)
.and().blockNetworkResources("*.png", "*.jpg");
Call restoreNetwork() after a profile-specific assertion when later steps
need normal connectivity.
Mobile Context
Get and Set Context
String context = driver.browser().getContext();
driver.browser().setContext("WEBVIEW_1");
Get Context Handles
List<String> contexts = driver.browser().getContextHandles();
Accessibility Testing
SHAFT Engine integrates axe-core to run automated WCAG accessibility audits. Chain .accessibility() onto any browser action to start auditing:
driver.browser().navigateToURL("https://example.com")
.accessibility()
.assertNoCriticalViolations("Home Page");
For a full reference of all accessibility methods, see Accessibility Testing.
Fluent Chaining
All browser actions support fluent chaining with .and():
driver.browser()
.navigateToURL("https://www.google.com")
.and().maximizeWindow()
.and().captureScreenshot();
SHAFT provides automatic reporting for every browser action. Check the Reporting section in the sidebar for details on the rich reports generated for each action.