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

package org.fluentlenium.core.annotation;

import java.lang.annotation.Retention;

import static java.lang.annotation.RetentionPolicy.RUNTIME;

/**
 * PageUrl is a class annotation used instead of getUrl method of {@link org.fluentlenium.core.FluentPage} object.
 * If PageUrl annotation is used the page class may not override the getUrl method.
 * 
 * It’s possible to define parameters using {@code {[?][/path/]parameter}} syntax.
 * If it starts with {@code ?}, it means that the parameter is optional.
 * Path can be included in the braces so it is removed when parameter value is not defined:
 * 
 * @PageUrl("/document/{document}{?/page/page}{?/format}")
 * public class DocumentPage extends FluentPage {
 *     public DocumentPage customPageMethod(){
 *             ...
 *             return this;
 *         }
 *         ...
 * }
 * 
 * Referencing local files in the test resources directory can be achieved by defining the file name of the resource in the
 * annotation's {@code file} attribute:
 *  * @PageUrl(file = "page2url.html", value = "?param1={param1}&param2={param2}")
 * class Page2DynamicP2P1 extends FluentPage {
 * }
 * 
 * In case you don't specify the {@code file} attribute but you override either {@link org.fluentlenium.core.FluentPage#getUrl()}
 * or {@link org.fluentlenium.core.FluentPage#getUrl(Object...)} in a way that it retrieves a local test resource you need to
 * also override {@link org.fluentlenium.core.FluentPage#isAtUsingUrl(String)} and leave its body empty to skip URL check
 * because PageUrl is not able to get local file path relatively.
 *  * @PageUrl(value = "?param1={param1}&param2={param2}")
 * class Page2DynamicP2P1 extends FluentPage {
 *     @Override
 *     protected String getUrl() {
 *          return someLocalResource;
 *     }
 *
 *     @Override
 *     public void isAtUsingUrl(String urlTemplate) {
 *     }
 * }
 * 
 * In case local files depending on the value of the {@code value} attribute you can use additional URL query parameters
 * attached to the path. If no query parameters are used the value attribute can be left empty.
 * 
 * You can find further examples at FluentLenium Key features.
 */
@Retention(RUNTIME)
public @interface PageUrl {
    /**
     * The page URL can be relative or absolute, if the URL is not recognized as absolute will be treated as relative.
     * 

     * For example:
     * 

     * @PageUrl("/")                  should redirect to the homepage of the website (baseUrl + "/")
     * @PageUrl("/index.html")        should redirect to baseUrl + "/index.html"
     * @PageUrl("http://example.com") should redirect to "http://example.com"
     * @PageUrl(file = "index.html" value="") should redirect to
     * * "file://{testResourcesDirectory}/index.html"
     * @PageUrl(file = "index.html" value="?param={param}") should
     * redirect to "file://{testResourcesDirectory}/index.html?param=<value of param>"
     * 
     *
     * @return page url
     */
    String value();

    /**
     * Defines the file name without a path located in the test resources directory on the local file system, e.g.
     * 
     * {@code @PageUrl(file = "index.html", value = "")}
     * 
     * Default value is empty.
     *
     * @return the file name
     */
    String file() default "";
}