Skip to main content

Architecture

SHAFT has two kinds of modularity:

  1. Maven artifacts control dependency weight.
  2. The SHAFT facade exposes testing namespaces such as GUI, API, CLI, and DB.

These are related, but they are not one artifact per facade namespace. Most functionality remains in the required shaft-engine JAR.

Where SHAFT fits in a test automation stack​

A test automation architecture separates concerns into layers — your test scripts, page objects/models, the engine, core libraries, and drivers/protocols that talk to the application under test. SHAFT Engine sits in the engine layer: it wraps and enhances industry-standard libraries (Selenium WebDriver, Appium, REST Assured, TestNG/JUnit, Allure) with smart element handling, a unified API across web/mobile/API/CLI/database testing, built-in reporting, and property-based configuration.

CapabilityWithout SHAFTWith SHAFT
Wait strategyManual WebDriverWait configurationAutomatic smart waits
Element not found handlingCustom retry logicBuilt-in retry with configurable attempts
Screenshot captureManual TakesScreenshot codeAutomatic at validation points
ReportingManual Allure setup and step annotationsAutomatic step logging and report generation
Cross-browserManual driver managementAutomatic driver management

SHAFT is an engine, not a framework: it does not dictate how you structure your tests — Page Object Model, fluent design, or any pattern you prefer all work — it provides the building blocks and you decide how to assemble them. This means SHAFT works with your team's existing conventions and can be adopted gradually, one test at a time, without rewriting your suite.

Published Maven artifacts​

ArtifactPackagingConsumer purpose
shaft-engineJARRequired facade and core web, mobile, API, database, CLI, reporting, and accessibility implementation.
shaft-pilot-coreJARProvider-neutral Pilot contracts, consent, redaction, budgets, audit metadata, and deterministic fallback.
shaft-captureJARManaged Chrome/Edge recording, deterministic privacy classification, versioned schema, and atomic JSON persistence.
shaft-doctorJARPortable redacted evidence, deterministic diagnosis, optional advisory, and approval-gated isolated repair proposals.
shaft-aiJAROptional direct OpenAI, Anthropic, Gemini, GitHub Models, and Ollama HTTP adapters discovered through ServiceLoader.
shaft-healJARDeterministic, explainable, action-scoped web element recovery with bounded local history and optional reranking.
shaft-browserstackJARBrowserStack SDK interception and browserstack.yml orchestration. Direct BrowserStack sessions stay in shaft-engine.
shaft-videoJARLocal non-headless desktop recording. Appium-native recording stays in shaft-engine.
shaft-visualJARReference-image assertions and image-based lookup through OpenCV, Eyes, and Shutterbug.
shaft-sikulixJARSikuliX image matching for desktop workflows that cannot be reached through DOM or Appium locators.
shaft-mcpthin JAROptional MCP server and CLI exposing browser automation, managed capture, Doctor analysis, and packaged direct adapters.
shaft-bomPOMAligns all SHAFT artifact versions; adds no runtime classes.
SHAFT_ENGINErelocation POMTemporary legacy-coordinate bridge to shaft-engine; adds no optional providers.

See the upgrade guide for method-level dependency boundaries.

pom.xml
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.github.shafthq</groupId>
      <artifactId>shaft-bom</artifactId>
      <version>${shaft.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>io.github.shafthq</groupId>
    <artifactId>shaft-engine</artifactId>
  </dependency>
</dependencies>

Facade architecture​

Optional provider discovery​

shaft-heal, shaft-visual, and shaft-video implement SHAFT-owned provider interfaces and register them through Java ServiceLoader. The facade and orchestration remain in shaft-engine, which means users add a provider JAR without changing test method calls.

shaft-browserstack is a runtime integration rather than a SHAFT provider. It adds browserstack-java-sdk; SHAFT's core BrowserStack driver path also generates browserstack.yml, which the SDK consumes when the optional module is present.

shaft-sikulix is a runtime action module. It adds the SikuliX API and a small desktop-image action facade without shadowing shaft-engine classes.

Module guides​