# SHAFT User Guide > SHAFT is a unified test automation engine for Web, Mobile, API, CLI, and Database testing. Markdown links below are the token-lean form of each guide page. The HTML page is named inside that file. ## Start - [How the modular SHAFT upgrade works](https://shafthq.github.io/md/start/upgrade/how-it-works.md): What the transactional upgrader guarantees: project detection, optional-module evidence, compile-validated rollback, AI repair, and Seleniu… - [Install managed mobile infrastructure](https://shafthq.github.io/md/start/local-infrastructure/mobile.md): Plan, approve, and install SHAFT-owned Android SDK, emulator, and Appium, or iOS and Windows Appium drivers. - [Install managed services and tools](https://shafthq.github.io/md/start/local-infrastructure/services.md): Plan, approve, and install SHAFT-owned Selenium Grid, Healenium, ReportPortal, BrowserStack Local, Playwright browsers, and Lighthouse, and… - [Install SHAFT](https://shafthq.github.io/md/start/installation.md): Generate a new SHAFT project or upgrade an existing automation project. - [Local infrastructure reference](https://shafthq.github.io/md/start/local-infrastructure/reference.md): Plan and install policy options, the SHAFT.Infrastructure Java API and properties, and shaft-cli setup exit codes. - [Modular SHAFT upgrade reference](https://shafthq.github.io/md/start/upgrade/reference.md): Upgrader command options, Maven coordinates, the module map, optional-module dependency boundaries, the legacy relocation, and measured dow… - [Preview managed local AI and OCR setup](https://shafthq.github.io/md/start/local-infrastructure/previews.md): Evaluate the managed LOCAL_AI provider and the unreleased managed OCR setup from a source build. - [Quick start](https://shafthq.github.io/md/start/quick-start.md): Choose the right SHAFT setup path, then run a first test. - [Run the modular SHAFT upgrade](https://shafthq.github.io/md/start/upgrade/run.md): Step-by-step: prerequisites, download and run the transactional upgrader, choose an upgrade type, validate, and roll back. - [Set up local infrastructure](https://shafthq.github.io/md/start/local-infrastructure.md): Diagnose, plan, approve, and install SHAFT-owned local tools through shaft-cli or Java. - [SHAFT at a glance](https://shafthq.github.io/md/start/overview.md): One Java automation engine for Web, Mobile, API, CLI, and Database testing. - [Upgrade to modular SHAFT](https://shafthq.github.io/md/start/upgrade.md): Transactionally migrate legacy or native Maven projects to modular SHAFT. ## Testing - [API testing](https://shafthq.github.io/md/testing/api.md): Build, execute, inspect, and assert REST API requests with SHAFT. - [CLI testing](https://shafthq.github.io/md/testing/cli.md): Execute and validate local, Docker, and SSH commands with SHAFT. - [Database testing](https://shafthq.github.io/md/testing/database.md): Connect, query, and validate databases through SHAFT. - [Flutter testing guide](https://shafthq.github.io/md/testing/flutter.md): SHAFT Flutter guide with Locator.flutter factories and tap/type/assert sample. - [How SHAFT reduces flakiness](https://shafthq.github.io/md/testing/flakiness.md): How SHAFT reduces common automation flakiness through semantic locators, synchronization, retry evidence, and optional locator recovery. - [Mobile and Flutter testing](https://shafthq.github.io/md/testing/mobile.md): Configure Appium and automate Android, iOS, mobile web, and Flutter applications. - [UI and API contract replay](https://shafthq.github.io/md/testing/contracts.md): Record browser and SHAFT.API traffic, replay captured responses, and validate live traffic against deterministic contracts. - [Web testing](https://shafthq.github.io/md/testing/web.md): A minimal SHAFT browser test with lifecycle, actions, and assertions. ## Agentic - [Agentic testing](https://shafthq.github.io/md/agentic/overview.md): Understand how the IntelliJ plugin, MCP, Pilot, Capture, Doctor, and Heal fit together. - [Connect shaft-mcp](https://shafthq.github.io/md/agentic/mcp.md): Run SHAFT browser, guide search, Capture, Doctor, and healer tools from Codex, Copilot, and other MCP clients. - [Diagnose failures with Doctor](https://shafthq.github.io/md/agentic/doctor.md): Build deterministic, portable diagnoses from explicitly allowlisted test evidence. - [Install and operate ChaosEngine](https://shafthq.github.io/md/agentic/chaos-engine.md): Install, inspect, recover, and understand the project-local SHAFT agent harness. - [Install SHAFT agent skills](https://shafthq.github.io/md/agentic/skills.md): Install the first-party SHAFT testing skill pack for agent-native projects. - [IntelliJ IDEA plugin](https://shafthq.github.io/md/agentic/intellij.md): Use the SHAFT coding partner front door for Assistant, Coding Partner, MCP tools, Recorder, Doctor, Healer, Inspector, Projects, and Guide… - [Optional AI providers](https://shafthq.github.io/md/agentic/providers.md): Consent, redaction, budgets, and provider controls for optional SHAFT AI advice. - [Record tests with Capture](https://shafthq.github.io/md/agentic/capture.md): Record browser activity and generate reviewable deterministic TestNG source. - [Recover locators with Heal](https://shafthq.github.io/md/agentic/heal.md): Enable deterministic, explainable WebDriver locator recovery. - [SHAFT Pilot](https://shafthq.github.io/md/agentic/pilot.md): Capture, generation, diagnosis, reviewed repairs, and MCP interoperability — plus downloadable credential-free Pilot example assets. - [shaft-cli command line](https://shafthq.github.io/md/agentic/cli.md): Run all shaft-mcp tools from the command line with one-shot commands or a persistent session. ## Features - [Agentic tool updates](https://shafthq.github.io/md/features/whats-new/agentic.md): Configure deterministic local tools, IntelliJ workflows, and optional providers. - [Architecture](https://shafthq.github.io/md/features/architecture.md): SHAFT runtime, module, facade, and agent integration architecture — plus where SHAFT fits in a general test automation stack and the engine… - [Capture and generation updates](https://shafthq.github.io/md/features/whats-new/capture.md): Record browser, API, and mobile journeys and generate replayed SHAFT code. - [Evidence and report updates](https://shafthq.github.io/md/features/whats-new/evidence.md): Configure portable failure evidence, structured checkpoints, and merged reports. - [Features and modules](https://shafthq.github.io/md/features/modules.md): Select core and optional SHAFT modules by capability, then review the technology stack, project support, and funding. - [Features you might have missed](https://shafthq.github.io/md/features/whats-new/missed.md): Find useful locator, localization, and report compatibility features. - [Integrations and modules](https://shafthq.github.io/md/features/whats-new/modules.md): Add focused SHAFT integrations and understand OCR release status. - [Pillars of successful test automation](https://shafthq.github.io/md/features/test-automation-pillars.md): How SHAFT helps teams build scalable, reliable, and maintainable test automation frameworks. - [Platform and setup updates](https://shafthq.github.io/md/features/whats-new/platform.md): Configure modular dependencies and local or remote test infrastructure. - [Reporting and evidence](https://shafthq.github.io/md/features/reporting.md): How SHAFT records actions, screenshots, logs, and Allure results. - [Testing API updates](https://shafthq.github.io/md/features/whats-new/testing.md): Use newer web, mobile, API, contract, visual, and accessibility capabilities. - [What's new since modularization](https://shafthq.github.io/md/features/whats-new.md): Find and use user-facing SHAFT capabilities added since the modular release. ## Integrations - [BrowserStack](https://shafthq.github.io/md/integrations/browserstack.md): Choose direct BrowserStack sessions or the optional SDK orchestration module. - [Desktop and video](https://shafthq.github.io/md/integrations/desktop-and-video.md): Optional local desktop recording and SikuliX image-based desktop automation. - [OCR and visible-text automation](https://shafthq.github.io/md/integrations/ocr.md): Recognize, assert, and interact with visible text in images, web pages, mobile apps, and desktop applications. - [Visual testing](https://shafthq.github.io/md/integrations/visual.md): Add reference-image assertions and image-based touch operations. ## Reference - [Reference](https://shafthq.github.io/md/reference/overview.md): Detailed SHAFT actions, properties, validations, and practices. - [Alert Actions](https://shafthq.github.io/md/reference/actions/GUI/Alert_Actions.md): Handle browser alert dialogs — accept, dismiss, read text, and type into prompt alerts using SHAFT Engine. - [API Authentication](https://shafthq.github.io/md/reference/actions/API/API_Authentication.md): Configure BASIC, FORM, OAuth2, API Key, cookie, and session authentication for API tests in SHAFT Engine using setAuthentication and addHea… - [Async Element Actions](https://shafthq.github.io/md/reference/actions/GUI/Async_Element_Actions.md): Run SHAFT element actions concurrently using Java virtual threads — improve test speed with non-blocking parallel interactions. - [Basic Configuration for API](https://shafthq.github.io/md/reference/configuration/apiConfig.md): Configure SHAFT Engine properties for REST API testing — proxy, timeouts, retry settings, and Swagger/OpenAPI schema validation. - [Basic Configuration for Mobile GUI](https://shafthq.github.io/md/reference/configuration/mobileConfig.md): Configure SHAFT Engine properties for mobile app automation with Appium — Android, iOS, native and web execution settings. - [Basic Configuration for Web GUI](https://shafthq.github.io/md/reference/configuration/webConfig.md): Configure SHAFT Engine properties for web browser automation — browser type, headless mode, timeouts, proxy, and visual reporting. - [BDD-Style Reports with Allure Annotations](https://shafthq.github.io/md/reference/guides/BDD_Style_Reports.md): Use Allure annotations to generate business-readable BDD-style reports without Cucumber — simpler setup, better maintainability. - [Browser Actions](https://shafthq.github.io/md/reference/actions/GUI/Browser_Actions.md): Navigate pages, manage windows, handle cookies, capture screenshots, and control the browser using SHAFT Engine's BrowserActions API. - [Built-in Cucumber BDD Step Definitions](https://shafthq.github.io/md/reference/guides/Cucumber_BDD_Steps.md): Use SHAFT Engine's 500+ pre-built Gherkin step definitions for browser, element, and assertion steps — integrate Cucumber without writing b… - [Common Configuration Examples](https://shafthq.github.io/md/reference/properties/CommonExamples.md): Practical configuration examples for SHAFT Engine — web, mobile, API, parallel execution, cloud platforms, and CI/CD pipeline setup. - [Complete Properties Reference](https://shafthq.github.io/md/reference/properties/PropertiesList.md): Full reference of all SHAFT Engine configuration properties — web, mobile, API, timeouts, paths, reporting, and integrations. - [Cross-Platform Strategy: Android and iOS](https://shafthq.github.io/md/reference/guides/Cross_Platform_Strategy.md): When to combine Android and iOS tests in one project vs. separate projects, and how to handle platform-specific locators with SHAFT Engine. - [Custom Properties Generator](https://shafthq.github.io/md/reference/properties/custom-properties-generator.md): Generate SHAFT Engine properties files from a searchable catalog of supported properties, defaults, possible values, and descriptions. - [Database Actions](https://shafthq.github.io/md/reference/actions/DB/DB_Actions.md): Execute SQL queries and interact with databases using SHAFT Engine's database automation support. - [Database Connection Strings](https://shafthq.github.io/md/reference/actions/DB/Connection_Strings.md): JDBC connection string examples for MySQL, PostgreSQL, SQL Server, Oracle, and other databases with SHAFT Engine. - [Docker Container Terminal](https://shafthq.github.io/md/reference/actions/CLI/Docker_Terminal.md): Legacy Docker-wrapped terminal execution using SHAFT Engine's deprecated TerminalActions Docker constructor. - [Element Actions](https://shafthq.github.io/md/reference/actions/GUI/Element_Actions.md): Interact with web elements using SHAFT Engine — click, type, drag and drop, select from dropdowns, handle iframes, and more. - [Element Identification](https://shafthq.github.io/md/reference/actions/GUI/Element_Identification.md): Locate web elements using ID, CSS selectors, XPath, SHAFT Locator Builder, relative locators, shadow DOM, iframes, By objects vs @FindBy, d… - [File Actions](https://shafthq.github.io/md/reference/actions/CLI/File_Actions.md): Manage files and directories programmatically — read, write, copy, move, and delete files using SHAFT Engine. - [Fluent Design: Chaining Actions and Validations](https://shafthq.github.io/md/reference/guides/Fluent_Design.md): Learn how to use SHAFT Engine's fluent API to chain actions and validations for readable, maintainable test code. - [GraphQL API Testing](https://shafthq.github.io/md/reference/actions/API/GraphQL_Testing.md): Test GraphQL APIs in SHAFT Engine — send queries, mutations, and subscriptions with variables, fragments, and authentication headers using… - [JUnit Integration](https://shafthq.github.io/md/reference/guides/JUnit_Integration.md): Run SHAFT Engine tests with JUnit — set up test classes with @BeforeEach, @AfterEach, @Test, and @Order annotations alongside the SHAFT Web… - [Natural Language Actions](https://shafthq.github.io/md/reference/actions/GUI/Natural_Language_Actions.md): Use trust-gated natural-language browser, element, and touch actions through SHAFT Engine. - [Oracle JDBC Setup](https://shafthq.github.io/md/reference/actions/DB/Oracle_JDBC_Setup.md): Step-by-step guide to configure Oracle JDBC driver for database testing with SHAFT Engine. - [Parallel Execution Configuration](https://shafthq.github.io/md/reference/configuration/parallelExecution.md): Run SHAFT tests in parallel using TestNG, JUnit, or Maven Surefire — thread-safe driver management with ThreadLocal and configuration examp… - [Playwright Backend](https://shafthq.github.io/md/reference/actions/GUI/Playwright_Backend.md): Use SHAFT GUI actions and assertions through the Microsoft Playwright Java backend. - [Programmatic Properties Configuration](https://shafthq.github.io/md/reference/properties/Programmatic_Config.md): Configure SHAFT Engine properties in code at runtime — thread-safe programmatic configuration for browser, timeouts, visuals, and behaviour… - [Property Types](https://shafthq.github.io/md/reference/properties/PropertyTypes.md): Understand SHAFT Engine property configuration — file-based, code-based, and CLI-based approaches with priority hierarchy. - [Reporting](https://shafthq.github.io/md/reference/reporting.md): Learn about SHAFT Engine's built-in reports — Allure and Execution Summary — how to configure video recording and report behavior via prope… - [Request Builder](https://shafthq.github.io/md/reference/actions/API/Request_Builder.md): Build and send API requests with SHAFT Engine — GET, POST, PUT, PATCH, DELETE with authentication, headers, parameters, body configuration,… - [Response Getters](https://shafthq.github.io/md/reference/actions/API/Response_Getters.md): Extract and parse API response data — body, typed JSON objects, status code, response time, JSON values, and XML values using SHAFT Engine. - [Response Validations](https://shafthq.github.io/md/reference/actions/API/Response_Validations.md): Validate API responses — status codes, JSON values, response body, schema matching, and response time using SHAFT Engine. - [Running Tests in CI/CD Pipelines](https://shafthq.github.io/md/reference/guides/CI_CD_Integration.md): How to run SHAFT Engine tests in CI/CD pipelines — configuring properties, headless execution, and pipeline integration tips. - [Sharded Test Execution and Merged Reports](https://shafthq.github.io/md/reference/guides/Sharded_Execution.md): Split a SHAFT suite across parallel shards with -Dshaft.shard=N/M, then merge every shard's Allure results into one report and speedboard. - [SSH Remote Terminal](https://shafthq.github.io/md/reference/actions/CLI/SSH_Terminal.md): Execute commands on remote servers via SSH using SHAFT Engine's TerminalActions with the SSH constructor. - [Terminal Actions](https://shafthq.github.io/md/reference/actions/CLI/Terminal_Actions.md): Execute terminal commands and shell scripts programmatically using SHAFT Engine's CLI terminal actions. - [Test Artifacts and Report Paths](https://shafthq.github.io/md/reference/guides/Test_Artifacts.md): Where to find SHAFT Engine test artifacts — Allure reports, execution summaries, and how to publish them from CI/CD pipelines. - [Test Automation Solution Design Patterns](https://shafthq.github.io/md/reference/guides/Solution_Design.md): Compare test automation design patterns — Page Object Model, fluent design, anonymous classes, inheritance, and base classes — with SHAFT E… - [Test Automation Tool Selection Criteria](https://shafthq.github.io/md/reference/guides/Tool_Selection.md): Key criteria for selecting a test automation tool or framework, and how SHAFT Engine addresses each one. - [Test Data Management](https://shafthq.github.io/md/reference/actions/TestData_Management.md): Manage test data from JSON, Excel, CSV, and YAML files using SHAFT Engine's test data management API. - [Test Structure: Cases vs. Scenarios](https://shafthq.github.io/md/reference/guides/Test_Structure.md): Understand the difference between isolated test cases and dependent test scenarios, and why you should avoid using priority to order tests. - [The Testing Pyramid and Automation Strategy](https://shafthq.github.io/md/reference/guides/Testing_Pyramid.md): Understand the testing pyramid, the role of each testing level, and how to build an effective test automation strategy with SHAFT Engine. - [Tips: Infrastructure, Network, and Visual](https://shafthq.github.io/md/reference/actions/GUI/Infrastructure_Network_And_Visual.md): SHAFT Engine infrastructure tips — native WebDriver access, custom browser capabilities, mobile emulation, local and Kubernetes Selenium Gr… - [Tips: Locators and Self-Healing](https://shafthq.github.io/md/reference/actions/GUI/Locators_And_Self_Healing.md): SHAFT Engine locator tips — ARIA role-based locators, self-healing locators (SHAFT Heal and legacy Healenium), Shadow DOM, the SHAFT Locato… - [Tips: Waits and Synchronization](https://shafthq.github.io/md/reference/actions/GUI/Waits_And_Synchronization.md): SHAFT Engine synchronization tips — explicit element and browser wait strategies, custom condition waits, and clipboard action sequencing. - [Touch Actions](https://shafthq.github.io/md/reference/actions/GUI/Touch_Actions.md): Automate mobile touch interactions — tap, swipe, pinch to zoom, long press, and app background management using SHAFT Engine. - [Validations](https://shafthq.github.io/md/reference/actions/Validations.md): SHAFT Engine's built-in assertions and verifications — browser, element, file, object, number, and API response validation, JSON schema val… ## Maintainers - [Maintainer runbooks](https://shafthq.github.io/md/maintainers/overview.md): Build, release, CI, agent guidance, and repository maintenance procedures. - [Documentation site operations](https://shafthq.github.io/md/maintainers/site-operations.md): Develop, validate, and deploy the canonical SHAFT documentation site. - [MCP publication and deployment](https://shafthq.github.io/md/maintainers/mcp-deployment.md): Build, publish, and optionally host the SHAFT MCP server. - [Agent guidance maintenance](https://shafthq.github.io/md/maintainers/agent-guidance.md): Keep repository agent instructions concise, validated, and current. - [Agent tooling](https://shafthq.github.io/md/maintainers/agent-tooling.md): Install, operate, and update the third-party agent stack used for SHAFT maintenance. - [CI failure investigation](https://shafthq.github.io/md/maintainers/ci-failure-investigation.md): Diagnose SHAFT CI failures using workflow logs and Allure artifacts. - [Maven Central publication](https://shafthq.github.io/md/maintainers/publication.md): SHAFT reactor publication order, verification, and rollback contract. - [Maven reactor](https://shafthq.github.io/md/maintainers/reactor.md): SHAFT modules, compatibility artifacts, and build boundaries. - [Repository history rewrite](https://shafthq.github.io/md/maintainers/history-rewrite.md): Maintainer-only procedure for approved repository history rewrites. - [SHAFT Pilot release](https://shafthq.github.io/md/maintainers/pilot-release.md): Release-candidate matrix and publication checks for SHAFT Pilot. - [User guide usability practices](https://shafthq.github.io/md/maintainers/usability-practices.md): The ten human and ten agent practices applied across the SHAFT user guide. - [Visual provider boundary](https://shafthq.github.io/md/maintainers/visual-provider.md): Maintainer contract between shaft-engine and the optional visual provider.