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.