jaroslav@273: /**
jaroslav@273:  * Back 2 Browser Bytecode Translator
jaroslav@273:  * Copyright (C) 2012 Jaroslav Tulach <jaroslav.tulach@apidesign.org>
jaroslav@273:  *
jaroslav@273:  * This program is free software: you can redistribute it and/or modify
jaroslav@273:  * it under the terms of the GNU General Public License as published by
jaroslav@273:  * the Free Software Foundation, version 2 of the License.
jaroslav@273:  *
jaroslav@273:  * This program is distributed in the hope that it will be useful,
jaroslav@273:  * but WITHOUT ANY WARRANTY; without even the implied warranty of
jaroslav@273:  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
jaroslav@273:  * GNU General Public License for more details.
jaroslav@273:  *
jaroslav@273:  * You should have received a copy of the GNU General Public License
jaroslav@273:  * along with this program. Look for COPYING file in the top folder.
jaroslav@273:  * If not, see http://opensource.org/licenses/GPL-2.0.
jaroslav@273:  */
jaroslav@346: package org.apidesign.bck2brwsr.vmtest;
jaroslav@273: 
jaroslav@1185: import java.lang.annotation.Annotation;
jaroslav@1050: import java.util.ArrayList;
jaroslav@1050: import java.util.Arrays;
jaroslav@1050: import java.util.List;
jaroslav@797: import org.apidesign.bck2brwsr.launcher.Launcher;
jaroslav@372: import org.apidesign.bck2brwsr.vmtest.impl.CompareCase;
jaroslav@273: import org.testng.annotations.Factory;
jaroslav@273: 
jaroslav@797: /** A TestNG {@link Factory} that seeks for {@link Compare} and {@link BrwsrTest} annotations
jaroslav@797:  * in provided class and builds set of tests that verify the functionality of <b>Bck2Brwsr</b> 
jaroslav@797:  * based system. Use as:
jaroslav@797:  * <pre>
jaroslav@273:  * {@code @}{@link Factory} public static create() {
jaroslav@797:  *   return @{link VMTest}.{@link #create(java.lang.Class) create}(YourClass.class);
jaroslav@273:  * }</pre>
jaroslav@797:  * where <code>YourClass</code> contains methods annotated with
jaroslav@797:  * {@link Compare} and {@link BrwsrTest} annotations.
jaroslav@797:  * 
jaroslav@273:  * @author Jaroslav Tulach <jtulach@netbeans.org>
jaroslav@273:  */
jaroslav@372: public final class VMTest {
jaroslav@1050:     private final List<Class> classes = new ArrayList<>();
jaroslav@1050:     private final List<String> launcher = new ArrayList<>();
jaroslav@1185:     private Class<? extends Annotation> annotation = BrwsrTest.class;
jaroslav@1050:     
jaroslav@797:     private VMTest() {
jaroslav@797:     }
jaroslav@797:     
jaroslav@797:     /** Inspects <code>clazz</code> and for each method annotated by
jaroslav@797:      * {@link Compare} or {@link BrwsrTest} creates
jaroslav@797:      * instances of tests. 
jaroslav@797:      * <p>
jaroslav@797:      * Each {@link Compare} instance runs the test in different virtual
jaroslav@346:      * machine and at the end they compare the results.
jaroslav@797:      * <p>
jaroslav@797:      * Each {@link BrwsrTest} annotated method is executed once in {@link Launcher started
jaroslav@797:      * browser}.
jaroslav@346:      * 
jaroslav@1018:      * @param clazz the class (or classes) to inspect
jaroslav@346:      * @return the set of created tests
jaroslav@346:      */
jaroslav@1050:     public static Object[] create(Class clazz) {
jaroslav@1054:         return newTests().withClasses(clazz).build();
jaroslav@1050:     }
jaroslav@1050:     
jaroslav@1050:     /** Creates new builder for test execution. Continue with methods
jaroslav@1054:      * like {@link #withClasses(java.lang.Class[])} or {@link #withLaunchers(java.lang.String[])}.
jaroslav@1050:      * Finish the process by calling {@link #build()}.
jaroslav@1050:      * 
jaroslav@1050:      * @return new instance of a builder
jaroslav@1050:      * @since 0.7
jaroslav@1050:      */
jaroslav@1050:     public static VMTest newTests() {
jaroslav@1050:         return new VMTest();
jaroslav@1050:     }
jaroslav@1050:     
jaroslav@1050:     /** Adds class (or classes) to the test execution. The classes are inspected
jaroslav@1050:      * to contain methods annotated by
jaroslav@1050:      * {@link Compare} or {@link BrwsrTest}. Appropriate set of TestNG test
jaroslav@1050:      * cases is then created.
jaroslav@1050:      * <p>
jaroslav@1050:      * Each {@link Compare} instance runs the test in different virtual
jaroslav@1050:      * machine and at the end they compare the results.
jaroslav@1050:      * <p>
jaroslav@1050:      * Each {@link BrwsrTest} annotated method is executed once in {@link Launcher started
jaroslav@1050:      * browser}.
jaroslav@1050:      * 
jaroslav@1050:      * @param classes one or more classes to inspect
jaroslav@1050:      * @since 0.7
jaroslav@1050:      */
jaroslav@1054:     public final VMTest withClasses(Class... classes) {
jaroslav@1050:         this.classes.addAll(Arrays.asList(classes));
jaroslav@1050:         return this;
jaroslav@1050:     }
jaroslav@1050: 
jaroslav@1050:     /** Adds list of launchers that should be used to execute tests defined
jaroslav@1050:      * by {@link Compare} and {@link BrwsrTest} annotations. This value 
jaroslav@1050:      * can be overrided by using <code>vmtest.brwsrs</code> property.
jaroslav@1050:      * List of supported launchers is available in the documentation of
jaroslav@1050:      * {@link Launcher}.
jaroslav@1050:      * 
jaroslav@1050:      * @param launcher names of one or more launchers to use for the execution
jaroslav@1050:      *   of tests
jaroslav@1050:      * @since 0.7
jaroslav@1050:      */
jaroslav@1054:     public final VMTest withLaunchers(String... launcher) {
jaroslav@1050:         this.launcher.addAll(Arrays.asList(launcher));
jaroslav@1050:         return this;
jaroslav@1050:     }
jaroslav@1185: 
jaroslav@1185:     /** Specifies which annotation annotates the test methods
jaroslav@1185:      * to be executed. By 
jaroslav@1185:      * default it is the {@link BrwsrTest} annotation. Methods in
jaroslav@1185:      * {@link #withClasses(java.lang.Class[]) test classes} annotated by
jaroslav@1185:      * this annotation will be executed.
jaroslav@1185:      * 
jaroslav@1185:      * @param aClass an annotation class 
jaroslav@1185:      * @return this
jaroslav@1185:      * @since 0.8
jaroslav@1185:      */
jaroslav@1185:     public final VMTest withTestAnnotation(Class<? extends Annotation> aClass) {
jaroslav@1185:         if (!aClass.isAnnotation()) {
jaroslav@1185:             throw new IllegalStateException();
jaroslav@1185:         }
jaroslav@1185:         this.annotation = aClass;
jaroslav@1185:         return this;
jaroslav@1185:     }
jaroslav@1050:     
jaroslav@1050:     /** Assembles the provided information into the final array of tests.
jaroslav@1050:      * @return array of TestNG tests
jaroslav@1050:      * @since 0.7
jaroslav@1050:      */
jaroslav@1050:     public final Object[] build() {
jaroslav@1050:         return CompareCase.create(
jaroslav@1050:             launcher.toArray(new String[0]), 
jaroslav@1185:             classes.toArray(new Class[0]),
jaroslav@1185:             annotation
jaroslav@1050:         );
jaroslav@346:     }
jaroslav@273: }