DOCSEARCHbyAlgolia
Submit Docs

SHAFT Engine Documentation

website·Indexed 29 days ago

https://shafthq.github.io/

Documentation for SHAFT, a test automation framework featuring the SHAFT Engine. It provides tools for UI, API, and mobile testing (including Flutter and Appium), managed local infrastructure, and integration with MCP clients via shaft-mcp. Key features include the SHAFT.GUI.WebDriver facade, Playwright backend support, and a CLI for project management and CI/CD integration.

Tokens
140.6K
Snippets
630
Records
899
Agent score
74%

What's inside SHAFT

  1. Overview of the SHAFT automation framework

    SHAFT is a Maven-published Java automation framework that provides a single fluent API to manage multiple test surfaces, including Web (Selenium), Mobile (Appium), API (REST Assured), CLI, and Databases. It integrates built-in synchronization, screenshots, logging, and Allure reporting. It supports TestNG, JUnit, and Cucumber.

  2. Overview of shaft-mcp

    shaft-mcp is the Model Context Protocol (MCP) server for SHAFT automation, supporting browser, mobile, Capture, coding-partner planning, Doctor, and healer automation. It is published to Maven Central as the io.github.shafthq:shaft-mcp JAR and depends on the shaft-engine module.

  3. Overview of SHAFT Agentic Testing Capabilities

    SHAFT provides a suite of agentic tools that separate deterministic automation from optional AI model-provider advice. Many tools work without provider credentials (the 'No-AI lane').

    • IntelliJ Plugin: IDE interface for Assistant, Coding Partner, Recorder, Doctor, Healer, and Inspector.
    • MCP (Model Context Protocol): Local stdio tools that do not store model credentials.
    • Planning: Generates deterministic Markdown test plans in specs/ via same-origin crawls without AI calls.
    • Capture: Records user actions to generate deterministic TestNG source code.
    • Doctor: Analyzes allowlisted evidence offline to provide portable diagnosis of failures.
    • Heal: Recovers eligible web locators using an explainable policy.
    • Pilot Providers: Optional AI provider integration, disabled by default until explicitly configured.

  4. Overview of SHAFT Pilot Modules

    SHAFT Pilot is composed of several modules that handle different parts of the automation lifecycle. AI capabilities are optional and disabled by default; core functions like capture and diagnosis remain usable without an AI provider account or API key.

  5. Manage SHAFT properties using different configuration methods

    SHAFT properties can be managed and configured through four primary methods depending on the required flexibility and timing of the configuration:

    1. Config Generator: An interactive builder tool used to search, edit, and export a .properties file without manual key entry.
    2. Programmatic Configuration: Read or write properties during runtime for maximum flexibility and dynamic control.
    3. CLI Commands: Set specific properties via the command line interface at the time of test execution.
    4. Custom Properties File: The traditional method of creating a custom.properties file to define static configuration values.

  6. Understand SHAFT Engine's underlying technology stack

    SHAFT acts as a facade over several established automation projects, allowing test code to remain at a single entry point while leveraging specialized libraries. The core stack includes:

    • Runtime/Build: Java 25, Maven
    • Web: Selenium
    • Mobile: Appium
    • API: REST Assured
    • Test Runners: TestNG, JUnit, Cucumber
    • Evidence: Allure Report
    • Optional Visual Providers: OpenCV, Applitools, Selenium Shutterbug
    • Distribution: Maven Central, GitHub Container Registry
    SHAFT.GUI.WebDriver driver = new SHAFT.GUI.WebDriver();

driver.browser().navigateToURL("https://duckduckgo.com");
driver.element().type(By.name("q"), "SHAFT Engine");
driver.assertThat().browser().title().contains("DuckDuckGo");

driver.quit();

  7. Understand SHAFT_ENGINE reactor layout

    SHAFT_ENGINE is structured as a Maven reactor. The canonical published coordinate is io.github.shafthq:shaft-engine. The coordinate io.github.shafthq:SHAFT_ENGINE is maintained as a POM-only relocation artifact to redirect consumers to the canonical JAR.

  8. Record web API traffic using shaft-mcp

    The shaft-mcp API capture tools allow developers to record HTTP request and response traffic during browser-based test execution. These tools extend the standard Capture lifecycle by providing automatic API event collection, body externalization, and sensitive header redaction. This functionality requires browser support for the Chrome DevTools Protocol (CDP); therefore, only Chrome and Edge are supported (Firefox and Safari are not supported).

  9. Breaking Changes in shaft-mcp tool surface

    The tool architecture was trimmed from 164 to 89 tools. There is no backward compatibility shim; calling deleted tools will fail immediately.

    Major removals include:

    • All playwright_* prefixed tools (34 tools removed).
    • natural_act and mobile_natural_act.
    • Specific mobile tools like mobile_tap, mobile_type, mobile_clear, and various mobile_swipe_* tools (now handled by unified element_* or mobile_swipe).
    • Redundant cookie and file upload tools (absorbed into browser_delete_cookies and element_upload_file).
    • Standalone mobile initialization and recording tools (absorbed into driver_initialize and capture_*).

  10. Understand SHAFT Engine architecture and positioning

    SHAFT is an automation engine, not a framework. It sits in the engine layer of a test automation stack, wrapping industry-standard libraries (Selenium WebDriver, Appium, REST Assured, TestNG/JUnit, Allure) to provide smart element handling, a unified API, and built-in reporting. Because it is an engine, it does not dictate test structure; it is compatible with Page Object Model, fluent design, and other patterns.

  11. Manage SHAFT dependencies using Maven artifacts

    SHAFT uses a modular architecture to control dependency weight. The shaft-engine is the required core runtime. Other capabilities are provided as optional JARs that can be added based on project needs. The shaft-bom (Bill of Materials) should be used to align versions across all artifacts.
    <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>

  12. ChaosEngine host adapter topology

    ChaosEngine uses a provider-neutral kernel to normalize native lifecycle events from five host adapters: Codex, Claude, Gemini, Grok, and GitHub Copilot. These adapters preserve their native configuration shapes and foreign handlers. The kernel resolves account tools which then interface with Memory, MemPalace, and Graphify.