org.fluentlenium.core.annotation.Label Maven / Gradle / Ivy

package org.fluentlenium.core.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Define a label on an injected {@link org.fluentlenium.core.domain.FluentWebElement} or
 * {@link org.fluentlenium.core.domain.FluentList}.
 * 
 * By default the injected element's original {@code toString()} value is returned but with
 * having the {@code @Label} annotation with different configurations that toString value can
 * be overridden. Using it can provide more meaningful error messages during test execution and debugging.
 * 

 * {@code FluentWebElement} Examples:
 * 
 * public class HomepageHeader {
 *
 *      @FindBy(css = "#header")
 *      private FluentWebElement header;
 *      //toString(): By.cssSelector: #header (first) (Lazy Element)
 *
 *      @FindBy(css = "#header")
 *      @Label
 *      private FluentWebElement headerDefaultLabel;
 *      //toString(): HomepageHeader.headerDefaultLabel (Lazy Element)
 *
 *      @FindBy(css = "#header")
 *      @Label("customLabel")
 *      private FluentWebElement headerCustomLabel;
 *      //toString(): customLabel (Lazy Element)
 * }
 * 
 * 
 * {@code FluentList} Examples:
 * 
 * public class HomepageHeader {
 *      @FindBy(css = ".footer-link")
 *      private FluentList<FluentWebElement footerLinks;
 *      //toString(): By.cssSelector: .footer-link (<toString() of the underlying list of FluentWebElements)
 *
 *      @FindBy(css = ".footer-link")
 *      @Label
 *      private FluentList<FluentWebElement footerLinksDefaultLabel;
 *      //toString(): HomepageHeader.footerLinksDefaultLabel (<toString() of the underlying list of FluentWebElements)
 *
 *      @FindBy(css = ".footer-link")
 *      @Label("customLabel")
 *      private FluentList<FluentWebElement footerLinksCustomLabel;
 *      //toString(): customLabel (<toString() of the underlying list of FluentWebElements)
 * }
 * 
 * 
 * This annotation is independent from the {@link LabelHint} annotation. Each one can be used without the other.
 * 

 * Defining a label can also be done inline on an a {@code FluentWebElement} or {@code FluentList}
 * by calling the {@code withLabel()} method on it.
 *
 * @see org.fluentlenium.core.inject.LabelAnnotations
 * @see org.fluentlenium.core.label.FluentLabelImpl
 * @see org.fluentlenium.core.label.FluentLabel#withLabel(String)
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface Label {
    /**
     * Label value.
     * 
     * If not defined, it will use the class name and field name as the label.
     *
     * @return label value
     */
    String value() default "";
}