org.scalatest.WrapWith Maven / Gradle / Ivy

/*
 * 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;

import java.lang.annotation.*; 

/**
 * Annotation to associate a wrapper suite with a non-Suite class, so it can be run via ScalaTest.
 *
 * 
 * Note: This is actually an annotation defined in Java, not a Scala trait. It must be defined in Java instead of Scala so it will be accessible
 * at runtime. It has been inserted into Scaladoc by pretending it is a trait.
 * 
 *
 * 
 * A class will be considered annotated with WrapWith if it is annotated directly or one of its superclasses (but
 * not supertraits) are annotated with WrapWith.
 * The wrapper suite must have a public, one-arg constructor that takes a Class instance whose type parameter
 * is compatible with the class to wrap: i.e., the class being annotated with WrapWith.
 * ScalaTest will load the class to wrap and construct a new instance of the wrapper suite, passing in the Class
 * instance for the class to wrap.
 * Here's an example:
 * 
 *
 *  * import org.scalacheck.Properties
 *
 * @WrapWith(classOf[ScalaCheckPropertiesSpec])
 * class StringSpecification extends Properties("String") {
 *   // ...
 * }
 * 
 *
 * 
 * The ScalaCheckPropertiesSpec would need to have a public, no-arg constructor that accepts subclasses of org.scalacheck.Properties:
 * 
 *
 *  * import org.scalacheck.Properties
 * import org.scalatest.Suite
 *
 * class ScalaCheckPropertiesSpec(clazz: Class[_ <: Properties]) extends Suite {
 *   // ...
 * }
 * 
 *
 * @author Bill Venners
 * @author Chua Chee Seng
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited
public @interface WrapWith {

    /**
     * The wrapper suite.
     *
     * @return a wrapper suite class, which must have a constructor that takes a single Class to run
     */
    Class value();
}