Reporting

SHAFT Engine ships with two complementary report formats, each suited to a different audience and workflow. You can enable or disable them independently using properties.

Report Types at a Glance

Report	Best For	Default State
Allure Report	Deep debugging — step-by-step logs, screenshots, videos	✅ Opens automatically after execution
Execution Summary	Quick supplemental feedback — fast, portable, no setup	⚙️ Opt-in via property

Allure Report

The Allure Report is the primary report in SHAFT. It opens automatically in your default browser at the end of every test run and provides a rich, single-file HTML report with:

Step-by-step action logs with screenshots attached
Video recordings (when enabled)
Animated GIFs of browser sessions
Test history and trend graphs across multiple runs
Environment information and categories

Failure Trace Viewer

When a test fails, SHAFT attaches a failure trace viewer to Allure by default. The viewer collects the failure timeline, exception and stacktrace, source-code frame fallback, available page or native source snapshot, and related artifacts without generating heavy trace artifacts for passing tests.

Allure receives these attachments on failed tests:

SHAFT Trace Report.html
shaft-trace.json
shaft-trace.zip
Native Playwright trace ZIP, when Playwright tracing is enabled and available

Use shaft.trace.mode=failure for normal runs. Switch to retry or always only while actively debugging.

src/main/resources/properties/custom.properties
shaft.trace.enabled=true
shaft.trace.mode=failure
shaft.trace.includeCodeContext=true
shaft.trace.includeFullPageSnapshots=true
shaft.trace.includeNativePageSource=true
shaft.trace.includeNetwork=true
shaft.trace.includeConsole=true
shaft.trace.maxArtifactMb=50

Open Allure Report Manually

SHAFT writes convenience scripts to your project root during the first run. Use them to regenerate and serve the Allure report at any time:

Windows
generate_allure_report.bat

macOS / Linux
./generate_allure_report.sh

Disable Auto-Opening the Allure Report

The Allure report opens automatically by default (allure.automaticallyOpen=true). To disable this:

File-based
CLI-based
Code-based

src/main/resources/properties/custom.properties
allure.automaticallyOpen=false

mvn test -Dallure.automaticallyOpen=false

import com.shaft.driver.SHAFT;

SHAFT.Properties.allure.set().automaticallyOpen(false);

Generate an Allure Report Archive (for CI/CD)

To generate a portable ZIP archive of the Allure report that you can publish as a CI/CD artifact:

File-based
CLI-based
Code-based

src/main/resources/properties/custom.properties
allure.generateArchive=true

mvn test -Dallure.generateArchive=true

import com.shaft.driver.SHAFT;

SHAFT.Properties.allure.set().generateArchive(true);

Customize the Allure Report

You can customize the report title and logo displayed in the generated HTML:

File-based
Code-based

src/main/resources/properties/custom.properties
allure.customTitle=My Regression Suite
allure.customLogo=https://example.com/my-logo.png

import com.shaft.driver.SHAFT;

SHAFT.Properties.allure.set()
    .customTitle("My Regression Suite")
    .customLogo("https://example.com/my-logo.png");

Tune Allure 3 Awesome Report Output

When SHAFT generates an Allure 3 report, it writes the corresponding allurerc.yaml file for the Allure Awesome plugin. In addition to the title, output directory, logo, and history settings, you can control the Awesome plugin options that affect packaging, theme mode, language, browser opening, and the hierarchy shown in the report tree. SHAFT-generated Allure 3 reports use the same light and dark color tokens as this user guide. Allure 2 reports keep their existing UI.

note

These options apply to Allure 3 report generation. allure.automaticallyOpen controls whether SHAFT opens the final report after test execution, while allure.open is passed to the Allure CLI configuration itself.

File-based
CLI-based
Code-based

src/main/resources/properties/custom.properties
# Generate a self-contained HTML report file (default: true)
allure.singleFile=true

# Allure 3 color mode (default: auto)
allure.theme=auto

# Allure UI language code (default: en)
allure.reportLanguage=en

# Let the Allure CLI open the report after generation (default: false)
allure.open=false

# Comma-separated Allure label hierarchy (default: package,testClass)
allure.groupBy=package,testClass

