Skip to content

Commit

Permalink
Fixed #381 - Restructure document generation
Browse files Browse the repository at this point in the history
  • Loading branch information
@khmarbaise
khmarbaise committed Oct 28, 2023
1 parent a45be0a commit b4606cc
Show file tree
Hide file tree
Showing 7 changed files with 94 additions and 20 deletions.
Empty file added .mvn/.gitkeep
View file
Empty file.
80 changes: 74 additions & 6 deletions itf-documentation/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,10 @@

<description>ITF Documentation</description>

<properties>
<asciidoc>${project.basedir}/src/main/asciidoc</asciidoc>
</properties>

<dependencies>
<dependency>
<groupId>com.soebes.itf.jupiter.extension</groupId>
Expand All @@ -50,23 +54,91 @@
<artifactId>asciidoctor-maven-plugin</artifactId>
<executions>
<execution>
<id>output-html</id>
<id>concept-html</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<sourceDirectory>${asciidoc}/concept</sourceDirectory>
</configuration>
</execution>
<execution>
<id>background-html</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<sourceDirectory>${asciidoc}/background</sourceDirectory>
</configuration>
</execution>
<execution>
<id>userguide-html</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<sourceDirectory>${asciidoc}/usersguide</sourceDirectory>
</configuration>
</execution>
<execution>
<id>release-notes-html</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<sourceDirectory>${asciidoc}/release-notes</sourceDirectory>
</configuration>
</execution>
<execution>
<id>output-pdf</id>
<id>concept-pdf</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<sourceDirectory>${asciidoc}/concept</sourceDirectory>
</configuration>
</execution>
<execution>
<id>background-pdf</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<sourceDirectory>${asciidoc}/background</sourceDirectory>
</configuration>
</execution>
<execution>
<id>userguide-pdf</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<sourceDirectory>${asciidoc}/usersguide</sourceDirectory>
</configuration>
</execution>
<execution>
<id>release-notes-pdf</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<sourceDirectory>${asciidoc}/release-notes</sourceDirectory>
</configuration>
</execution>
</executions>
Expand All @@ -81,16 +153,12 @@
<revnumber>${project.version}</revnumber>
<linkcss>false</linkcss>
<toc>left</toc>
<imagesdir>../resources/images</imagesdir>
<source-highlighter>coderay</source-highlighter>
</attributes>
<sourceDirectory>src/main/asciidoc</sourceDirectory>
<headerFooter>true</headerFooter>
<preserveDirectories>true</preserveDirectories>
<baseDir>${project.basedir}</baseDir>
<outputDirectory>${project.reporting.outputDirectory}</outputDirectory>
</configuration>

</plugin>

</plugins>
Expand Down
0 ...on/src/main/asciidoc/concept/Concept.adoc → ...on/src/main/asciidoc/concept/concept.adoc
View file
File renamed without changes.
3 changes: 2 additions & 1 deletion itf-documentation/src/main/asciidoc/release-notes/_release-notes-0.13.0.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@
:issue-374: https://github.com/khmarbaise/maven-it-extension/issues/374[Fixed #374]
:issue-375: https://github.com/khmarbaise/maven-it-extension/issues/375[Fixed #375]
:issue-376: https://github.com/khmarbaise/maven-it-extension/issues/376[Fixed #376]
:issue-381: https://github.com/khmarbaise/maven-it-extension/issues/381[Fixed #381]
:issue-??: https://github.com/khmarbaise/maven-it-extension/issues/??[Fixed #??]

:release_0_13_0: https://github.com/khmarbaise/maven-it-extension/milestone/13
Expand Down Expand Up @@ -97,6 +98,6 @@
*Build Improvements*

* {issue-351} - JDK17+ Usage in Tests
* {issue-???} - ??
* {issue-381} - Improved structuring of documentation.

The full release notes can be found here {release_0_13_0}[Release 0.13.0].
5 changes: 3 additions & 2 deletions itf-documentation/src/main/asciidoc/release-notes/release-notes.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,17 +18,18 @@
[[release-notes]]
= Integration Testing Framework Release Notes
Karl Heinz Marbaise; {docdate}
:includedir: _includes
:sourcedir: src/main/asciidoc/release-notes
:numbered!:
:toc: left
:includedir: _includes
:sourcedir: ./

This document contains the _change log_ for all Integration Test Framework
releases since 0.1.0.

Please refer to the <<../user-guide/index.adoc#user-guide,User Guide>> for a comprehensive
overview and detailed instructions how to use the Integration Testing Framework.


include::{sourcedir}/_release-notes-0.13.0.adoc[]

include::{sourcedir}/_release-notes-0.12.0.adoc[]
Expand Down
25 changes: 14 additions & 11 deletions itf-documentation/src/main/asciidoc/usersguide/usersguide.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@ Karl Heinz Marbaise; {docdate}
:sectlinks:
:xrefstyle: full
:toc: left
:includedir: _includes
:sourcedir: ../../../../../
:itf-examples: {sourcedir}/itf-examples
:itf-failure-plugin: {sourcedir}/itf-failure-plugin
//
:junit-jupiter: https://junit.org/junit5/[JUnit Jupiter]
:junit-jupiter-extension: https://junit.org/junit5/docs/current/user-guide/#extensions
Expand All @@ -36,7 +40,6 @@ Karl Heinz Marbaise; {docdate}
:itf-issues: https://github.com/khmarbaise/maven-it-extension/issues
:assertj: https://assertj.github.io/doc/
//
:itfexample: _basedir/../..

