package cz.moneta.test.harness.support.mobile.android;

import cz.moneta.test.harness.support.mobile.MobileLookup;
import cz.moneta.test.harness.support.web.Until;

import java.lang.annotation.*;

/**
 * Wait annotation is used for wait for some element or explicit wait.<br>
 * Dynamic path functionality is supported. 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>Wait for element example:</u>
 *    <pre>
 *         {@literal @}AndroidWait (SOME_VALUE)
 *          SomePage waitForElement();
 *    </pre>
 * <u>Explicit wait example:</u>
 *    <pre>
 *         {@literal @}AndroidWait (explicitWaitSeconds = 10)
 *          SomePage waitTenSeconds();
 *    </pre>
 * Params:<br>
 * {@link #value()} - Value for element identification. More values can be used.<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 #until()} - wait type. Default value is: {@link Until}.PRESENT_IN_DOM.<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 @}AndroidWait (
 *                           value = SOME_CLASSNAME,
 *                           waitSecondsForElement = 30,
 *                           by = MobileLookup.CLASSNAME,
 *                           until = Until.GONE)
 *          SomePage waitForElementGone();
 *    </pre>
 *
 * <u>IMPORTANT:</u> For @AndroidWait until GONE used in flows (WebFlow) is necessary to have another @AndroidWait for element to identify
 * displayed page - if wrong page still loaded, @AndroidWait until GONE is validate to this page not the expected one. In case this rule
 * is not followed, test execution throws HarnessException.
 * <br>
 * <br>
 * NOTE: In case you need for eg. both id and xpath, you need express id as xpath and use {@link MobileLookup}.XPATH<br>
 * <u>Example 4: </u>
 *    <pre>
 *          String XPATH = "//div[@attr1='attribute']";
 *          String ID_AS_XPATH = "//div[@id='id']";
 *
 *         {@literal @}AndroidWait (
 *              value = {XPATH, ID_AS_XPATH},
 *              by = MobileLookup.XPATH
 *              )
 *          SomePage waitForElementGone();
 *    </pre>
 */
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface AndroidWait{

    /**
     * Value for identification of element.
     */
    String[] value() default {};

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

    /**
     * Tool will wait for defined seconds.
     */
    int explicitWaitSeconds() default 0;

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

    /**
     * Defines what type of wait condition will be used.
     * @see Until
     */
    Until until() default Until.PRESENT_IN_DOM;

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