Skip to content
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

Jump to bottom

Add initial documentation for the AsciiDoc reporter #1353

Draft
wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

Add initial documentation for the AsciiDoc reporter #1353

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
195ee1a
Add initial documentation for the AsciiDoc reporter
johthor Jul 24, 2023
1a9685d
Add experimental remark to AsciiDoc reporter description
johthor Nov 23, 2023
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
137 changes: 103 additions & 34 deletions docs/report_generation.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,33 +2,32 @@

=== Plain Text Reports

By default JGiven outputs plain text reports to the console when executed. To disable plain text reports set the following Java system property:
By default, JGiven outputs plain text reports to the console when executed. To disable plain text reports set the following Java system property:

[source,java]
[source,properties]
----
jgiven.report.text=false
----

=== JSON Reports

By default JGiven will generate JSON reports into the `jgiven-reports/json` directory. JGiven tries to autodetect when it is executed by the Maven surefire plugin and in that case generates the reports into `target/jgiven-reports/json`. To disable JSON report generation set the following Java system property:
By default, JGiven will generate JSON reports into the `jgiven-reports/json` directory. JGiven tries to autodetect when it is executed by the Maven surefire plugin and in that case generates the reports into `target/jgiven-reports/json`. To disable JSON report generation set the following Java system property:

[source,java]
[source,properties]
----
jgiven.report.enabled=false
----

[NOTE]
====
In order to generate HTML reports, JSON reports are required.
In order to generate HTML or AsciiDoc reports, JSON reports are required.
====

==== Change report directory

If you want to change the `jgiven-reports/json` directory, respectively `target/jgiven-reports/json`, set the following Java system property:


[source,java]
[source,properties]
----
jgiven.report.dir=<targetDir>
----
Expand All @@ -37,15 +36,18 @@ If JGiven is executed by the Maven surefire plugin, this can be done by the syst

[NOTE]
====
In case HTML Reports are being generated, the source directory for the JSON Reports needs to be set accordingly (see "HTML Report" for more).
In case HTML or AsciiDoc reports are being generated,
the source directory for the JSON reports needs to be set accordingly
(see <<HTML Report>> or <<AsciiDoc Report>> for more).
====

=== Dry Run
==== Dry Run

There is a dry run option, which just generates a report without actually
executing the code. This might be helpful to generate a test report quickly
without having to wait for the tests to be executed.

[source,java]
[source,properties]
----
jgiven.report.dry-run=true
----
Expand All @@ -65,19 +67,41 @@ The report generator can be executed on the command line as
follows (assuming that the `jgiven-core` and the `jgiven-html5-report` JAR
and all required dependencies are on the Java CLASSPATH)


[source,bash]
[source,console]
----
java com.tngtech.jgiven.report.ReportGenerator \
--format=html \
[--sourceDir=<jsonreports>] \
[--targetDir=<targetDir>] \
$ java com.tngtech.jgiven.report.ReportGenerator \
--format=html \
[--sourceDir=<jsonreports>] \
[--targetDir=<targetDir>] \
----

To see the HTML report in action you can have a look at the
https://jgiven.org/jgiven-report/html5/[HTML report of JGiven itself]

==== Maven
=== AsciiDoc Report

[CAUTION]
====
The generator for AsciiDoc reports is currently still in an experimental phase.
Not all functions of the HTML report are supported.
====

To generate an AsciiDoc report you have to run the JGiven report generator with the `asciidoc` format option.
The report generator can be executed on the command line as follows
(assuming that the `jgiven-core` JAR and all required dependencies are on the Java CLASSPATH)

[source,console]
----
$ java com.tngtech.jgiven.report.ReportGenerator \
--format=asciidoc \
[--sourceDir=<jsonreports>] \
[--targetDir=<targetDir>]
----

To see the AsciiDoc report in action you can have a look at the
https://jgiven.org/jgiven-report/asciidoc/[AsciiDoc report of JGiven itself]

=== Maven Plugin

For Maven there exists a plugin that can be used as follows:

Expand Down Expand Up @@ -107,44 +131,79 @@ For Maven there exists a plugin that can be used as follows:
You can add the following configuration options (like the _format_ configuration above) to customize the report.
All of them are optional.