mvn test \
  -Dallure.singleFile=false \
  -Dallure.theme=auto \
  -Dallure.reportLanguage=fr \
  -Dallure.open=false \
  -Dallure.groupBy=package,testClass

import com.shaft.driver.SHAFT;

SHAFT.Properties.allure.set()
    .singleFile(false)
    .theme("auto")
    .reportLanguage("fr")
    .open(false)
    .groupBy("package,testClass");

Monitor Allure 3 Results While Tests Run

When allure.realtimeMonitoring=true and SHAFT resolves an Allure 3 CLI, SHAFT starts native allure watch against allure-results while tests run. The watch process is stopped before final report generation and archiving. This is disabled by default, and is ignored when Allure 2 compatibility mode is active or the Allure CLI cannot be resolved.

File-based
CLI-based
Code-based

src/main/resources/properties/custom.properties
allure.realtimeMonitoring=true

mvn test -Dallure.realtimeMonitoring=true

import com.shaft.driver.SHAFT;

SHAFT.Properties.allure.set().realtimeMonitoring(true);

Common allure.groupBy presets include:

Preset	Value	Best For
Code hierarchy	`package,testClass`	Default Java package and class navigation
Suite hierarchy	`parentSuite,suite,subSuite`	TestNG or suite-based organization
BDD hierarchy	`epic,feature,story`	Business-readable Allure annotation reports
Module hierarchy	`module,parentSuite,suite,subSuite`	Multi-module projects

Full-page image attachments open at the available modal width in SHAFT-generated Allure 3 reports. Use the modal scrollbar to inspect the rest of tall screenshots.

Troubleshoot Allure CLI Generation

SHAFT runs Allure report generation synchronously so the generated command, exit code, standard output, and standard error are visible in execution logs. If report generation fails, check the log entries around Executing Allure report generation command, Allure generate stdout, Allure generate stderr, and Allure report generation command exited with code ... before changing report settings.

Accumulate History and Reports Across Runs

By default, SHAFT keeps Allure history to enable trend graphs across runs. You can control this behavior:

File-based
Code-based

src/main/resources/properties/custom.properties
# Accumulate history to show trends across runs (default: true)
allure.accumulateHistory=true

# Keep previous HTML report files in the report directory (default: true)
allure.accumulateReports=true

# Clean the results directory before each run (default: true)
allure.cleanResultsDirectory=true

import com.shaft.driver.SHAFT;

SHAFT.Properties.allure.set()
    .accumulateHistory(true)
    .accumulateReports(true)
    .cleanResultsDirectory(true);

Execution Summary Report

The Execution Summary report is a lightweight supplement to the Allure report. It is disabled by default and is most useful when you want a quick, portable HTML summary without opening the full Allure report.

No extra setup required — just enable the property.
Portable — a fast self-contained HTML file you can share or archive.

Enable the Execution Summary Report

File-based
CLI-based
Code-based

src/main/resources/properties/custom.properties
openExecutionSummaryReportAfterExecution=true

mvn test -DopenExecutionSummaryReportAfterExecution=true

import com.shaft.driver.SHAFT;

SHAFT.Properties.reporting.set().openExecutionSummaryReportAfterExecution(true);

Locator Health Report

The Locator Health Report is disabled by default. Enable it when you want to find slow, flaky, ambiguous, stale, or healed web locators across a full run. SHAFT records lightweight metrics during element identification and writes HTML and JSON reports under execution-summary/locator-health/. The JSON export is attached to Allure, and the HTML dashboard is attached when shaft.locatorHealth.attachDashboard=true.

Recorded metrics include lookup count, unique-match, no-match, multi-match, and stale rates, average and p95 lookup time, polling attempts, timeout count, slow lookups, SHAFT Heal attempts, accepted recoveries, selected replacement locator, and confidence when the provider exposes it. Each locator also gets a health score, selector-smell labels, and plain-language recommendations for risky patterns such as absolute XPath, index-heavy XPath, generated IDs, text-only selectors, and deep CSS chains. When the failure trace viewer is enabled, failed-test trace JSON also includes the current locator health snapshot.

