com.github.javatlacati.contiperf

Annotation Type PerfTest

@Documented
 @Target(value={METHOD,TYPE})
 @Retention(value=RUNTIME)
public @interface PerfTest

Defines execution details and performance requirements for a test method: How long the test should take, the level of concurrency and timings to apply. Two basic modes can be used: count-based or duration-based execution.

Count-based execution

In count-based execution, the total number of test executions is stated and ContiPerf runs until the number has been reached - however slow or fast this may be. Example: @PerfTest(invocations = 3000, threads = 10) advises ContiPerf to execute the annotated test method 3000 times with up to 10 threads in parallel

Duration-based execution

In duration-based execution ContiPerf repeats test invocation only as long as a stated test duration has been reached or exceeded. This is especially suited for performing test runs over a certain (longer) period of time for memory leak and stability testing.

Timing

In order not to have tests run continuously at full speed, but to achieve some more user-interaction-like behavior, timers can be used: They incur a wait time between invocations. ContiPerf comes with some predefined timers (ConstantTimer, RandomTimer and CumulatedTimer) and you can easily define custom ones. Example: @PerfTest(invocations = 1000, threads = 10, timer = RandomTimer.class, timerParams = { 30, 80 }) causes ContiPerf to wait for 30 to 80 milliseconds between the test invocations of each thread.

Ramp-up and warm-up time

If the tested component or system would be overloaded if all thread were immediately accessing it, a ramp-up mechanism can be used: When specifying a rampUp() time, the test run begins with a single thread. After the ramp-up period, a second thread is added, after one more ramp-up period a third and so on until the full number of threads has been reached. In order to ease switching between ramp-up scenarios, the duration() always specifies the time running with full number of threads, ramp-up times are always added to the duration. Example: @PerfTest(threads = 10, duration = 60000, rampUp = 1000) makes ContiPerf start with one thread, add a new thread each second until 10 threads are reached (which is the case after 9 seconds) and then runs the test at the full number of threads for 60 seconds. Consequentially, the total amount of time of test runs is 69 seconds. For measuring only the characteristics under full load, you can configure a warmUp() time to tell ContiPerf after which amount of time it should begin to measure and validate test execution. For the example above, a minimum rampUp time of 9 seconds is useful: @PerfTest(threads = 10, duration = 60000, rampUp = 1000, warmUp = 9000)

Created: 14.10.2009 14:41:18

Since:

1.0

Author:

Volker Bergmann

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	cancelOnViolation Set this to true, if execution should stop with a failure message as soon as a configured Required.max() value is violated.
Class<? extends Clock>[]	clocks One ore more Clock classes to use for time measurement.
int	duration The number of milliseconds to run and repeat the test with the full number of configured threads - use this alternatively to invocations().
int	invocations The total number of invocations to perform - use this alternatively to duration().
int	rampUp The number of milliseconds to wait before each thread is added to the currently active threads.
int	threads The number of threads which concurrently invoke the test.
Class<? extends WaitTimer>	timer The class of a WaitTimer implementation by which a wait time can be incurred between test invocations
double[]	timerParams The parameters to initialize the WaitTimer.
int	warmUp The number of milliseconds to wait before the actual measurement and requirements monitoring is activated.

Element Detail

invocations

public abstract int invocations

The total number of invocations to perform - use this alternatively to duration(). The default value is one. @see #duration()

Default:

1

duration

public abstract int duration

The number of milliseconds to run and repeat the test with the full number of configured threads - use this alternatively to invocations(). When using a rampUp(), the ramp-up times add to the duration.

See Also:

duration()

Default:

-1

threads

public abstract int threads

The number of threads which concurrently invoke the test. The default value is 1.

Default:

1

rampUp

public abstract int rampUp

The number of milliseconds to wait before each thread is added to the currently active threads. On duration()-based tests, the total ramp-up time of rampUp * (threads - 1) is added to the configured duration.

Default:

0

warmUp

public abstract int warmUp

The number of milliseconds to wait before the actual measurement and requirements monitoring is activated. Use this to exclude ramp-up times from measurement or wait some minutes before dynamic optimizations are applied (like code optimization or cache population).

Default:

0

cancelOnViolation

public abstract boolean cancelOnViolation

Set this to true, if execution should stop with a failure message as soon as a configured Required.max() value is violated. Set it to false, if you are interested in performing a full measurement to get percentiles, throughput and more. The default value is false.

Default:

false

timer

public abstract Class<? extends WaitTimer> timer

The class of a WaitTimer implementation by which a wait time can be incurred between test invocations

Default:

com.github.javatlacati.contiperf.timer.None.class

timerParams

public abstract double[] timerParams

The parameters to initialize the WaitTimer. The meaning of the values is individual for the WaitTimer implementation.

Default:

{}

clocks

public abstract Class<? extends Clock>[] clocks

One ore more Clock classes to use for time measurement. The first one specified is the one relevant for requirements verification.

Default:

{}