[cols="1,3"]
[%autowidth]
.Configuration Options for Reports
|===
|Option |Description
|Option |Default value |Description

|format
|The format of the generated report. Can be _html_ or _text_. Default: _html_
|`html`
|The format of the generated report. Can be _html_, _text_ or _asciidoc_.

|title
|The title of the generated report. Default: _JGiven Report_
|`JGiven Report`
|The title of the generated report.

|customCssFile
|Custom CSS file to customize the HTML report. Default: _src/test/resources/jgiven/custom.css_
|`src/test/resources/jgiven/custom.css`
|Custom CSS file to customize the HTML report.

|customJsFile
|Custom JS file to customize the HTML report. Default: _src/test/resources/jgiven/custom.js_
|`src/test/resources/jgiven/custom.js`
|Custom JS file to customize the HTML report.

|excludeEmptyScenarios
|Whether or not to exclude empty scenarios, i.e. scenarios without any steps, from the report. Default: _false_
|`false`
|Whether or not to exclude empty scenarios, i.e. scenarios without any steps, from the report.

|outputDirectory
|Directory where the reports are generated to. Default: _${project.build.directory}/jgiven-reports/html_
|`${project.build.directory}/jgiven-reports/html`
|Directory where the reports are generated to.

|sourceDirectory
|Directory to read the JSON report files from. Default: _${project.build.directory}/jgiven-reports/json_

|`${project.build.directory}/jgiven-reports/json`
|Directory to read the JSON report files from.
|===

Now run:

[source,bash]
[source,console]
----
$ mvn verify
----

HTML reports are then generated into the `target/jgiven-reports/html` directory. Note that the plugin relies on the existence of the JSON output, so if the property `jgiven.reports.enabled` was set to `false`, no output will be generated.
HTML reports are then generated into the `target/jgiven-reports/html` directory.
Note that the plugin relies on the existence of the JSON output,
so if the property `jgiven.reports.enabled` was set to `false`,
no output will be generated.

==== Gradle
Use the following configuration to generate the AsciiDoc report instead of the HTML report.

[source,xml,subs="verbatim,attributes"]
----
<build>
<plugins>
<plugin>
<groupId>com.tngtech.jgiven</groupId>
<artifactId>jgiven-maven-plugin</artifactId>
<version>{version}</version>
<executions>
<execution>
<goals>
<goal>report</goal>
</goals>
</execution>
</executions>
<configuration>
<format>asciidoc</format>
<outputDirectory>${project.build.directory}/jgiven-reports/asciidoc</outputDirectory>
</configuration>
</plugin>
</plugins>
</build>
----

=== Gradle Plugin

There also exists a plugin for Gradle to make your life easier.
Add the following plugins section to your `build.gradle` file or extend the one you have already accordingly:
Expand Down Expand Up @@ -173,17 +232,19 @@ buildscript {
}

apply plugin: "com.tngtech.jgiven.gradle-plugin"

----

Now run:

[source,bash]
[source,console]
----
$ gradle test jgivenTestReport
----

HTML reports are then generated into the `build/reports/jgiven/test/html/` directory. Note that the plugin relies on the existence of the JSON output, so if the property `jgiven.reports.enabled` was set to `false`, no output will be generated.
HTML reports are then generated into the `build/reports/jgiven/test/html/` directory.
Note that the plugin relies on the existence of the JSON output,
so if the property `jgiven.reports.enabled` was set to `false`,
no output will be generated.

If you want that the HTML report is always generated after the tests
have been executed, you can configure the `test` task in your Gradle
Expand All @@ -201,19 +262,27 @@ https://plugins.gradle.org/plugin/com.tngtech.jgiven.gradle-plugin

JGiven will optionally load a configuration properties file, defaulting to:
`jgiven.properties`. The path to the configuration can be customized with the system property:

----
jgiven.config.path
----

The encoding for the file is assumed to be `UTF-8`, but can be customized with the system property:

----
jgiven.config.charset
----

The following can be defined in the properties file:

[source,properties]
----
jgiven.report.enabled=false
jgiven.report.dir=<targetDir>
jgiven.report.text=false
jgiven.report.text.color
jgiven.report.text.color=auto
jgiven.report.filterStackTrace=true
jgiven.report.dry-run=false
----

Configuration defined via Java system properties will take precedence over values in the configuration file.