com.clarkware.junitperf

## Class LoadTest

- java.lang.Object
- - com.clarkware.junitperf.LoadTest

    public class LoadTest
    extends java.lang.Object

The `LoadTest` is a test decorator that runs a test with a simulated number of concurrent users and iterations.

In its simplest form, a `LoadTest` is constructed with a test to decorate and the number of concurrent users.

For example, to create a load test of 10 concurrent users with each user running `ExampleTest` once and all users started simultaneously, use:

>      Test loadTest = new LoadTest(new TestSuite(ExampleTest.class), 10);

or, to load test a single test method, use:

>      Test loadTest = new LoadTest(new ExampleTest("testSomething"), 10);

The load can be ramped by specifying a pluggable `Timer` instance which prescribes the delay between the addition of each concurrent user. A `ConstantTimer` has a constant delay, with a zero value indicating that all users will be started simultaneously. A `RandomTimer` has a random delay with a uniformly distributed variation.

For example, to create a load test of 10 concurrent users with each user running `ExampleTest.testSomething()` once and with a one second delay between the addition of users, use:

>      Timer timer = new ConstantTimer(1000);
>      Test loadTest = new LoadTest(new ExampleTest("testSomething"), 10, timer);

In order to simulate each concurrent user running a test for a specified number of iterations, a `LoadTest` can be constructed to decorate a `RepeatedTest`. Alternatively, a `LoadTest` convenience constructor specifying the number of iterations is provided which creates a `RepeatedTest`.

For example, to create a load test of 10 concurrent users with each user running `ExampleTest.testSomething()` for 20 iterations, and with a one second delay between the addition of users, use:

>      Timer timer = new ConstantTimer(1000);
>      Test repeatedTest = new RepeatedTest(new ExampleTest("testSomething"), 20);
>      Test loadTest = new LoadTest(repeatedTest, 10, timer);

or, alternatively, use:

>      Timer timer = new ConstantTimer(1000);
>      Test loadTest = new LoadTest(new ExampleTest("testSomething"), 10, 20, timer);

A `LoadTest` can be decorated as a `TimedTest` to test the elapsed time of the load test. For example, to decorate the load test constructed above as a timed test with a maximum elapsed time of 2 seconds, use:

>      Test timedTest = new TimedTest(loadTest, 2000);

By default, a `LoadTest` does not enforce test atomicity (as defined in transaction processing) if its decorated test spawns threads, either directly or indirectly. In other words, if a decorated test spawns a thread and then returns control without waiting for its spawned thread to complete, then the test is assumed to be transactionally complete.

If threads are integral to the successful completion of a decorated test, meaning that the decorated test should not be treated as complete until all of its threads complete, then `setEnforceTestAtomicity(true)` should be invoked to enforce test atomicity. This effectively causes the load test to wait for the completion of all threads belonging to the same `ThreadGroup` as the thread running the decorated test.

Author:
  Mike Clark, Clarkware Consulting, Inc., Ervin Varga

### Constructor Summary

Constructors
Constructor and Description
`LoadTest(Test test, int users)` Constructs a `LoadTest` to decorate the specified test using the specified number of concurrent users starting simultaneously.
`LoadTest(Test test, int users, int iterations)` Constructs a `LoadTest` to decorate the specified test using the specified number of concurrent users starting simultaneously and the number of iterations per user.
`LoadTest(Test test, int users, int iterations, Timer timer)` Constructs a `LoadTest` to decorate the specified test using the specified number of concurrent users, number of iterations per user, and delay timer.
`LoadTest(Test test, int users, Timer timer)` Constructs a `LoadTest` to decorate the specified test using the specified number of concurrent users and delay timer.

### Method Summary

Methods
`protected void` `cleanup()`
`int` `countTestCases()` Returns the number of tests in this load test.
`protected long` `getDelay()`
`void` `run(TestResult result)` Runs the test.
`void` `setEnforceTestAtomicity(boolean isAtomic)` Indicates whether test atomicity should be enforced.
`protected void` `sleep(long time)`
`java.lang.String` `toString()`
`protected void` `waitForAllThreadsToComplete()`
`protected void` `waitForTestCompletion()`
`protected void` `waitForThreadedTestThreadsToComplete()`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Constructor Detail

#### LoadTest

    public LoadTest(Test test,
            int users)

Constructs a `LoadTest` to decorate the specified test using the specified number of concurrent users starting simultaneously.

Parameters:
  `test` - Test to decorate.
  `users` - Number of concurrent users.

#### LoadTest

    public LoadTest(Test test,
            int users,
            int iterations)

Constructs a `LoadTest` to decorate the specified test using the specified number of concurrent users starting simultaneously and the number of iterations per user.

Parameters:
  `test` - Test to decorate.
  `users` - Number of concurrent users.
  `iterations` - Number of iterations per user.

#### LoadTest

    public LoadTest(Test test,
            int users,
            int iterations,
            Timer timer)

Constructs a `LoadTest` to decorate the specified test using the specified number of concurrent users, number of iterations per user, and delay timer.

Parameters:
  `test` - Test to decorate.
  `users` - Number of concurrent users.
  `iterations` - Number of iterations per user.
  `timer` - Delay timer.

#### LoadTest

    public LoadTest(Test test,
            int users,
            Timer timer)

Constructs a `LoadTest` to decorate the specified test using the specified number of concurrent users and delay timer.

Parameters:
  `test` - Test to decorate.
  `users` - Number of concurrent users.
  `timer` - Delay timer.

### Method Detail

#### setEnforceTestAtomicity

    public void setEnforceTestAtomicity(boolean isAtomic)

Indicates whether test atomicity should be enforced.

If threads are integral to the successful completion of a decorated test, meaning that the decorated test should not be treated as complete until all of its threads complete, then `setEnforceTestAtomicity(true)` should be invoked to enforce test atomicity. This effectively causes the load test to wait for the completion of all threads belonging to the same `ThreadGroup` as the thread running the decorated test.

Parameters:
  `isAtomic` - `true` to enforce test atomicity; `false` otherwise.

#### countTestCases

    public int countTestCases()

Returns the number of tests in this load test.

Returns:
  Number of tests.

#### run

    public void run(TestResult result)

Runs the test.

Parameters:
  `result` - Test result.

#### waitForTestCompletion

    protected void waitForTestCompletion()

#### waitForThreadedTestThreadsToComplete

    protected void waitForThreadedTestThreadsToComplete()

#### waitForAllThreadsToComplete

    protected void waitForAllThreadsToComplete()

#### sleep

    protected void sleep(long time)

#### cleanup

    protected void cleanup()

#### toString

    public java.lang.String toString()

Overrides:
  `toString` in class `java.lang.Object`

#### getDelay

    protected long getDelay()