Fixed #359 - ITF class level annotations misbehave

khmarbaise · Dec 25, 2023 · dc7cdef · dc7cdef
1 parent 04ed054
commit dc7cdef
Show file tree

Hide file tree

Showing 10 changed files with 752 additions and 27 deletions.
diff --git a/itf-documentation/src/main/asciidoc/release-notes/_release-notes-0.13.0.adoc b/itf-documentation/src/main/asciidoc/release-notes/_release-notes-0.13.0.adoc
@@ -34,6 +34,7 @@
 :issue-351: https://github.com/khmarbaise/maven-it-extension/issues/351[Fixed #351]
 :issue-353: https://github.com/khmarbaise/maven-it-extension/issues/353[Fixed #353]
 :issue-355: https://github.com/khmarbaise/maven-it-extension/issues/355[Fixed #355]
+:issue-359: https://github.com/khmarbaise/maven-it-extension/issues/359[Fixed #359]
 :issue-360: https://github.com/khmarbaise/maven-it-extension/issues/360[Fixed #360]
 :issue-362: https://github.com/khmarbaise/maven-it-extension/issues/362[Fixed #362]
 :issue-364: https://github.com/khmarbaise/maven-it-extension/issues/364[Fixed #363]
@@ -94,11 +95,56 @@
                  Also all Maven Version for `M3_0_5` up to `M3_5_4` have been marked deprecated to indicate that those
                  versions are very old and shouldn't be used anymore; Not even in tests (You should upgrade your Maven
                  version)
+ * {issue-359} - ITF class level annotations misbehave
+ ** if you have used `@MavenProfile` annotation on class level with profiles and relied on the behaviour that
+    on a method or a nested class a definition of another `@MavenProfile` replaced all the original profiles
+    during the execution. That behaviour has been changed. Please refer to the users guide about `@MavenProfile`
+    annotation and it particular behaviour. The following example shows the behaviour in release 0.12.0:
++
+[source,java]
+----
+@MavenProfile({"profile-1", "profile-2", "profile-3"})
+class ProfileOnClassIT {
+
+  @MavenTest
+  void profile_1_2_3(MavenExecutionResult result) {
+     ...
+  }
+
+  @MavenTest
+  @MavenProfile("profile-1")
+  void profile_1(MavenExecutionResult result) {
+    ...
+  }
+}
+----
++
+The way to achieve the same with the release 0.13.0, you have to express is like this:
++
+[source,java]
+----
+@MavenProfile({"profile-1"})
+class ProfileOnClassIT {
+
+  @MavenTest
+  @MavenProfile({"profile-2", "profile-3"})
+  void profile_1_2_3(MavenExecutionResult result) {
+     ...
+  }
+
+  @MavenTest
+  void profile_1(MavenExecutionResult result) {
+    ...
+  }
+}
+----
+
+
 
 *Reporter of this release*
 
- * ???
-   ** Reported ..
+ * {issue-359}
+   ** https://github.com/cstamas[Tamas Cservenak] has reported the issue.
 
 *Contributors of this release*
 

