diff --git a/docs/report_generation.adoc b/docs/report_generation.adoc index 74eb814ffc..1502b8e930 100644 --- a/docs/report_generation.adoc +++ b/docs/report_generation.adoc @@ -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= ---- @@ -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 <> or <> 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 ---- @@ -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=] \ - [--targetDir=] \ +$ java com.tngtech.jgiven.report.ReportGenerator \ + --format=html \ + [--sourceDir=] \ + [--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=] \ + [--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: @@ -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"] +---- + + + + com.tngtech.jgiven + jgiven-maven-plugin + {version} + + + + report + + + + + asciidoc + ${project.build.directory}/jgiven-reports/asciidoc + + + + +---- + +=== 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: @@ -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 @@ -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= 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.