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;%1$s on %2$s expecting %3$s&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 * <p>
079 * In case this annotation is used on a method from a test class annotated with
080 * <code>{@link TestDelegator}</code>, this method is used as a way to provide
081 * parameter to the test classes. In this case, this method must have exactly
082 * one parameter, which will be a class annotated with
083 * <code>{@link TestInterface}</code>.
084 *
085 * @author borettim
086 * @see java.util.stream.Stream
087 * @see TestSuite#addFieldToEachEntry(Object) This is used on the stream to add
088 *      an object at the end of each entry (for instance the BiFunction).
089 */
090@Documented
091@Retention(RetentionPolicy.RUNTIME)
092@Target(ElementType.METHOD)
093public @interface Parameters {
094        /**
095         * Define an optional name of the test parameters. use the syntax defined by
096         * {@link java.lang.String#format(String, Object...)} to refer to the
097         * parameter.
098         * <p>
099         * <b>The syntax for the formatted string has change since the version
100         * 0.4.0.</b>. At the moment, both syntax are supported, but the old one may
101         * be removed in a future release.
102         * <br>
103         * <h3>Normal syntax</h3>
104         * The syntax defined by {@link java.lang.String#format(String, Object...)}
105         * is used. Each parameter is available. It is here required to be careful
106         * with the numbering of the argument ; {@link Parameter} index are numbered
107         * starting from 0, but in the string format the numbering start from 1. In
108         * the easy form, the parameter can be passed with the syntax
109         * <code>%1$s</code> which for instance will use the first parameter (0
110         * parameter), as a String. 
111         * <br>
112         * <h3>Old syntax</h3>
113         * The old syntax is defined by
114         * {@link java.text.MessageFormat#format(String, Object...)} ; This syntax
115         * is enabled when the passed string format contains the regular expression
116         * <code>\{[0-9]+\}</code>.
117         * 
118         * @return the name.
119         * @see java.text.MessageFormat#format(String, Object...) The formatter used
120         *      for parameterized test. For version before 0.4.0.
121         * @see java.lang.String#format(String, Object...) The formatter used for
122         *      parameterized test, since version 0.4.0.
123         */
124        String value() default "";
125}