Added missing Hamcrest matcher documentation

Author: slu-it

webtester-support-hamcrest/src/main/java/info/novatec/testit/webtester/support/hamcrest/WebTesterMatchers.java

@@ -4,11 +4,33 @@
 import org.hamcrest.Description;
 import org.hamcrest.Matcher;
 
-
+import info.novatec.testit.webtester.support.hamcrest.WebTesterMatchers;
+
+
+/**
+ * This {@link BaseMatcher} has only syntactical value. Like the {@link org.hamcrest.core.Is} matcher it delegates it's
+ * evaluation to another matcher. Instances of this matcher should be initialized using the {@link WebTesterMatchers}
+ * factory class.
+ * <p>
+ * <b>Example:</b> assertThat(textField, has(text("foo")));
+ * <p>
+ *
+ * @param <T> the type of the wrapped matcher
+ * @see WebTesterMatchers
+ * @since 2.0
+ */
 public class HasMatcher<T> extends BaseMatcher<T> {
 
+    /** The wrapped matcher instance. */
     private final Matcher<T> matcher;
 
+    /**
+     * Creates a new instance with wrapping the given matcher.
+     *
+     * @param matcher the matcher to wrap
+     * @see HasMatcher
+     * @since 2.0
+     */
     public HasMatcher(Matcher<T> matcher) {
         this.matcher = matcher;
     }

webtester-support-hamcrest/src/main/java/info/novatec/testit/webtester/support/hamcrest/matchers/HasMatcher.java

@@ -5,26 +5,43 @@
 
 import info.novatec.testit.webtester.conditions.Conditions;
 import info.novatec.testit.webtester.pagefragments.PageFragment;
-
-
+import info.novatec.testit.webtester.support.hamcrest.WebTesterMatchers;
+
+
+/**
+ * This {@link TypeSafeMatcher} checks whether or not a specific attribute is present on a {@link PageFragment}.
+ * Instances of this matcher should be initialized using the {@link WebTesterMatchers} factory class.
+ * <p>
+ * <b>Example:</b> assertThat(fragment, has(attribute("type")));
+ * <p>
+ *
+ * @param <T> the type of the checked page fragment
+ * @see WebTesterMatchers
+ * @since 2.0
+ */
 public class AttributeMatcher<T extends PageFragment> extends TypeSafeMatcher<T> {
 
-    // TODO: Document
-
-    private final String attributeName;
-
-    public AttributeMatcher(String attributeName) {
-        this.attributeName = attributeName;
+    private final String expected;
+
+    /**
+     * Creates a new instance for the given attribute name.
+     *
+     * @param expected the name of the attribute to check
+     * @see AttributeMatcher
+     * @since 2.0
+     */
+    public AttributeMatcher(String expected) {
+        this.expected = expected;
     }
 
     @Override
     public void describeTo(Description description) {
-        description.appendText("attribute <" + attributeName + ">");
+        description.appendText("attribute <" + expected + ">");
     }
 
     @Override
     protected boolean matchesSafely(T item) {
-        return Conditions.attribute(attributeName).test(item);
+        return Conditions.attribute(expected).test(item);
     }
 
     @Override

webtester-support-hamcrest/src/main/java/info/novatec/testit/webtester/support/hamcrest/matchers/pagefragments/AttributeMatcher.java

@@ -4,39 +4,65 @@
 import org.hamcrest.TypeSafeMatcher;
 
 import info.novatec.testit.webtester.pagefragments.PageFragment;
+import info.novatec.testit.webtester.support.hamcrest.WebTesterMatchers;
 
 
+/**
+ * This {@link TypeSafeMatcher} checks whether or not a specific attribute has a given value on a {@link PageFragment}.
+ * Instances of this matcher should be initialized using the {@link WebTesterMatchers} factory class.
+ * <p>
+ * <b>Example:</b> assertThat(fragment, has(attributeValue("type", "radio")));
+ * <p>
+ * <b>Note:</b> This matcher has two possible failure scenarios:
+ * <ol>
+ * <li>The attribute does not exist.</li>
+ * <li>The attribute has a different value.</li>
+ * </ol>
+ *
+ * @param <T> the type of the checked page fragment
+ * @see WebTesterMatchers
+ * @since 2.0
+ */
 public class AttributeValueMatcher<T extends PageFragment> extends TypeSafeMatcher<T> {
 
-    // TODO: Document
+    private final String expectedAttributeName;
+    private final String expectedValue;
 
-    private final String attributeName;
-    private final String value;
+    /** Boolean to remember if the attribute was present for a possible mismatch description. */
     private boolean attributePresent;
+    /** The actual value for a possible mismatch description. */
     private String actualValue;
 
-    public AttributeValueMatcher(String attributeName, String value) {
-        this.attributeName = attributeName;
-        this.value = value;
+    /**
+     * Creates a new instance for the given attribute name and value.
+     *
+     * @param expectedAttributeName the name of the attribute to check
+     * @param expectedValue the expected value of the attribute
+     * @see AttributeValueMatcher
+     * @since 2.0
+     */
+    public AttributeValueMatcher(String expectedAttributeName, String expectedValue) {
+        this.expectedAttributeName = expectedAttributeName;
+        this.expectedValue = expectedValue;
     }
 
     @Override
     public void describeTo(Description description) {
-        description.appendText("attribute <" + attributeName + "> with value <" + value + ">");
+        description.appendText("attribute <" + expectedAttributeName + "> with value <" + expectedValue + ">");
     }
 
     @Override
     protected boolean matchesSafely(T item) {
-        item.getAttribute(attributeName).ifPresent(value -> {
+        item.getAttribute(expectedAttributeName).ifPresent(value -> {
             attributePresent = true;
             actualValue = value;
         });
-        return attributePresent && value.equals(actualValue);
+        return attributePresent && expectedValue.equals(actualValue);
     }
 
     @Override
     protected void describeMismatchSafely(T item, Description mismatchDescription) {
-        if(!attributePresent) {
+        if (!attributePresent) {
             mismatchDescription.appendText("attribute was not present");
         } else {
             mismatchDescription.appendText("value was <" + actualValue + ">");

webtester-support-hamcrest/src/main/java/info/novatec/testit/webtester/support/hamcrest/matchers/pagefragments/AttributeValueMatcher.java

@@ -4,33 +4,52 @@
 import org.hamcrest.TypeSafeMatcher;
 
 import info.novatec.testit.webtester.pagefragments.Button;
-
-
+import info.novatec.testit.webtester.support.hamcrest.WebTesterMatchers;
+
+
+/**
+ * This {@link TypeSafeMatcher} checks whether or not a {@link Button} has a certain label.
+ * Instances of this matcher should be initialized using the {@link WebTesterMatchers} factory class.
+ * <p>
+ * <b>Example:</b> assertThat(button, has(label("type")));
+ * <p>
+ *
+ * @param <T> the type of the checked button
+ * @see WebTesterMatchers
+ * @since 2.0
+ */
 public class ButtonLabelMatcher<T extends Button> extends TypeSafeMatcher<T> {
 
-    // TODO: Document
+    private final String expected;
 
-    private final String label;
-    private String actualLabel;
+    /** The actual label for a possible mismatch description. */
+    private String actual;
 
-    public ButtonLabelMatcher(String label) {
-        this.label = label;
+    /**
+     * Creates a new instance for the given label.
+     *
+     * @param expected the label to check
+     * @see ButtonLabelMatcher
+     * @since 2.0
+     */
+    public ButtonLabelMatcher(String expected) {
+        this.expected = expected;
     }
 
     @Override
     public void describeTo(Description description) {
-        description.appendText("label <" + label + ">");
+        description.appendText("label <" + expected + ">");
     }
 
     @Override
     protected boolean matchesSafely(T item) {
-        actualLabel = item.getLabel();
-        return label.equals(actualLabel);
+        actual = item.getLabel();
+        return expected.equals(actual);
     }
 
     @Override
     protected void describeMismatchSafely(T item, Description mismatchDescription) {
-        mismatchDescription.appendText("was <" + actualLabel + ">");
+        mismatchDescription.appendText("was <" + actual + ">");
     }
 
 }

webtester-support-hamcrest/src/main/java/info/novatec/testit/webtester/support/hamcrest/matchers/pagefragments/ButtonLabelMatcher.java

@@ -5,12 +5,22 @@
 
 import info.novatec.testit.webtester.conditions.Conditions;
 import info.novatec.testit.webtester.pagefragments.PageFragment;
-
-
+import info.novatec.testit.webtester.support.hamcrest.WebTesterMatchers;
+
+
+/**
+ * This {@link TypeSafeMatcher} checks whether or not a {@link PageFragment} is disabled.
+ * Instances of this matcher should be initialized using the {@link WebTesterMatchers} factory class.
+ * <p>
+ * <b>Example:</b> assertThat(fragment, is(disabled()));
+ * <p>
+ *
+ * @param <T> the type of the checked page fragment
+ * @see WebTesterMatchers
+ * @since 2.0
+ */
 public class DisabledMatcher<T extends PageFragment> extends TypeSafeMatcher<T> {
 
-    // TODO: Document
-
     @Override
     public void describeTo(Description description) {
         description.appendText("disabled");

webtester-support-hamcrest/src/main/java/info/novatec/testit/webtester/support/hamcrest/matchers/pagefragments/DisabledMatcher.java

@@ -5,12 +5,22 @@
 
 import info.novatec.testit.webtester.conditions.Conditions;
 import info.novatec.testit.webtester.pagefragments.PageFragment;
-
-
+import info.novatec.testit.webtester.support.hamcrest.WebTesterMatchers;
+
+
+/**
+ * This {@link TypeSafeMatcher} checks whether or not a {@link PageFragment} is enabled.
+ * Instances of this matcher should be initialized using the {@link WebTesterMatchers} factory class.
+ * <p>
+ * <b>Example:</b> assertThat(fragment, is(enabled()));
+ * <p>
+ *
+ * @param <T> the type of the checked page fragment
+ * @see WebTesterMatchers
+ * @since 2.0
+ */
 public class EnabledMatcher<T extends PageFragment> extends TypeSafeMatcher<T> {
 
-    // TODO: Document
-
     @Override
     public void describeTo(Description description) {
         description.appendText("enabled");

webtester-support-hamcrest/src/main/java/info/novatec/testit/webtester/support/hamcrest/matchers/pagefragments/EnabledMatcher.java

@@ -5,12 +5,22 @@
 
 import info.novatec.testit.webtester.conditions.Conditions;
 import info.novatec.testit.webtester.pagefragments.PageFragment;
-
-
+import info.novatec.testit.webtester.support.hamcrest.WebTesterMatchers;
+
+
+/**
+ * This {@link TypeSafeMatcher} checks whether or not a {@link PageFragment} is invisible.
+ * Instances of this matcher should be initialized using the {@link WebTesterMatchers} factory class.
+ * <p>
+ * <b>Example:</b> assertThat(fragment, is(invisible()));
+ * <p>
+ *
+ * @param <T> the type of the checked page fragment
+ * @see WebTesterMatchers
+ * @since 2.0
+ */
 public class InvisibleMatcher<T extends PageFragment> extends TypeSafeMatcher<T> {
 
-    // TODO: Document
-
     @Override
     public void describeTo(Description description) {
         description.appendText("invisible");

webtester-support-hamcrest/src/main/java/info/novatec/testit/webtester/support/hamcrest/matchers/pagefragments/InvisibleMatcher.java

@@ -4,13 +4,24 @@
 import org.hamcrest.TypeSafeMatcher;
 
 import info.novatec.testit.webtester.pagefragments.GenericSelect;
-
-
+import info.novatec.testit.webtester.support.hamcrest.WebTesterMatchers;
+
+
+/**
+ * This {@link TypeSafeMatcher} checks whether or not a {@link GenericSelect} has no options.
+ * Instances of this matcher should be initialized using the {@link WebTesterMatchers} factory class.
+ * <p>
+ * <b>Example:</b> assertThat(select, has(noOptions()));
+ * <p>
+ *
+ * @param <T> the type of the checked select
+ * @see WebTesterMatchers
+ * @since 2.0
+ */
 public class NoOptionsMatcher<T extends GenericSelect<T>> extends TypeSafeMatcher<T> {
 
-    // TODO: Document
-
-    private int options;
+    /** The actual number of options for a possible mismatch description. */
+    private int actual;
 
     @Override
     public void describeTo(Description description) {
@@ -19,13 +30,13 @@ public void describeTo(Description description) {
 
     @Override
     protected boolean matchesSafely(T item) {
-        options = item.getOptionCount();
-        return options == 0;
+        actual = item.getOptionCount();
+        return actual == 0;
     }
 
     @Override
     protected void describeMismatchSafely(T item, Description mismatchDescription) {
-        mismatchDescription.appendText("has <" + options + "> options");
+        mismatchDescription.appendText("has <" + actual + "> options");
     }
 
 }