org.databene.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
 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.
 

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:
org.databene.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:
{}


Copyright © 2013. All Rights Reserved.