/
Tag.scala
158 lines (154 loc) · 6.87 KB
/
Tag.scala
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
/*
* Copyright 2001-2013 Artima, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.scalatest
/**
* Class whose subclasses can be used to tag tests in style traits in which tests are defined as functions.
*
* <p>
* ScalaTest has two ways to tag tests: annotations and instances of this <code>Tag</code> class.
* To tag a test method or an entire test class, you use a <em>tag annotation</em>, whereas to tag a test function,
* you use a <code>Tag</code> object. Though not required, it is usually a good idea to define both an annotation
* and a corresponding <code>Tag</code> object for each conceptual tag you want, so you can tag anything: test functions, test classes,
* and test methods. The name of the conceptual tag is the fully qualified name of the annotation interface, so you must
* pass this name to the <code>Tag</code> constructor.
* </p>
*
* <p>
* For example, imagine you want to tag integration tests that use the actual database, and are, therefore, generally slower. You could
* create a tag annotation and object called <code>DbTest</code>. To give them both the same simple name, you can declare them in different packages.
* The tag annotation must be written in Java, not Scala, because annotations written
* in Scala are not accessible at runtime. Here's an example:
* </p>
*
* <pre>
* package com.mycompany.myproject.testing.tags;
*
* import java.lang.annotation.*;
* import org.scalatest.TagAnnotation;
*
* @TagAnnotation
* @Retention(RetentionPolicy.RUNTIME)
* @Target({ElementType.METHOD, ElementType.TYPE})
* public @interface DbTest {}
* </pre>
*
* <p>
* Given this annotation's fully qualified name is <code>com.mycompany.myproject.testing.tags.DbTest</code> the corresponding <code>Tag</code>
* object decaration must have that name passed to its constructor, like this:
* </p>
*
* <pre class="stHighlighted">
* <span class="stReserved">package</span> com.mycompany.myproject.testing.tagobjects
* <br/><span class="stReserved">object</span> <span class="stType">DbTest</span> <span class="stReserved">extends</span> <span class="stType">Tag</span>(<span class="stQuotedString">"com.mycompany.myproject.testing.tags.DbTest"</span>)
* </pre>
*
* <p>
* Given these definitions, you could tag a test function as a <code>DbTest</code> in, for
* example, a <a href="FlatSpec.html"><code>FlatSpec</code></a> like this:
* </p>
*
* <pre class="stHighlighted">
* <span class="stReserved">import</span> org.scalatest.FlatSpec
* <span class="stReserved">import</span> com.mycompany.myproject.testing.tagobjects.DbTest
* <br/><span class="stReserved">class</span> <span class="stType">ExampleSpec</span> <span class="stReserved">extends</span> <span class="stType">FlatSpec</span> {
* <br/> <span class="stQuotedString">"Integration tests"</span> can <span class="stQuotedString">"sometimes be slow"</span> taggedAs(<span class="stType">DbTest</span>) in {
* Thread.sleep(<span class="stLiteral">1000</span>)
* }
* }
* </pre>
*
* <p>
* You could tag a test method as a <code>DbTest</code> in, for
* example, a <a href="Suite.html"><code>Suite</code></a> like this:
* </p>
*
* <pre class="stHighlighted">
* <span class="stReserved">import</span> org.scalatest.Suite
* <span class="stReserved">import</span> com.mycompany.myproject.testing.tags.DbTest
* <br/><span class="stReserved">class</span> <span class="stType">ExampleSuite</span> <span class="stReserved">extends</span> <span class="stType">Suite</span> {
* <br/> @<span class="stType">DbTest</span>
* <span class="stReserved">def</span> <span class="literalIdentifier">`integration tests can sometimes be slow`</span> {
* Thread.sleep(<span class="stLiteral">1000</span>)
* }
* }
* </pre>
*
* <p>
* And you could tag all the tests in an entire test class by annotating the class, like this:
* </p>
*
* <pre class="stHighlighted">
* <span class="stReserved">import</span> org.scalatest.FlatSpec
* <span class="stReserved">import</span> com.mycompany.myproject.testing.tags.DbTest
* <br/>@<span class="stType">DBTest</span>
* <span class="stReserved">class</span> <span class="stType">ExampleSpec</span> <span class="stReserved">extends</span> <span class="stType">FlatSpec</span> {
* <br/> <span class="stQuotedString">"Integration tests"</span> can <span class="stQuotedString">"sometimes be slow"</span> in {
* Thread.sleep(<span class="stLiteral">1000</span>)
* }
* <br/> they should <span class="stQuotedString">"likely sometimes be excluded "</span> in {
* Thread.sleep(<span class="stLiteral">1000</span>)
* }
* }
* </pre>
*
* <p>
* In the previous example, both tests will be tagged as <code>DBTest</code>s even though the
* tests are not tagged as such individually.
* </p>
*
* <p>
* When you run ScalaTest and want to either include or exclude <code>DbTest</code>s, you'd give the fully qualified
* name of the tag annotation (which is also the name passed to the corresponding <code>Tag</code> constructor) to <a href="tools/Runner$.html"><code>Runner</code></a>. For
* example, here's how you'd exclude <code>DbTest</code>s on the <code>Runner</code> command line:
* </p>
*
* <pre>
* -l com.mycompany.myproject.testing.tags.DbTest
* </pre>
*
* <p>
* For examples of tagging in other style traits, see the "Tagging tests" section in the documentation for the trait:
* </p>
*
* <ul>
* <li><a href="FeatureSpec.html#taggingTests">Tagging <code>FeatureSpec</code> tests</a></li>
* <li><a href="FlatSpec.html#taggingTests">Tagging <code>FlatSpec</code> tests</a></li>
* <li><a href="FreeSpec.html#taggingTests">Tagging <code>FreeSpec</code> tests</a></li>
* <li><a href="FunSpec.html#taggingTests">Tagging <code>FunSpec</code> tests</a></li>
* <li><a href="FunSuite.html#taggingTests">Tagging <code>FunSuite</code> tests</a></li>
* <li><a href="PropSpec.html#taggingTests">Tagging <code>PropSpec</code> tests</a></li>
* <li><a href="Spec.html#taggingTests">Tagging <code>Spec</code> tests</a></li>
* <li><a href="WordSpec.html#taggingTests">Tagging <code>WordSpec</code> tests</a></li>
* </ul>
*
* @author Bill Venners
* @author George Berger
*/
class Tag(val name: String)
/**
* Companion object for <code>Tag</code>, which offers a factory method.
*
* @author George Berger
* @author Bill Venners
*/
object Tag {
/**
* Factory method for creating new <code>Tag</code> objects.
*/
def apply(name: String): Tag = {
new Tag(name)
}
}