1 /*
2  * Copyright (C) 2021 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package com.android.bedstead.harrier.annotations.meta;
18 
19 import com.android.bedstead.harrier.annotations.ParameterizedAnnotationScope;
20 
21 import java.lang.annotation.Annotation;
22 import java.lang.annotation.ElementType;
23 import java.lang.annotation.Retention;
24 import java.lang.annotation.RetentionPolicy;
25 import java.lang.annotation.Target;
26 
27 /**
28  * Mark a Harrier annotation as being Parameterized.
29  *
30  * <p>There will be a separate run generated for the annotated method for each
31  * {@link ParameterizedAnnotation} annotation. The test will be named methodName[paramName].
32  *
33  * <p>If any {@link ParameterizedAnnotation} annotations are applied to a test, then the basic
34  * un-parameterized test will not be run.
35  */
36 @Target(ElementType.ANNOTATION_TYPE)
37 @Retention(RetentionPolicy.RUNTIME)
38 @RequiresBedsteadJUnit4
39 public @interface ParameterizedAnnotation {
40 
41     /**
42      * Other parameterized annotations which are less powerful versions of this one.
43      *
44      * <p>For example, if this annotation represents a permission, and there is another annotation
45      * representing a permission which allows a subset of this one, then this annotation may shadow
46      * that one.
47      *
48      * <p>This will mean that these annotations will never be used together - one will be removed
49      * depending on whether the test requires the most powerful or least powerful state.
50      *
51      * <p>This should not be used if you want to explicitly test the state represented by each
52      * annotation.
53      */
shadows()54     Class<? extends Annotation>[] shadows() default {};
55 
56     /**
57      * Annotations of different scope is applied to the test method together. Whereas annotations of
58      * same scope will not be applied together to the same test method.
59      *
60      * <p>For example, if a test is annotated A1, A2, A3, A4 - and A1 and A2 are of scope S1, and A3
61      * and A4 are of scope S2 then it will result in the following tests: MyTest[A1][A3]
62      * MyTest[A1][A4] MyTest[A2][A3] MyTest[A2][A4].
63      */
scope()64     ParameterizedAnnotationScope scope();
65 }
66