org.jboss.arquillian.graphene.javascript.JavaScript Maven / Gradle / Ivy

Go to download
/**
 * JBoss, Home of Professional Open Source
 * Copyright 2013, Red Hat, Inc. and individual contributors
 * by the @authors tag. See the copyright.txt in the distribution for a
 * full listing of individual contributors.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package org.jboss.arquillian.graphene.javascript;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import org.jboss.arquillian.graphene.spi.ImplementedBy;
import org.openqa.selenium.JavascriptExecutor;

/**
 * 
 * Interfaces or abstract classes annotated with this interface invokes a script on a page under test.
 * 
 *
 * 
 * This annotation is used for both, annotating the type and marking the injection point as demonstrated in following example.
 * 
 *
 * 
 * The interface can also automatically retrieve JavaScript file dependencies, using {@link Dependency} annotation.
 * 
 *
 * 
 * Default implementation of {@link ExecutionResolver} which invokes the script on the page automatically converts all types
 * defined by {@link JavascriptExecutor#executeScript(String, Object...)} and additionally it converts enumerations to their
 * string representation.
 * 
 *
 * 
 * Default implementation also automatically resolves the getters and setters name as accessors to the object. Java method
 * called setName can either call setName method on target JavaScript object or it can set a value of
 * name property of that object. Similarly getName can either call a getName method or return
 * name property.
 * 
 *
 * 
 * The name of a method is automatically diverged from name of a Java interface method, however it can be re-defined using
 * {@link MethodName} annotation.
 *
 * 
Example
 *
 * helloworld.js
 *
 *  * window.helloworld = {
 *   hello: function() {
 *     return "Hello World!";
 *   }
 * }
 * 
 *
 * HelloWorld.java
 *
 *  * @JavaScript("helloworld")
 * @Dependency(sources = "helloworld.js")
 * public interface HelloWorld {
 *
 *     String hello();
 *
 * }
 * 
 *
 * TestCase.java
 *
 *  * public static class TestCase {
 *
 *     @JavaScript
 *     private HelloWorld helloWorld;
 *
 *     @Test
 *     public void testHelloWorld() {
 *         assertEquals("Hello World!", helloWorld.hello());
 *     }
 * }
 * 
 *
 * @author Lukas Fryc
 */
@Target({ TYPE, FIELD })
@Retention(RUNTIME)
@Documented
public @interface JavaScript {

    /**
     * 
     * The name of JavaScript interface - Graphene will look up the global object of that name on a page.
     * 
     *
     * 
     * Defaults to window.<type> where type is name of the interface annotated with this annotation.
     * 
     *
     * @return name of the interface
     */
    String value() default "";

    /**
     * Indicates that this interface is just an interface and its implementation (another JavaScript interface) is specified in
     * linked implementation class.
     *
     * @return the class of implementation
     */
    String implementation() default "";

    /**
     * Returns {@link ExecutionResolver} which will execute the JavaScript interface.
     *
     * @return the class of a {@link ExecutionResolver} which will invokes this interface
     */
    Class executionResolver() default DefaultExecutionResolver.class;

    @ImplementedBy(className = "org.jboss.arquillian.graphene.javascript.DefaultExecutionResolver")
    interface DefaultExecutionResolver extends ExecutionResolver {
    }
}