package cz.moneta.test.harness.support.web;

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

/**
 * WaitOrFailOnErrorElement annotation is used for waiting for #value element and fail of test if #valueToFail element is present <br>
 * Dynamic path functionality is supported for #value element. See {@link cz.moneta.test.harness.support.web.DynamicPathPart}
 * for use or open  @see <a href="https://confluence.moneta.cz/display/CONT/Dynamic+Elements">Confluence Best Practises page</a><br>
 * <u>WaitOrFailOnErrorElement for element example:</u>
 * <pre>
 *         {@literal @}@WaitOrFailOnErrorElement(SOME_VALUE_FOR_WAITING, SOME_VALUE_TO_FAIL, waitSecondsForElement = 80, by = Lookup.XPATH)
 *          SomePage waitForElement();
 *    </pre>
 * <p>
 * Params:<br>
 * {@link #value()} - Value for element identification..<br>
 * {@link #valueToFail()} - Value for identification of element to fail of test..<br>
 * {@link #waitSecondsForElement()} - Wait timeout. Default value is: 20<br>
 * {@link #by()} - could be used for other then default type of element search.<br>
 * {@link #isStringDynamicXpath()} - Use to set String from method in xpath. Boolean type. The default value is: false.<br>
 * <u>Example 3: </u>
 * <pre>
 *         {@literal @}WaitOrFailOnErrorElement (
 *                           value = SOME_CLASSNAME,
 *                           valueToFail = SOME_CLASSNAME,
 *                           waitSecondsForElement = 30,
 *                           by = Lookup.CLASSNAME,
 *          SomePage waitForElementGone();
 *    </pre>
 *
 * <br>
 * <br>
 * NOTE: In case you need for eg. both id and xpath, you need express id as xpath and use {@link Lookup}.XPATH<br>
 * <u>Example 4: </u>
 * <pre>
 *          String XPATH = "//div[@attr1='attribute']";
 *          String ID_AS_XPATH = "//div[@id='id']";
 *
 *         {@literal @}WaitOrFailOnErrorElement (
 *              value = {XPATH, ID_AS_XPATH},
 *              by = Lookup.XPATH
 *              )
 *          SomePage waitForElementGone();
 *    </pre>
 */
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface WaitOrFailOnErrorElement {
    /**
     * Value for identification of element for waiting.
     */
    String value();

    /**
     * Value for identification of element to fail of test.
     */
    String valueToFail();

    /**
     * Maximum waiting time (timeout) for element
     */
    int waitSecondsForElement() default 20;

    /**
     * Type of element identification which will be used for element search. XPATH, ID or DEFAULT can be used.
     *
     * @see Lookup
     */
    Lookup by() default Lookup.DEFAULT;

    /**
     * If set true will be used input String parameter of method to substitute %s in xpath.
     */
    boolean isStringDynamicXpath() default false;
}