Start here

SHAFT is a Java test-automation framework. The shortest path from zero to a run is the published user guide at https://shafthq.github.io/: generate a project, then run mvn test.

Humans: use this page to orient, then CONTRIBUTING.md when you change the engine. Report vulnerabilities through SECURITY.md.

Agents: start at AGENTS.md. It points at ChaosEngine, the only working-policy owner. This README is orientation. Do not treat it, or any module README, as agent policy.

Each Maven reactor module and shaft-intellij has a short README with a purpose line and a use-or-skip note.

SHAFT removes the repeated plumbing around drivers, waits, assertions, configuration, test data, screenshots, logs, and Allure evidence. Its modular Maven reactor keeps the core lean and lets teams add advanced tooling only when they need it.

Local agency (ChaosEngine)

• FreeToken / llama.cpp on ROG: resolve with chaos-engine/skills/local-agency (dispatch.py --prefer freetoken or OpenAI-compat on :8080).
• Colibri is optional only when http://127.0.0.1:8000 is READY; not the default on 6GB VRAM laptops.
• Proof runner note (#6045): preferred dense coder is Qwen2.5-Coder-7B Q4_K_M via llama-server when FreeToken KV is ~8k.

From zero to useful evidence

1. Open the SHAFT landing page and generate a ready-to-run Maven project.

2. Extract it and run:

   mvn test
   

3. Inspect the sample result, screenshots, logs, and Allure evidence.

The generated project uses the canonical Maven coordinate io.github.shafthq:shaft-engine and gives you a repeatable baseline for local runs and CI.

One orchestration layer, every execution surface

Test intent and configuration enter SHAFT's orchestration layer, fan out across the required execution surfaces, and return through one unified evidence flow.

flowchart LR
    accTitle: SHAFT execution and evidence workflow
    accDescr: Test intent and configuration enter SHAFT orchestration, run across Web, Mobile, API, and Native execution surfaces, and produce unified evidence.
    I[Test intent] --> S[SHAFT orchestration]
    C[Configuration] --> S
    S --> W[Web]
    S --> M[Mobile]
    S --> A[API]
    S --> N[Native, CLI, and Database]
    W --> E[Unified evidence]
    M --> E
    A --> E
    N --> E

Engineering need	What SHAFT provides
Stable UI automation	Managed Selenium and Appium drivers, synchronized actions, locator builders, screenshots, and accessibility evidence.
End-to-end coverage	REST, GraphQL, Database, CLI, and native desktop actions in the same test flow.
Trustworthy verdicts	Hard and soft assertions, structured logs, attachments, failure context, and Allure reports.
Scalable execution	Configuration-first local, Grid, BrowserStack, LambdaTest, TestNG, JUnit, and Cucumber runs.
Maintainable architecture	A focused engine, BOM-aligned optional modules, public extension points, and reusable test assets.
Assisted workflows	Capture, Doctor, deterministic Heal, MCP/CLI tools, provider adapters, and an IntelliJ IDEA plugin.

Built for long-lived automation suites

• Strong defaults, explicit control. Sensible behavior gets teams moving; configuration keeps environments and CI reproducible.
• Modular by design. Start with shaft-engine, then adopt visual, video, cloud, native, or agentic modules without rebuilding the test architecture.
• Evidence is part of execution. Logs, screenshots, attachments, and reports share one lifecycle instead of becoming after-the-fact glue.
• Open and inspectable. SHAFT is MIT licensed, built in public, and guarded by its pull-request gate, security policy, and published release history.

Agent-ready, source-grounded

SHAFT ships 30 first-party skills for planning, authoring, running, diagnosing, and reporting tests. Start with $shaft-developer; it routes the immediate job to one focused specialist. Exact MCP names and CLI syntax are generated from source in shaft-mcp-tools.md and shaft-cli-commands.md.

Join the project

• Found a bug or have an idea? Open an issue.
• Want to contribute? Read CONTRIBUTING.md and our Code of Conduct.
• Found a vulnerability? Follow SECURITY.md and report it privately.
• Does SHAFT help your team? Star the repository so more automation engineers can find it.

BrowserStack, LambdaTest, Applitools, and JetBrains have provided tooling or open-source program support. This is support for the project, not a claim of financial sponsorship, customer status, or endorsement.

SHAFT is free and MIT licensed. You can support ongoing maintenance, documentation, and public infrastructure through GitHub Sponsors.

MIT licensed — see LICENSE.