Skip to content

docs: document Allure 3 config flags (singleFile, reportLanguage, open, groupBy) #496

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MohabMohie wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: document Allure 3 config flags (singleFile, reportLanguage, open, groupBy) #496

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/Basic_Config/basicConfig.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,12 @@ createAnimatedGif=true

# Record a full MP4 video of each test execution
videoParams_recordVideo=true

# Keep the Allure 3 Awesome report portable as one HTML file
allure.singleFile=true

# Group the Allure report tree by suite labels
allure.groupBy=parentSuite,suite,subSuite
```

---
Expand Down
18 changes: 17 additions & 1 deletion docs/Properties/PropertiesList.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -416,6 +416,10 @@ This section lists all configurable properties related to Swagger/OpenAPI contra
boolean generateArchive = SHAFT.Properties.allure.generateArchive();
String customLogo = SHAFT.Properties.allure.customLogo();
String customTitle = SHAFT.Properties.allure.customTitle();
boolean singleFile = SHAFT.Properties.allure.singleFile();
String reportLanguage = SHAFT.Properties.allure.reportLanguage();
boolean open = SHAFT.Properties.allure.open();
String groupBy = SHAFT.Properties.allure.groupBy();

/** set **/
SHAFT.Properties.allure.set()
Expand All @@ -425,7 +429,11 @@ This section lists all configurable properties related to Swagger/OpenAPI contra
.cleanResultsDirectory(true)
.generateArchive(false)
.customLogo("https://example.com/logo.png")
.customTitle("My Test Suite Report");
.customTitle("My Test Suite Report")
.singleFile(true)
.reportLanguage("en")
.open(false)
.groupBy("parentSuite,suite,subSuite");
```

</TabItem>
Expand All @@ -440,6 +448,10 @@ This section lists all configurable properties related to Swagger/OpenAPI contra
allure.generateArchive=false
allure.customLogo=https://example.com/logo.png
allure.customTitle=My Test Suite Report
allure.singleFile=true
allure.reportLanguage=en
allure.open=false
allure.groupBy=parentSuite,suite,subSuite
```

</TabItem>
Expand All @@ -454,6 +466,10 @@ This section lists all configurable properties related to Swagger/OpenAPI contra
| allure.generateArchive | `false` | `true`, `false` | • Generate a self-contained ZIP archive of the Allure report after test execution. Useful for sharing or archiving in CI pipelines. *(previously: `generateAllureReportArchive`)* |
| allure.customLogo | *(SHAFT default logo URL)* | URL or local file path | • URL or local path to a custom logo image to replace the default SHAFT logo in the Allure report. |
| allure.customTitle | `Test run report` | Any string | • Custom title displayed in the header of the generated Allure report. |
| allure.singleFile | `true` | `true`, `false` | • Controls the Allure 3 Awesome plugin `singleFile` option. When `true`, the report is generated as a self-contained HTML file. |
| allure.reportLanguage | `en` | Language code, such as `en`, `fr`, or `ru` | • Controls the Allure 3 Awesome plugin `reportLanguage` option used by the generated report UI. |
| allure.open | `false` | `true`, `false` | • Controls the Allure 3 Awesome plugin `open` option passed to Allure CLI report generation. |
| allure.groupBy | `parentSuite,suite,subSuite` | Comma-separated Allure label names | • Controls the Allure 3 Awesome plugin `groupBy` hierarchy. Common values include `epic,feature,story` and `package,class,method`. |

</TabItem>
</Tabs>
Expand Down
69 changes: 69 additions & 0 deletions docs/Reporting/reporting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,71 @@ SHAFT.Properties.allure.set()
</TabItem>
</Tabs>

### 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 now control the Awesome plugin options that affect packaging, language, browser opening, and the hierarchy shown in the report tree.

:::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.
:::

<Tabs groupId="configMethod">
<TabItem value="file" label="File-based">

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

# 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: parentSuite,suite,subSuite)
allure.groupBy=parentSuite,suite,subSuite
```

</TabItem>
<TabItem value="cli" label="CLI-based">

```bash
mvn test \
-Dallure.singleFile=false \
-Dallure.reportLanguage=fr \
-Dallure.open=false \
-Dallure.groupBy=package,class,method
```

</TabItem>
<TabItem value="code" label="Code-based">

```java
import com.shaft.driver.SHAFT;

SHAFT.Properties.allure.set()
.singleFile(false)
.reportLanguage("fr")
.open(false)
.groupBy("package,class,method");
```

</TabItem>
</Tabs>

Common `allure.groupBy` presets include:

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

### 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:
Expand Down Expand Up @@ -368,6 +433,10 @@ Key properties quick reference:
| `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.singleFile` | `true` | Generate an Allure 3 Awesome report as a self-contained HTML file |
| `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` | `parentSuite,suite,subSuite` | Comma-separated label hierarchy for the Allure 3 report tree |
| `openExecutionSummaryReportAfterExecution` | `false` | Open the Execution Summary report after the run |
| `videoParams_recordVideo` | `false` | Enable video recording of test sessions |
| `videoParams_scope` | `DriverSession` | Scope of video recording |
Expand Down
Loading