File-based
CLI-based
Code-based

src/main/resources/properties/custom.properties
shaft.locatorHealth.enabled=true
shaft.locatorHealth.warnBelowScore=70
shaft.locatorHealth.attachDashboard=true
shaft.locatorHealth.failBelowScore=-1
slowLocatorThresholdMillis=750

mvn test -Dshaft.locatorHealth.enabled=true -Dshaft.locatorHealth.warnBelowScore=70 -Dshaft.locatorHealth.failBelowScore=-1 -DslowLocatorThresholdMillis=750

import com.shaft.driver.SHAFT;

SHAFT.Properties.reporting.set()
    .locatorHealthEnabled(true)
    .locatorHealthWarnBelowScore(70)
    .locatorHealthAttachDashboard(true)
    .locatorHealthFailBelowScore(-1)
    .slowLocatorThresholdMillis(750)
    .failOnLocatorHealthWarnings(false);

Keep shaft.locatorHealth.failBelowScore=-1 while introducing the report. Set it to a score threshold only after the suite has a stable locator-health baseline. The legacy locatorHealthReportEnabled=true and failOnLocatorHealthWarnings=false keys remain supported.

Video Recording

SHAFT can record a video of every test session and automatically attach it to the Allure report. There is no code change required — it is purely a property:

File-based
CLI-based
Code-based

src/main/resources/properties/custom.properties
videoParams_recordVideo=true

mvn test -DvideoParams_recordVideo=true

import com.shaft.driver.SHAFT;

SHAFT.Properties.visuals.set().videoParamsRecordVideo(true);

Where to Put Your Properties File

Create a custom.properties file under src/main/resources/properties/ in your project. SHAFT automatically creates a properties/ directory with some core files on first run — just add your file there:

your-project/
└── src/
    └── main/
        └── resources/
            └── properties/
                ├── default/               ← auto-generated by SHAFT
                └── custom.properties      ← your file

Control Video Recording Scope

You can control which part of the session is recorded:

File-based
CLI-based
Code-based

src/main/resources/properties/custom.properties
videoParams_recordVideo=true
# Scope options: DriverSession | TestMethod
videoParams_scope=DriverSession

mvn test -DvideoParams_recordVideo=true -DvideoParams_scope=DriverSession

import com.shaft.driver.SHAFT;

SHAFT.Properties.visuals.set()
    .videoParamsRecordVideo(true)
    .videoParamsScope("DriverSession");

Scope	Description
`DriverSession`	Records the entire browser/driver session (default)
`TestMethod`	Records each test method as a separate video

Animated GIFs

Animated GIFs are disabled by default. SHAFT creates them when you explicitly set createAnimatedGif=true, and also enables them automatically for retry attempts when forceCaptureSupportingEvidenceOnRetry=true. GIF frames are captured in the background and do not force every action screenshot to be attached to the report. Generated GIF files are written under video.folder before they are attached to Allure:

File-based
CLI-based
Code-based

src/main/resources/properties/custom.properties
createAnimatedGif=true
# Delay between frames in milliseconds (default: 500)
animatedGif_frameDelay=500

mvn test -DcreateAnimatedGif=true -DanimatedGif_frameDelay=500

import com.shaft.driver.SHAFT;

SHAFT.Properties.visuals.set()
    .createAnimatedGif(true)
    .animatedGifFrameDelay(500);

Recommended Configurations by Use Case

CI/CD Pipeline (archive report as artifact)

src/main/resources/properties/custom.properties
# Do not open the browser during CI
allure.automaticallyOpen=false
# Generate a ZIP artifact to publish from the pipeline
allure.generateArchive=true

Active Debugging (rich visuals)

src/main/resources/properties/custom.properties
# Allure opens automatically by default — add visual evidence
videoParams_recordVideo=true
createAnimatedGif=true
# Attach every action screenshot while actively debugging
screenshotParams_whenToTakeAScreenshot=Always

Quick Pass/Fail Summary

src/main/resources/properties/custom.properties
# Enable fast portable summary alongside the Allure report
openExecutionSummaryReportAfterExecution=true

All Reporting Properties

For the full list of reporting-related properties and their default values, see the Properties List.

