Skip to main content

Web testing

Start here when you want one browser test that opens a page, performs an action, asserts a result, and leaves screenshot/report evidence.

import com.shaft.driver.SHAFT;
import org.openqa.selenium.By;
import org.testng.annotations.*;

public class SearchTest {
    private SHAFT.GUI.WebDriver driver;

    @BeforeMethod
    public void openBrowser() {
        driver = new SHAFT.GUI.WebDriver();
    }

    @Test
    public void search() {
        driver.browser().navigateToURL("https://duckduckgo.com/")
                .and().element().type(By.name("q"), "SHAFT Engine")
                .and().assertThat().title().contains("DuckDuckGo");
    }

    @AfterMethod(alwaysRun = true)
    public void closeBrowser() {
        driver.quit();
    }
}

Use the GUI actions reference for locators, browser actions, elements, waits, validations, accessibility, and network mocking. For browser traffic that should be captured and replayed later, see UI and API contract replay.

Run and inspect evidence​

Run the generated or copied test from the project root:

mvn test

The report includes browser steps, screenshots, logs, and assertion results under allure-results and the generated Allure report under the project target output. If the browser never opens, check Java/Maven first, then browser installation, then targetBrowserName and headlessExecution.

Locator strategy​

Stop at the first unique match. Generated and repository web code uses this ladder:

  1. A unique, author-written id through the SHAFT locator builder: SHAFT.GUI.Locator.hasAnyTagName().hasId("checkout-submit").build(). Never a framework-recycled id such as :r1:, mat-input-3, cdk-overlay-0, ember1234, j_idt42, ctl00_..., or sc-bdVaJa.
  2. The same builder's ARIA role, chained until unique: SHAFT.GUI.Locator.hasRole(Role.BUTTON).hasNormalizedText("Create Account").build().
  3. Native relative By.xpath(...) only when the element has neither an eligible id nor a usable role.

Never generate SHAFT.GUI.Locator.xpath(...), the raw SHAFT.GUI.Locator.id/name/cssSelector/className/tagName(...) factories, or a Smart Locator (inputField / clickableField) in generated or repository code. Smart Locators stay legitimate only for a human's throwaway exploration snippet. See Locators and self-healing.

Keep waits and retries as evidence-backed safety nets, not as a substitute for a stable locator. Use SHAFT Heal only after deterministic locator strategies cannot survive expected UI changes.

Playwright backend​

Use SHAFT.GUI.Playwright when a test should run through Microsoft Playwright instead of Selenium/Appium WebDriver. Both backends implement SHAFT.GUI.Driver, so setup code can choose the backend per test class.

private SHAFT.GUI.Driver driver;

@BeforeMethod
public void openBrowser() {
    driver = new SHAFT.GUI.Playwright();
}

See the Playwright Backend reference for configuration, native Playwright access, tracing, and the WebDriver-to-Playwright mapping tree.

Click and type by control kind​

element().click(...) and element().type(...) keep the same fluent API, but SHAFT now classifies the target control and picks a safer recipe automatically (Selenium, Playwright, Appium mobile, and Windows/UIA desktop).

You do not opt in. Public calls stay unchanged. Typical routing:

  • Text-like inputs and textareas: clear strategy (see clearBeforeTypingMode) then type; Playwright prefers fill, and uses sequential keys when masks/debounce need key events
  • Checkbox / radio / switch: click or toggle, never type
  • Select / listbox / combobox: option or expand → filter → confirm — not blind sendKeys of the label alone
  • File inputs: set files via the file path API
  • Overlay / interception: scroll and retry before optional JS click (clickUsingJavascriptWhenWebDriverClickFails)
  • Mobile: focus → sendKeys / mobile: type / hide-keyboard helpers; Compose/Flutter need focus (and tags/semantics) before type
  • Windows desktop (WinAppDriver): UIA control-type map for Edit, Button, CheckBox, ComboBox, and related kinds

Flags such as attemptToClickBeforeTyping, clearBeforeTypingMode, and clickUsingJavascriptWhenWebDriverClickFails still apply when you need to tune the defaults. Maintainer detail lives in com.shaft.gui.element.internal.interaction (ElementClassifier, ClickStrategies, TypeStrategies) from epic #5732.