moock.org > Unity Automated Test Client

Unity Automated Test Client
The Unity Automated Test Client is a simple Java application and custom Unity room designed to stress-test Unity Multiuser Server. The test client performs the following tasks:

Connect n clients
Have each client send n messages to the server (as fast as possible)
Wait for the server to respond to all messages
Repeat until failure (out of memory or threads).

Results for each iteration of the test are written to the server's log, as shown in the following example log entry:

2005-02-18 11:16:23,687 WARN  - Messages Processed: 2000
2005-02-18 11:16:23,687 WARN  - Average Process Time: 0.0615
2005-02-18 11:16:23,687 WARN  - Total Connected to Server: 2000

For each message received, the server records two times:

the time at which the message is received
the time at which a response has been created and loaded into the send buffer

The duration between those times is the "Process Time" for the message.

The "Average Process Time" indicates the average number of milliseconds it took the server to process one message under the current load. The process time for most messages in average applications is typically less than a millisecond. For example, in the preceding log entry, 2000 clients were connected to the server. When every client sent a message to the server at roughly the same time, it took 0.0615 milliseconds to process a single message.

The round-trip time required for a message to leave a client, arrive at the server, and be received back at the originating client is calculated as follows:

  [client's message-send time (including creating the message)]
+ [network time] 
+ [server-side message process time] 
+ [network time]
+ [client's message-receive time (including parsing the message)]

For example,

  [5ms]
+ [100ms] 
+ [0.0615ms (message process time)] 
+ [100ms]
+ [10ms]
=============
215.0615ms

The server-side message process time is typically the fastest stage of a message's round-trip.

Note that the Automated Test Client answers the following question only: "How long does it take the server to receive and respond to a single message given the current number of connections and incoming messages?". Factors such as client performance and network lag must be tested individually for each application by the application developer.

Customizing the Automated Test Client
Source code for the Automated Test Client is available for developers who wish to customize its behaviour.

>> Download Unity Automated Test Client Source Code

Installing and Using the Automated Test Client
The server and client components of the automated test client reside in a single file named tester.jar. To use the test client, you first need to obtain a copy of tester.jar here:

>> Download tester.jar

Once you have downloaded tester.jar, follow these steps to set up server-side support for the automated test client.

Place a copy of tester.jar in your Unity installation directory (/unity/ by default).

Add tester.jar to the classpath of the server's startup script. For example:

java -cp
tester.jar;lib\xerces.jar;lib\xml-apis.jar;lib\unity_core.jar;lib\log4j.jar;lib\jdom.jar 
-Dlog4j.configuration=file:ss.lcf org.moock.unity.core.Unity start

Optionally set the minimum and maximum heap size for the JVM. For example, the following options set the minimum heap size to 256MB and the maximum heap size to 768MB:

java -Xms256m -Xmx768m -cp
tester.jar;lib\xerces.jar;lib\xml-apis.jar;lib\unity_core.jar;lib\log4j.jar;lib\jdom.jar 
-Dlog4j.configuration=file:ss.lcf org.moock.unity.core.Unity start

Add the TestRoom room type to the TYPES tag in the server's uconfig.xml file, as follows:

<TYPES> 
  <ROOM>
    <ID>TestRoom</ID>
    <CLASS>org.moock.unity.tester.TestRoom</CLASS>
  </ROOM>     
</TYPES>

Add the testRoom room instance to the INSTANCES tag in the server's uconfig.xml file, as follows:

<INSTANCES>  
  <ROOM>
    <TYPE_ID>TestRoom</TYPE_ID>
    <ID>testRoom</ID>
    <NAMESPACE>tester</NAMESPACE>
    <ACCEPT_OUTSIDE_MESSAGES>true</ACCEPT_OUTSIDE_MESSAGES>
    <AUTOJOIN>true</AUTOJOIN>
  </ROOM>
</INSTANCES>

In the server's uconfig.xml file, use the MAX_CLIENTS to increase the allowed number of connections for your server to support the number of connections you wish to test. Removing the contents of the tag altogether specifies unlimited connections, as shown in the following example:
```
<MAX_CLIENTS></MAX_CLIENTS>
```
(Note that the maximum value of the MAX_CLIENTS tag for Express-licence servers is always 100, even if set to a greater value via uconfig.xml).
For easy-to-read test results, optionally set the log level to WARN in the server's ss.lcf file.
Start the server. Ensure that no other client applications connect to the server during the test.

Now follow these steps to run the automated test client. Results of the test are written to the server's log.txt file.

On the machine on which you will be running the test client, create a new directory named "testclient". (Should be a different machine than the machine on which the server is running).
Copy tester.jar to the /testclient/ directory.
Copy jdom.jar, log4j.jar, and unity_core.jar from your server installation's /unity/lib/ directory to /testclient/ on the client machine.
Start the client from the command line by running the class org.moock.unity.tester.Tester, ensuring that all jars (tester.jar, jdom.jar, log4j.jar, and unity_core.jar) are in the classpath. Command line options to Tester are:
- The IP or domain of the server to which the client should connect.
- The port on which the client should connect.
- The number of clients to connect at each iteration of the test.
- The number of messages each connected client should send at each iteration of the test.
For example, the following command tells the client to connect to a server running at the IP address 192.168.0.1 on port 100. The client will create 100 connections per test iteration and send 1 message over each connection per test iteration.
```
java -Xms256m -Xmx512m -cp 
tester.jar;unity_core.jar;log4j.jar;jdom.jar 
org.moock.unity.tester.Tester 192.168.0.1 9100 100 1
```
The above command also sets the JVM's minimum heap size to 256MB and maximum heap size to 512MB.

Note that the test is designed to run infinitely until failure. It will continue to connect clients until either the client machine or the server machine runs out of threads or memory. In either case, the console or server log will report exceptions or Out of Memory errors. For example, here is an Out of Memory error caused by hitting the system thread limit:

java.lang.OutOfMemoryError: unable to create new native thread
        at java.lang.Thread.start(Native Method)
        at org.moock.unity.core.w.a(Unknown Source)
        at org.moock.unity.core.n.f(Unknown Source)
        at org.moock.unity.core.p.run(Unknown Source)
        at java.lang.Thread.run(Unknown Source)

When errors occur, the test client and the server should be stopped. Results of the test will be available in the server's log.txt file.