001 /*
002 * $Id: Broken.java,v 1.14 2011/03/18 06:43:32 oboehm Exp $
003 *
004 * Copyright (c) 2009 by Oliver Boehm
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express orimplied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 *
018 * (c)reated 23.11.2009 by oliver (ob@oasd.de)
019 */
020
021 package patterntesting.runtime.annotation;
022
023 import static patterntesting.runtime.NullConstants.*;
024
025 import java.lang.annotation.*;
026
027 /**
028 * If you want to mark JUnit tests which does not work for the moment as
029 * "broken" you can use this annotation. The tests will be skipped if you
030 * run JUnit. You can also add a date till when you want to fix this "broken"
031 * test. If the date is reached then the test will fail if it is not fixed
032 * (and the @Broken removed).
033 * <br/>
034 * Before 1.0.0 this annotation was handled by BrokenAspect. But since 1.0.0
035 * it is handled now by the {@link patterntesting.runtime.junit.SmokeRunner} class.
036 * You should use this annotation together with {@code @RunWith(SmokeRunner.class)},
037 * also for JUnit 3 tests.
038 * <br/>
039 * You can also use this annotation to mark a method or constructor as
040 * "broken". If assertions are enabled an AssertionError will be thrown if
041 * you call such a broken method. If not only a error message will be logged.
042 * <br/>
043 * What is the difference to <code>@SkipTestOn</code>?
044 * "Broken" means, the test does not work for the moment and should be
045 * (temporarily) skipped. "SkipTestOn" means, this test is not constructed
046 * for that platform and should be therefore skipped on it.
047 *
048 * @see SkipTestOn
049 * @author oliver
050 * @since 23.11.2009
051 */
052 @Documented
053 @Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.TYPE})
054 @Retention(RetentionPolicy.RUNTIME)
055 public @interface Broken {
056
057 /**
058 * You can change the default string to give a reason why the test is
059 * marked as "broken".
060 * You can use 'value=...' or 'wyh=...' to change it.
061 */
062 String value() default "marked as @Broken";
063
064 /**
065 * You can change the default string to give a reason why the test is
066 * marked as "broken".
067 * You can use 'value=...' or 'why=...' to change it.
068 */
069 String why() default NULL_STRING;
070
071 /**
072 * Use this attribute to mark the begin of the broken area, when it
073 * was detected that your JUnit test or method does not work as expected.
074 * <br/>
075 * The format of the date is "dd-MMM-yyyy".
076 */
077 String since() default NULL_STRING;
078
079 /**
080 * Use this attribute till you want the broken JUnit test to be fixed.
081 * <br/>
082 * The format of the date is "dd-MMM-yyyy" or "dd-MMM-yyyy H:mm".
083 */
084 String till() default NULL_STRING;
085
086 /**
087 * Is a test only broken on a single platform e.g. on Linux?
088 * Use os="Linux" to mark it as broken only for the Linux platform.
089 * Instead of "Linux" you can use any other operation system. The
090 * format must be the same as returned by the system property "os.name".
091 * Valid values are:
092 * <ul>
093 * <li>"Linux"</li>
094 * <li>"Mac OS X" (for Mac),</li>
095 * <li>"Windows XP"</li>
096 * <li>and others
097 * (see {@link "http://lopica.sourceforge.net/os.html"}).
098 * </li>
099 * </ul>
100 * Multiple values like <code>{ "Linux", "Mac OS X" }</code> are allowed.
101 *
102 * @deprecated use osName()
103 */
104 String[] os() default NULL_STRING;
105
106 /**
107 * Does the test break only for user "Bob" and you can't fix it for him at
108 * the moment? Use <code>user="bob"</code> to mark it as broken for user
109 * account "bob".
110 * <br/>
111 * Damn, the new member of the team, Bill, has the same problem and nobody
112 * is able to fix it. Ok, use <code>user={"bob", "bill"}</code> to mark the
113 * code as broken for both user.
114 *
115 * @since 1.0
116 */
117 String[] user() default NULL_STRING;
118
119 /**
120 * Should a test be skipped on a single platform e.g. for Linux?
121 * Use "Linux" to mark it as broken only for the Linux platform.
122 * Instead of "Linux" you can use any other operation system. The
123 * format must be the same as returned by the system property "os.name".
124 * Valid values are:
125 * <ul>
126 * <li>"Linux"</li>
127 * <li>"Mac OS X" (for Mac),</li>
128 * <li>"Windows XP"</li>
129 * <li>and others
130 * (see {@link "http://lopica.sourceforge.net/os.html"}).
131 * </li>
132 * </ul>
133 * Multiple values like <code>{ "Linux", "Mac OS X" }</code> are allowed.
134 * If no operation system is given you will get an IllegalArgumentException.
135 * <br/>
136 * The format of this attribute must be the same as returned by system
137 * property "os.name".
138 *
139 * @since 1.1
140 */
141 String[] osName() default NULL_STRING;
142
143 /**
144 * The test is broken only for the Intel architecture?
145 * Then you can use this attribute to limit it on this platform.
146 * You can define a single platform like <code>"x86_64"</code> for an
147 * Intel-Mac with 64 bit or multiple platform like
148 * <code>{ "x86_32", "x86_64" }</code> for Intel Mac with 42 or 64 bit.
149 * <br/>
150 * The format of this attribute must be the same as returned by the system
151 * property "os.arch".
152 *
153 * @since 1.1
154 */
155 String[] osArch() default NULL_STRING;
156
157 /**
158 * The test breaks only on a special version of the
159 * operating system? Use this attribute to limit it.
160 * In contradiction to the other attributes the real version must start
161 * with the given version. I.e. if you define "10.6" as version this would
162 * match only real version "10.6.1" or "10.6.2".
163 * <br/>
164 * You can't define a range of skipped versions. But several versions are
165 * allowed. So if you want to skip the tests in version 10.6.1 till 10.6.3
166 * define { "10.6.1", "10.6.2", "10.6.3" } as values.
167 * The format of this attribute must be the same as returned by the system
168 * property "osVersion".
169 *
170 * @since 1.1
171 */
172 String[] osVersion() default NULL_STRING;
173
174 /**
175 * With this attribute you can express that the test is broken for
176 * the given host(s). Perhaps these hosts have not enough memory.
177 * You can define the host by its name or by its IP address.
178 *
179 * @since 1.1
180 */
181 String[] host() default NULL_STRING;
182
183 /**
184 * You want to mark the test as broken on a special version of the VM, e.g. on
185 * version "1.6.0_17" because you know that on this version there is a bug
186 * that caused your test not to work? Then use this attribute.
187 * <br/>
188 * You can't define a range of skipped versions. But you regex (regular
189 * expressions) are allowed. And you can define more than one version
190 * (or regex).
191 * <br/>
192 * The format of this attribute must be the same as returned by the
193 * system property "java.version".
194 *
195 * @since 1.1
196 */
197 String[] javaVersion() default NULL_STRING;
198
199 /**
200 * The test is broken for a special vendor VM? Use this attribute
201 * here. The format of this attribute must be the same as returned by the
202 * system property "java.vendor".
203 * Valid values are:
204 * <ul>
205 * <li>"Apple Inc."</li>
206 * <li>and others</li>
207 * </ul>
208 *
209 * @since 1.1
210 */
211 String[] javaVendor() default NULL_STRING;
212
213 /**
214 * You have some tests that are broken if some proxy properties are set?
215 * Define the property here (e.g. <code>property="proxy.host"</code>).
216 * If this property is set (and its value is
217 * not "false") the test will be skipped if this property is set as
218 * system property.
219 * <br/>
220 * You can control more than property with this attribute. Then all
221 * properties must be "true" to skip the test.
222 *
223 * @since 1.1
224 */
225 String[] property() default NULL_STRING;
226
227 }