[[general.overview]]
== Overview
Expand Down Expand Up @@ -144,7 +147,7 @@ cause you only need them during the integration tests.

[source,xml]
----
include::../../../../../itf-examples/pom.xml[tag=dependencies]
include::{itf-examples}/pom.xml[tag=dependencies]
----
The dependency `com.soebes.itf.jupiter.extension:itf-assertj` contains custom assertions of {assertj}[AssertJ]
in case you want to use {assertj}[AssertJ] as your assertion framework. This means you have to include
Expand All @@ -166,7 +169,7 @@ like this:

[source,xml]
----
include::../../../../../itf-examples/pom.xml[tag=itf-maven-plugin]
include::{itf-examples}/pom.xml[tag=itf-maven-plugin]
----
//FIXME: Needed to be changed after itf-maven-plugin will run also the tests.
The `itf-maven-plugin` copies the code of your extension/plugin into appropriate directories which are
Expand All @@ -177,7 +180,7 @@ Finally you have to add a configuration for {maven-failsafe-plugin} like the fol

[source,xml]
----
include::../../../../../itf-examples/pom.xml[tag=failsafe]
include::{itf-examples}/pom.xml[tag=failsafe]
----
The given properties like `maven.version` transfers the version of Maven which is used
within the `itf-jupiter-extension` to run your integration tests and the `maven.home` transfers the
Expand Down Expand Up @@ -1548,24 +1551,24 @@ That will not filter anything.

Another example of using the assertions could look like this:

include::../../../../../itf-examples/src/test/java/com/soebes/itf/examples/LogoutputIT.java[tag=stdout]
include::{itf-examples}/src/test/java/com/soebes/itf/examples/LogoutputIT.java[tag=stdout]

This will extract all messages with the prefix `[INFO] ` of the log and check if there is
at least one line which contains the given content.

We can check for warnings like the following:

include::../../../../../itf-examples/src/test/java/com/soebes/itf/examples/LogoutputIT.java[tag=warning]
include::{itf-examples}/src/test/java/com/soebes/itf/examples/LogoutputIT.java[tag=warning]

You can access directly the `stdout` and/or the `stderr` of the Maven build and do things yourself
if you prefer to go that way. In this case you have to add another injection to the test case
(`MavenLog mavenLog` or like this `result.getMavenLog().getStdout()`).

include::../../../../../itf-examples/src/test/java/com/soebes/itf/examples/LogoutputIT.java[tag=selfmade]
include::{itf-examples}/src/test/java/com/soebes/itf/examples/LogoutputIT.java[tag=selfmade]

The `stderr` output can be accessed as well like this:

include::../../../../../itf-examples/src/test/java/com/soebes/itf/examples/LogoutputIT.java[tag=error]
include::{itf-examples}/src/test/java/com/soebes/itf/examples/LogoutputIT.java[tag=error]

A full-fledged example can be found `itf-examples/src/test/java/com/soebes/itf/examples/LogoutputIT.java`
within the itf project.
Expand Down Expand Up @@ -1684,7 +1687,7 @@ the build cause the plugin needs to be configured.

[source,xml]
----
include::../../../../../itf-failure-plugin/src/test/resources-its/com/soebes/itf/maven/plugin/failure/FailureIT/basic_configuration/pom.xml[tag=configuration]
include::{itf-failure-plugin}/src/test/resources-its/com/soebes/itf/maven/plugin/failure/FailureIT/basic_configuration/pom.xml[tag=configuration]
----

The plugin does not bind to any life cycle phase by default which is intentionally to require a binding
Expand All @@ -1697,15 +1700,15 @@ exception can given via `exception` configuration part.

[source,xml]
----
include::../../../../../itf-failure-plugin/src/test/resources-its/com/soebes/itf/maven/plugin/failure/FailureIT/fail_with_mojo_execution_exception/pom.xml[tag=configuration]
include::{itf-failure-plugin}/src/test/resources-its/com/soebes/itf/maven/plugin/failure/FailureIT/fail_with_mojo_execution_exception/pom.xml[tag=configuration]
----

The final example will fail the build with a `MojoFailureException` (failureException=true) and the text of the exception
can given via `exception` configuration part as before.

[source,xml]
----
include::../../../../../itf-failure-plugin/src/test/resources-its/com/soebes/itf/maven/plugin/failure/FailureIT/fail_with_mojo_failure_exception/pom.xml[tag=configuration]
include::{itf-failure-plugin}/src/test/resources-its/com/soebes/itf/maven/plugin/failure/FailureIT/fail_with_mojo_failure_exception/pom.xml[tag=configuration]
----


Expand Down
1 change: 1 addition & 0 deletions pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,7 @@
<exclude>.repository/**</exclude><!-- Jenkins job with local Maven repository -->
<exclude>.repo/**</exclude><!-- Jenkins job with local Maven repository -->
<exclude>.maven/spy.log</exclude><!-- Hudson Maven3 integration log -->
<exclude>.mvn/*</exclude><!-- Maven Configuration -->
<exclude>dependency-reduced-pom.xml</exclude><!-- Maven shade plugin -->
<exclude>.asf.yaml</exclude><!-- GitHub Support -->
<exclude>.java-version</exclude>
Expand Down

0 comments on commit b4606cc

Please sign in to comment.