001/**
002 * Powerunit - A JDK1.8 test framework
003 * Copyright (C) 2014 Mathieu Boretti.
004 *
005 * This file is part of Powerunit
006 *
007 * Powerunit is free software: you can redistribute it and/or modify
008 * it under the terms of the GNU General Public License as published by
009 * the Free Software Foundation, either version 3 of the License, or
010 * (at your option) any later version.
011 *
012 * Powerunit is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
015 * GNU General Public License for more details.
016 *
017 * You should have received a copy of the GNU General Public License
018 * along with Powerunit. If not, see <http://www.gnu.org/licenses/>.
019 */
020package ch.powerunit;
021
022import java.lang.annotation.Documented;
023import java.lang.annotation.ElementType;
024import java.lang.annotation.Retention;
025import java.lang.annotation.RetentionPolicy;
026import java.lang.annotation.Target;
027
028/**
029 * Used to mark a method (public static, returning Stream&lt;Object[]&gt;,
030 * 0-args) as method to provide test parameter.
031 * <p>
032 * This method will be run once only.
033 * <p>
034 * For instance, we may wrote this code
035 *
036 * <pre>
037 * import java.util.Arrays;
038 * import java.util.function.Function;
039 * import java.util.stream.Stream;
040 * 
041 * import ch.powerunit.Parameter;
042 * import ch.powerunit.Parameters;
043 * import ch.powerunit.Test;
044 * import ch.powerunit.TestSuite;
045 * 
046 * public class FunctionParameterTest&lt;T, R&gt; implements TestSuite {
047 * 
048 *     &#064;Parameters(&quot;{0} on {1} expecting {2}&quot;)
049 *     public static Stream&lt;Object[]&gt; getDatas() {
050 *         return Arrays.stream(new Object[][] { {
051 *                 (Function&lt;String, Integer&gt;) Integer::valueOf, &quot;1&quot;, 1 } });
052 *     }
053 * 
054 *     &#064;Parameter(0)
055 *     public Function&lt;T, R&gt; function;
056 * 
057 *     &#064;Parameter(1)
058 *     public T input;
059 * 
060 *     &#064;Parameter(2)
061 *     public R expected;
062 * 
063 *     &#064;Test
064 *     public void testAFunction() {
065 *         assertThatFunction(function, input).is(expected);
066 *     }
067 * }
068 *
069 * </pre>
070 * 
071 * It is also possible to indicate that each test parameter set is not
072 * applicable for each test method. This is done by using an additional, with
073 * the attribute <code>filter=true</code>. This field will be a BiFunction
074 * receiving the test method name and the parameters and returning a boolean. (
075 * <code>BiFunction&lt;String,Object[],Boolean&gt;</code>). This method will be
076 * used to check if the test method accept (or not) the parameter.
077 *
078 * @author borettim
079 * @see java.util.stream.Stream
080 * @see TestSuite#addFieldToEachEntry(Object) This is used on the stream to add
081 *      an object at the end of each entry (for instance the BiFunction).
082 */
083@Documented
084@Retention(RetentionPolicy.RUNTIME)
085@Target(ElementType.METHOD)
086public @interface Parameters {
087    /**
088     * Define an optional name of the test parameters. use {n} to refer to the
089     * parameter.
090     * 
091     * @return the name.
092     * @see java.text.MessageFormat#format(String, Object...) The formatter used
093     */
094    String value() default "";
095}