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<Object[]>, 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<T, R> implements TestSuite { 047 * 048 * @Parameters("%1$s on %2$s expecting %3$s") 049 * public static Stream<Object[]> getDatas() { 050 * return Arrays.stream(new Object[][] { { 051 * (Function<String, Integer>) Integer::valueOf, "1", 1 } }); 052 * } 053 * 054 * @Parameter(0) 055 * public Function<T, R> function; 056 * 057 * @Parameter(1) 058 * public T input; 059 * 060 * @Parameter(2) 061 * public R expected; 062 * 063 * @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<String,Object[],Boolean></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}