Changed @must to @PostConstructMustBe and replaced enumeration with class reference in order to be more extendable

Author: slu-it

documentation/README.md

@@ -14,10 +14,10 @@
   - [@Cached](chapters/annotation-cached.md)
   - [@IdentifyUsing](chapters/annotation-identify-using.md)
   - [@Mark](chapters/annotation-mark.md)
-  - [@Must](chapters/annotation-must.md)
   - [@Named](chapters/annotation-named.md)
   - [@PostConstruct](chapters/annotation-post-construct.md)
-  - [@Wait](chapters/annotation-wait-until.md)
+  - [@PostConstructMustBe](chapters/annotation-post-construct-must-be.md)
+  - [@WaitUntil](chapters/annotation-wait-until.md)
 - Utility Classes
   - [Conditions](chapters/conditions.md)
   - [ByProducers](chapters/by-producers.md)

documentation/chapters/annotation-must.md renamed to documentation/chapters/annotation-post-construct-must-be.md

@@ -1,28 +1,23 @@
 [Home](../README.md)
 
-# @Must
+# @PostConstructMustBe
 This annotation can be added to `@IdentifyUsing` annotated methods of `Page` or `PageFragment` subclasses.
 Every annotated method will be invoked after an instance of this subclass was initialized and the condition provided by 
 the annotation will be checked. This mechanism is intended to be used in order to prevent unnecessary `@PostConstruct` 
 methods to check basic conditions of parts of the page / fragment. As with `@PostConstruct`, the order in which these 
 methods are invoked / checked is not deterministic!
 
-> Collection and Streams are currently NOT supported!
-
-**The following conditions are available:**
+It is important to note that not all Predicate classes will work with this annotation.
+The mechanism with which the predicate is evaluated will initialize the given class via reflection
+and needs a default constructor to work!
 