diff --git a/itf-documentation/src/main/asciidoc/usersguide/usersguide.adoc b/itf-documentation/src/main/asciidoc/usersguide/usersguide.adoc
@@ -553,6 +553,46 @@ class BasicIT {
 The `+` prefix is responsible for deactivating a given profile during the build. We strongly recommend to use `+`
 sign (instead of `!`) to prevent issues on different operating systems.
 
+So finally let use show how the inheritance behaviour of the `MavenProfile` annotation is defined.
+
+[source,java]
+----
+@MavenJupiterExtension
+@MavenProfile({"run-its"})
+class BasicIT {
+
+  @MavenTest
+  @MavenProfile("run-its-delta")
+  void first(MavenExecutionResult result) {
+    ..
+  }
+
+  @MavenTest
+  void second(MavenExecutionResult result) {
+    ..
+  }
+
+  @Nested
+  @MavenProfile("nested-class")
+  class NestedClass {
+    @MavenTest
+    @MavenProfile("nested-first")
+    void nested_first(MavenExecutionResult result) {
+      ..
+    }
+    @MavenTest
+    void nested_second(MavenExecutionResult result) {
+      ..
+    }
+  }
+}
+----
+So based on the given example the method `first` will be executed with the activation of the profiles
+`run-its` and `run-its-delta`. The method `second` will be execute with the activated profile `run-its`. The method
+`nested_first` will be executed with the activated profiles `run-its`, `nested-class`and `nested-first`. Finally the
+method `nested_second` will be executed with the activated profiles `run-its` and `nested-class`.
+
+
 [[structuring.system.properties]]
 === System Properties
 
@@ -662,6 +702,54 @@ class RunningIT
 ----
 This prevents the repetition of the property on each test case method.
 
+
+Another option is to define the `SystemProperty` annotation on different levels. For example
+class level, method level or nested levels. Let us make deep dive into the following example:
+[source,java]
+----
+..
+@MavenJupiterExtension
+@SystemProperty("skipTests")
+class RunningIT
+{
+
+    @MavenTest
+    void first( MavenExecutionResult result )
+    {
+       ...
+    }
+
+    @MavenTest
+    @SystemProperty("second")
+    void second( MavenExecutionResult result )
+    {
+       ...
+    }
+
+    @Nested
+    @SystemProperty("NestedLevel")
+    class NestedLevel {
+      @MavenTest
+      void nested_first( MavenExecutionResult result )
+      {
+         ...
+      }
+
+      @MavenTest
+      @SystemProperty("NestedLevelSecond")
+      void nested_second( MavenExecutionResult result )
+      {
+         ...
+      }
+
+    }
+}
+----
+The method `first` will be executed with the defined system property `skipTests` given by the class level `RunningIT`.
+The method `second` will be executed with the defined system properties `skipTests` and also with the `second` property.
+The method `nested_first` will be executed with the following system properties `skipTests` and `NestedLevel` while the
+method `nested_second` will be executed with the following system properties `skipTest`, `NestedLevel` and `NestedLevelSecond`.
+
 [[goals.command.line.options]]
 === Command Line Options
 In different scenarios it is needed to define command line options for example `--non-recursive` etc.
@@ -770,6 +858,43 @@ class BasicIT {
 Now let us summarize the information for goals. As long as no explicit `@MavenGoal` is defined the
 default will be used which is `package`.
 
+Furthermore we can define goal annotation `MavenGoal` on different levels which means class level, method level,
+nested classes etc. We will look at the following example:
+
+[source,java]
+----
+@MavenJupiterExtension
+@MavenGoal("clean")
+class BasicIT {
+
+  @MavenTest
+  void first(MavenExecutionResult result) {
+  }
+
+  @MavenTest
+  @MavenGoal("install")
+  void second(MavenExecutionResult result) {
+  }
+
+  @Nested
+  @MavenGoal("verify")
+  class NestedLevel {
+    @MavenTest
+    void nested_first(MavenExecutionResult result) {
+    }
+    @MavenTest
+    @MavenGoal("site:stage")
+    void nested_second(MavenExecutionResult result) {
+    }
+
+  }
+}
+----
+How would the above test cases executed related to the defined goal annotation? The method `first` will
+be executed with the goal `clean`. The method `second` will be executed with the goals `clean` and `install`.
+The method `nested_first` in the nested class `NestedLevel` will be executed with the goals `clean` and `verify`
+and finally the method `nested_second` will be exectuted with the goals `clean`, `verify` and `site:stage`.
+
 [[structuring.options]]
 ==== Options
 Now let us going back to the example:
@@ -804,7 +929,7 @@ class BasicIT {
 }
 ----
 Using the option like this means (like for goals as mentioned before) all consecutive tests will
-now run with the given option which in this case is only a single command line option `--debug`
+now run with the given option which in this case is only a single command line option `--verbose`
 and nothing else. You can add supplemental command line options just by adding supplemental
 annotations to your tests like this:
 [source,java]
@@ -852,6 +977,45 @@ default will be used which are the following:
 * `--batch-mode`
 * `--errors`
 
+What will happen if you have a test class like this with nested class and the appropriate annotations:
+[source,java]
+----
+@MavenJupiterExtension
+@MavenOption(MavenCLIOptions.VERBOSE)
+class BasicIT {
+
+  @MavenTest
+  @MavenOption(MavenCLIOptions.FAIL_AT_END)
+  void first(MavenExecutionResult result) {
+     ...
+  }
+  @MavenTest
+  void second(MavenExecutionResult result) {
+     ...
+  }
+
+  @MavenOption(MavenCLIOptions.FAIL_FAST)
+  class NestedClass {
+   @MavenTest
+   void nested_first(MavenExecutionResult result) {
+     ...
+   }
+   @MavenTest
+   @MavenOption(MavenCLIOptions.FAIL_NEVER)
+   void nested_second(MavenExecutionResult result) {
+     ...
+   }
+
+  }
+}
+----
+Let us analyze that. The method `second` will be executed with the option `--verbose` while the
+method `first` will be executed with two options `--verbose` and `--fail-at-end`. Now the interesting part.
+The method `nested_first` will be executed with the options `--verbose` plus the `--fail-fast` and the method
+`nested_second` will be executed with `--verbose`, `--fail-fast` and `--fail-never`. Just ignore that the
+combination of those options does not really makes sense. It's only to show the behaviour over different inheritance
+levels. In other words the behaviour of the `MavenOption` annotation is additive (except for the root level!).
+
 [[structuring.combined.annotations]]
 ==== Combined Annotation
 Sometimes you would like to combine things from options and goals in a more convenient way.