Key properties quick reference:

Property	Default	Description
`allure.automaticallyOpen`	`true`	Open the Allure report in the browser automatically after the run
`allure.generateArchive`	`false`	Generate a portable ZIP archive of the Allure report
`allure.accumulateHistory`	`true`	Accumulate history across runs for trend graphs
`allure.accumulateReports`	`true`	Keep previous Allure HTML report files
`allure.cleanResultsDirectory`	`true`	Clean Allure results directory before each run
`allure.customTitle`	`Test run report`	Custom title in the Allure report header
`allure.customLogo`	(SHAFT default logo)	Custom logo URL for the Allure report
`allure.realtimeMonitoring`	`false`	Start native Allure 3 `allure watch` while tests run
`allure.singleFile`	`true`	Generate an Allure 3 Awesome report as a self-contained HTML file
`allure.theme`	`auto`	Default Allure 3 Awesome color mode: `auto`, `light`, or `dark`
`allure.reportLanguage`	`en`	Language code used by the Allure 3 Awesome report UI
`allure.open`	`false`	Pass the browser-open flag to Allure 3 report generation
`allure.groupBy`	`package,testClass`	Comma-separated label hierarchy for the Allure 3 report tree
`openExecutionSummaryReportAfterExecution`	`false`	Open the Execution Summary report after the run
`locatorHealthReportEnabled`	`false`	Generate end-of-run HTML/JSON locator health reports and Allure attachments
`shaft.locatorHealth.enabled`	`false`	Generate end-of-run locator health reports
`shaft.locatorHealth.warnBelowScore`	`70`	Mark locators below this health score as risky
`shaft.locatorHealth.attachDashboard`	`true`	Attach the HTML locator health dashboard to Allure
`shaft.locatorHealth.failBelowScore`	`-1`	Fail the run when any locator score is below this threshold; `-1` disables score-based failure
`slowLocatorThresholdMillis`	`750`	Lookup duration that marks a locator as slow
`failOnLocatorHealthWarnings`	`false`	Fail the run when locator health warnings are present
`shaft.trace.enabled`	`true`	Attach the SHAFT failure trace viewer artifacts
`shaft.trace.mode`	`failure`	Trace mode: `failure`, `retry`, or `always`
`shaft.trace.includeCodeContext`	`true`	Include the best matching source-code frame and snippet
`shaft.trace.includeFullPageSnapshots`	`true`	Include web snapshots when available
`shaft.trace.includeNativePageSource`	`true`	Include Appium/native page source when available
`shaft.trace.includeNetwork`	`true`	Reserve network evidence in the trace metadata
`shaft.trace.includeConsole`	`true`	Reserve console evidence in the trace metadata
`shaft.trace.maxArtifactMb`	`50`	Maximum size for a single trace bundle entry
`videoParams_recordVideo`	`false`	Enable video recording of test sessions
`videoParams_scope`	`DriverSession`	Scope of video recording
`createAnimatedGif`	`false`	Create an animated GIF; retries can enable it automatically
`animatedGif_frameDelay`	`500`	Delay between GIF frames (milliseconds)
`screenshotParams_whenToTakeAScreenshot`	`ValidationPointsOnly`	When to attach screenshots; failed element actions always attach evidence, highlight found elements red, and fall back to a page screenshot when the locator is missing

Report Types at a Glance​

Allure Report​

Failure Trace Viewer​

Open Allure Report Manually​

Disable Auto-Opening the Allure Report​

Generate an Allure Report Archive (for CI/CD)​

Customize the Allure Report​

Tune Allure 3 Awesome Report Output​

Monitor Allure 3 Results While Tests Run​

Troubleshoot Allure CLI Generation​

Accumulate History and Reports Across Runs​

Execution Summary Report​

Enable the Execution Summary Report​

Locator Health Report​

Video Recording​

Where to Put Your Properties File​

Control Video Recording Scope​

Animated GIFs​

Recommended Configurations by Use Case​

CI/CD Pipeline (archive report as artifact)​

Active Debugging (rich visuals)​

Quick Pass/Fail Summary​

All Reporting Properties​

Related​