-- `VISIBLE`: The fragment is displayed on the current page.
-- `PRESENT`: The fragment is present in the current page's DOM.
-- `PRESENT_AND_VISIBLE`: The fragment is present in the current page's DOM and is displayed.
-- `ENABLED`: The fragment is enabled / not disabled.
-- `EDITABLE`: The fragment is enabled and not 'read-only'
-- `INTERACTABLE`: The fragment is visible and editable.
+> Collection and Streams are currently NOT supported!
 
 **Example for page:**
 ```java
 public interface FooPage extends Page {
 
-    @Must(Be.VISIBLE)
+    @PostConstructMustBe(Visible.class)
     @IdentifyUsing("#foo")
     FooWidget widget();
 
@@ -35,11 +30,11 @@ public interface FooPage extends Page {
 ```java
 public interface FooWidget extends PageFragment {
 
-    @Must(Be.VISIBLE)
+    @PostConstructMustBe(Visible.class)
     @IdentifyUsing("#one")
     TextField fieldOne();
 
-    @Must(Be.VISIBLE)
+    @PostConstructMustBe(Visible.class)
     @IdentifyUsing("#two")
     TextField fieldTwo();
 
@@ -50,17 +45,17 @@ public interface FooWidget extends PageFragment {
 
 ## Combination with @WaitUntil
 
-The `@Must` annotation can be used in combination with `WaitUntil`. This is especially useful in AJAX heavy applications
-where a fragment might be created with a short delay.
+The `@PostConstructMustBe` annotation can be used in combination with `WaitUntil`. This is especially useful in AJAX heavy
+applications where a fragment might be created with a short delay.
 
 **Example:**
 In this example the `widget` is checked as soon as `BarPage` is initialized. But `WaitUntil` will be triggered when invoking 
 the method assuring that the widget is present before checking if it is visible.
 ```java
 public interface BarPage extends Page {
 
-    @Must(Be.VISIBLE)
-    WaitUntil(Present.class)
+    @PostConstructMustBe(Visible.class)
+    @WaitUntil(Present.class)
     @IdentifyUsing("#bar")
     BarWidget widget();
 

documentation/chapters/annotation-post-construct.md

@@ -10,8 +10,8 @@ The order in which multiple annotated methods are invoked is not deterministic.
 
 Since these methods are invoked using reflection, it is not possible to have method arguments!
 
-As an alternative for `@PostConstruct` the `@Must` annotation can be used on page fragment returning methods.
-For more about that see [@Must](annotation-must.md).
+As an alternative for `@PostConstruct` the `@PostConstructMustBe` annotation can be used on page fragment returning methods.
+For more about that see [@PostConstructMustBe](chapters/annotation-post-construct-must-be.md).
 
 **Example for page:**
 ```java
@@ -55,4 +55,4 @@ public interface FooWidget extends PageFragment {
 
 - [Pages](page.md)
 - [Page Fragments](page-fragment.md)
-- [@Must](annotation-must.md)
+- [@PostConstructMustBe](chapters/annotation-post-construct-must-be.md)

documentation/chapters/page-fragment.md

@@ -93,9 +93,9 @@ These annotations can be used within a `PageFragment`.
 - [@Cached](annotation-cached.md)
 - [@IdentifyUsing](annotation-identify-using.md)
 - [@Mark](annotation-mark.md)
-- [@Must](annotation-must.md)
 - [@Named](annotation-named.md)
 - [@PostConstruct](annotation-post-construct.md)
+- [@PostConstructMustBe](chapters/annotation-post-construct-must-be.md)
 - [@WaitUntil](annotation-wait-until.md)
 
 # Linked Documentation

documentation/chapters/page.md

@@ -95,9 +95,9 @@ These annotations can be used within a `Page`.
 - [@Action](annotation-action.md)
 - [@Cached](annotation-cached.md)
 - [@IdentifyUsing](annotation-identify-using.md)
-- [@Must](annotation-must.md)
 - [@Named](annotation-named.md)
 - [@PostConstruct](annotation-post-construct.md)
+- [@PostConstructMustBe](chapters/annotation-post-construct-must-be.md)
 - [@WaitUntil](annotation-wait-until.md)
 
 # Anatomy of a Page 

webtester-core/src/main/java/info/novatec/testit/webtester/internal/must/MustChecker.java

@@ -11,19 +11,18 @@
 
 import info.novatec.testit.webtester.internal.exceptions.IllegalSignatureException;
 import info.novatec.testit.webtester.pagefragments.PageFragment;
-import info.novatec.testit.webtester.pagefragments.annotations.Be;
 import info.novatec.testit.webtester.pagefragments.annotations.IdentifyUsing;
-import info.novatec.testit.webtester.pagefragments.annotations.Must;
+import info.novatec.testit.webtester.pagefragments.annotations.PostConstructMustBe;
 import info.novatec.testit.webtester.pages.Page;
 
 
 public final class MustChecker {
 
     private static final String ILLEGAL_SIGNATURE_MSG =
-        "invalid @Must method declarations (returns PageFragment and has no parameters): ";
+        "invalid @PostConstructMustBe method declarations (returns PageFragment and has no parameters): ";
 
     private static Predicate<Method> isIdentificationMethod = method -> method.isAnnotationPresent(IdentifyUsing.class);
-    private static Predicate<Method> isMustMethod = method -> method.isAnnotationPresent(Must.class);
+    private static Predicate<Method> isMustMethod = method -> method.isAnnotationPresent(PostConstructMustBe.class);
     private static Predicate<Method> isRelevantMethod = isIdentificationMethod.and(isMustMethod);
     private static Predicate<Method> returnsPageFragment =
         method -> PageFragment.class.isAssignableFrom(method.getReturnType());
@@ -76,13 +75,13 @@ private static void assertThatAllMethodsHaveValidSignature(List<Method> mustMeth
 
     private static void invoke(Method method, Object object) {
         try {
-            Must annotation = method.getAnnotation(Must.class);
+            PostConstructMustBe annotation = method.getAnnotation(PostConstructMustBe.class);
             PageFragment fragment = ( PageFragment ) method.invoke(object);
-            Be condition = annotation.value();
-            if (!condition.checkFor(fragment)) {
-                throw new MustConditionException("condition not met for method (" + method + "): " + condition);
+            Predicate<PageFragment> predicate = annotation.value().newInstance();
+            if (!predicate.test(fragment)) {
+                throw new MustConditionException("condition not met for method (" + method + "): " + predicate);
             }
-        } catch (IllegalAccessException | InvocationTargetException e) {
+        } catch (IllegalAccessException | InvocationTargetException | InstantiationException e) {
             throw new MustConditionException(e);
         }
     }

webtester-core/src/main/java/info/novatec/testit/webtester/internal/must/MustConditionException.java

@@ -5,14 +5,15 @@
 
 public class MustConditionException extends WebTesterException {
 
-    private static final String MESSAGE = "Invocation of @Must annotated method failed! See cause for details:";
+    private static final String MESSAGE =
+        "Invocation of @PostConstructMustBe annotated method failed! See cause for details:";
 
     public MustConditionException(String message) {
         super(message);
     }
 
     public MustConditionException(Throwable cause) {
-        super(MESSAGE,cause);
+        super(MESSAGE, cause);
     }
 
 }

webtester-core/src/main/java/info/novatec/testit/webtester/pagefragments/annotations/Be.java

@@ -0,0 +1,76 @@
+package info.novatec.testit.webtester.pagefragments.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.util.function.Predicate;
+
+import info.novatec.testit.webtester.conditions.Conditions;
+import info.novatec.testit.webtester.conditions.pagefragments.Disabled;
+import info.novatec.testit.webtester.conditions.pagefragments.Editable;
+import info.novatec.testit.webtester.conditions.pagefragments.Enabled;
+import info.novatec.testit.webtester.conditions.pagefragments.Interactable;
+import info.novatec.testit.webtester.conditions.pagefragments.Invisible;
+import info.novatec.testit.webtester.conditions.pagefragments.Present;
+import info.novatec.testit.webtester.conditions.pagefragments.PresentAndVisible;
+import info.novatec.testit.webtester.conditions.pagefragments.ReadOnly;
+import info.novatec.testit.webtester.conditions.pagefragments.Selected;
+import info.novatec.testit.webtester.conditions.pagefragments.Visible;
+import info.novatec.testit.webtester.pagefragments.PageFragment;
+import info.novatec.testit.webtester.pages.Page;
+
+
+/**
+ * Identification methods of {@link Page pages} and {@link PageFragment page fragments} can be annotation with this
+ * annotation. Doing so will trigger an automatic post construct check on the page / page fragment after it's
+ * initialization. This check will take the {@link PostConstructMustBe @PostConstructMustBe's} condition and evaluate it.
+ * <p>
+ * <b>Important:</b> The used predicate class must provide a default constructor! Hence not all of our provided {@link
+ * Conditions} will work. The following conditions can be used:
+ * <ul>
+ * <li>{@link Disabled}</li>
+ * <li>{@link Editable}</li>
+ * <li>{@link Enabled}</li>
+ * <li>{@link Interactable}</li>
+ * <li>{@link Invisible}</li>
+ * <li>{@link Present}</li>
+ * <li>{@link PresentAndVisible}</li>
+ * <li>{@link ReadOnly}</li>
+ * <li>{@link Selected}</li>
+ * <li>{@link Visible}</li>
+ * </ul>
+ * <p>
+ * <b>Example:</b>
+ * <pre>
+ * // this will throw an exception if the username is not visible when the page is initialized
+ * &#64;PostConstructMustBe(Visible.class)
+ * &#64;IdentifyUsing("#username")
+ * TextField username();
+ *
+ * // in cases where fragments are created using JavaScript an additional wait can be defined in the following way:
+ * &#64;PostConstructMustBe(Visible.class)
+ * &#64;WaitUntil(Present.class)
+ * &#64;IdentifyUsing("#username")
+ * TextField username();
+ * </pre>
+ *
+ * @see Predicate
+ * @see Conditions
+ * @since 2.0
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface PostConstructMustBe {
+
+    /**
+     * The {@link Predicate} predicate to use for the must check.
+     *
+     * @return the predicate to use
+     * @since 2.0
+     */
+    Class<? extends Predicate<PageFragment>> value();
+
+}