org.lockss.util.test.VariantTest Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of lockss-util Show documentation
Development and testing utilities common to most LOCKSS projects
The newest version!
/*
 * Copyright 2015-2018 the original author or authors.
 *
 * All rights reserved. This program and the accompanying materials are
 * made available under the terms of the Eclipse Public License v2.0 which
 * accompanies this distribution and is available at
 *
 * http://www.eclipse.org/legal/epl-v20.html
 */

package org.lockss.util.test;
import org.junit.jupiter.params.*;

import static org.apiguardian.api.API.Status.EXPERIMENTAL;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import org.apiguardian.api.API;
import org.junit.jupiter.api.TestTemplate;
import org.junit.jupiter.api.extension.ExtendWith;

/**
 * {@code @VariantTest} is used to signal that the annotated method is a
 * parameterized test method.
 *
 * Such methods must not be {@code private} or {@code static}.
 *
 * 
Argument Providers and Sources
 *
 * {@code @VariantTest} methods must specify at least one
 * {@link org.junit.jupiter.params.provider.ArgumentsProvider ArgumentsProvider}
 * via {@link org.junit.jupiter.params.provider.ArgumentsSource @ArgumentsSource}
 * or a corresponding composed annotation (e.g., {@code @ValueSource},
 * {@code @CsvSource}, etc.). The provider is responsible for providing a
 * {@link java.util.stream.Stream Stream} of
 * {@link org.junit.jupiter.params.provider.Arguments Arguments} that will be
 * used to invoke the variant test method.
 *
 * 
Formal Parameter List
 *
 * A {@code @VariantTest} method may declare additional parameters at
 * the end of the method's parameter list to be resolved by other
 * {@link org.junit.jupiter.api.extension.ParameterResolver ParameterResolvers}
 * (e.g., {@code TestInfo}, {@code TestReporter}, etc). Specifically, a
 * variant test method must declare formal parameters according to the
 * following rules.
 *
 * 

 * Zero or more indexed arguments must be declared first.
 * Zero or more aggregators must be declared next.
 * Zero or more arguments supplied by other {@code ParameterResolver}
 * implementations must be declared last.
 * 
 *
 * In this context, an indexed argument is an argument for a given
 * index in the {@code Arguments} provided by an {@code ArgumentsProvider} that
 * is passed as an argument to the variant method at the same index in the
 * method's formal parameter list. An aggregator is any parameter of type
 * {@link org.junit.jupiter.params.aggregator.ArgumentsAccessor ArgumentsAccessor}
 * or any parameter annotated with
 * {@link org.junit.jupiter.params.aggregator.AggregateWith @AggregateWith}.
 *
 * 
Argument Conversion
 *
 * Method parameters may be annotated with
 * {@link org.junit.jupiter.params.converter.ConvertWith @ConvertWith}
 * or a corresponding composed annotation to specify an explicit
 * {@link org.junit.jupiter.params.converter.ArgumentConverter ArgumentConverter}.
 * Otherwise, JUnit Jupiter will attempt to perform an implicit
 * conversion to the target type automatically (see the User Guide for further
 * details).
 *
 * 
Composed Annotations
 *
 * {@code @VariantTest} may also be used as a meta-annotation in order
 * to create a custom composed annotation that inherits the semantics
 * of {@code @VariantTest}.
 *
 * @since 5.0
 * @see org.junit.jupiter.params.provider.Arguments
 * @see org.junit.jupiter.params.provider.ArgumentsProvider
 * @see org.junit.jupiter.params.provider.ArgumentsSource
 * @see org.junit.jupiter.params.provider.CsvFileSource
 * @see org.junit.jupiter.params.provider.CsvSource
 * @see org.junit.jupiter.params.provider.EnumSource
 * @see org.junit.jupiter.params.provider.MethodSource
 * @see org.junit.jupiter.params.provider.ValueSource
 * @see org.junit.jupiter.params.aggregator.ArgumentsAccessor
 * @see org.junit.jupiter.params.aggregator.AggregateWith
 * @see org.junit.jupiter.params.converter.ArgumentConverter
 * @see org.junit.jupiter.params.converter.ConvertWith
 */
@Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
//@API(status = EXPERIMENTAL)
@TestTemplate
@ExtendWith(VariantTestExtension.class)
public @interface VariantTest {

  /**
   * The name pattern to be used for invocations of the variant test;
   * never blank or consisting solely of whitespace.
   *
   * 
You may use the following placeholders:
   * 

   * {index}: the current invocation index (1-based)
   * {arguments}: the complete, comma-separated arguments list
   * {0}, {1}, etc.: an individual argument (0-based)
   * 
   *
   * For the latter, you may use {@link java.text.MessageFormat} patterns
   * to customize formatting of values.
   *
   * @see java.text.MessageFormat
   */
  String name() default "[{index}] {arguments}";

}