Gtest: An interactive test program for the Anet API

Copyright 1995-2001, Activision
Last updated: 13 May 98



Gtest was originally a small demo program to show how to create an Anet session. It has grown to become a useful tool for understanding the Anet API, for testing API functions, for troubleshooting games written with Anet, and for running small Internet game servers for testing.

Gtest is a command-line interface to the Anet API. It lets you call most of the dp and dpio functions directly. It also has a few commands to support writing test scripts, and rudimentary simulation of a network game's frame update cycle.

Gtest makes a good tool for learning, too, especially if you are willing to refer to the source file, gtest.c, to make up for the poor documentation.

Starting Gtest

Gtest is run from the DOS commandline (even the Windows version!). Choose the version you want to run, and copy it into the current directory. Debugging and nondebugging precompiled versions for Windows (win/bin/gtest.exe and (win/bin/gtestd.exe) are included in the SDK.

Gtest prints out a usage message if you run it without arguments that lists the commandline options:

Usage: gtest [-N:comm.dll][-B:busy10msec][-P:adrString][-S][-x]
[-W:phonenum][-Y:commportnum(0 : com1)][-Z:baudrate][-I:modeministr]

Option details:
-n:foo.dll Load comm dll foo.dll
-b:10      Burn CPU for 10 centisec, then call dpReceive until empty, repeat
-p:server  Connect to given game server
-s         Read commands from stdin (needed for win32)
-x         use dpio, not dp
-c         don't create dp on startup
Copy the transport DLL you want to use to the current directory, then specify it when you start gtest with -N:path, e.g.
gtest -N:wipx2d.dll
The current comm dll's are

If you use a version that was compiled for debugging, it will read gtest.ini on startup.

Gtest Commands

After you start gtest, it waits for you to type commands. Commands may be abbreviated, e.g. HOST may be abbreviated HO. Here is what typing HELP at the gtest prompt shows:
help:  Basic script language commands 
help:     #                 -- Comment
help:     help              -- Get help
help:     quit              -- terminate program (can give an exit code; default 0)
help:     remotequit        -- tell other players to terminate program
help:     wait              -- Wait until enum or join finishes.
help:     sleep             -- Sleep given number of seconds
help:     busy              -- Be busy given number of 10ms per main loop
help:     set               -- Set var to val; var is theVar or dwUser1
help:     show              -- Print variable value; var is one of anyGroup,anyPlayer,dwUser1,n_players,n_sessions,theError,theVar,thisGroup, or thisPlayer
help:     spam              -- Send data to node at intervals
help:     assert            -- Compare values and abort if unequal; var is one of anyGroup,anyPlayer,dwUser1,n_players,n_sessions,theError,theVar,thisGroup, or thisPlayer
help:  dpio commands 
help:     dpio_create       -- Load dpio
help:     dpio_openHdl      -- Open a comm handle to a given node
help:     dpio_closeHdl     -- Close a comm handle
help:     dpio_findTimedOutHost -- Find closed handles
help:     dpio_setMaxPlayerHdls -- Set maximum handles
help:     dpio_setHandleOptions -- Set handle options
help:     dpio_put_reliable -- Send datagram via dpio reliably to given node
help:     dpio_freeze       -- Save dpio to disk [dpio.dat]
help:     dpio_thaw         -- Restore dpio from disk [dpio.dat]
help:     statinit          -- initialize dp statistics
help:     statprint         -- print dp statistics
help:  startup/shutdown 
help:     enumtransports    -- list available transports
help:     gameservers       -- list available game servers
help:     setGameServer     -- connects to a game server
help:     dpCreate          -- load dp
help:     dpDestroy         -- unload dp
help:     freeze            -- freeze the current session and destroy
help:     thaw              -- Restore a dp session from disk
help:  session mgmt 
help:     species           -- Set species used for listing and hosting
help:     host              -- create new session; name [maxpl] [flags] [dwuser1].
help:     lobby             -- declare the current session to be a server lobby
help:     join              -- join an existing session
help:     joinany           -- join any existing session
help:     dpClose           -- Disconnect from the current session
help:     sessions          -- list available sessions
help:     sdeltas           -- request session deltas; [on|off]
help:     gdeltas           -- request gameserver deltas; [on|off]
help:     pdeltas           -- request player deltas; [on|off]
help:     dpGetSessionDesc  -- get current session description
help:  player mgmt 
help:     players           -- list players in current session
help:     rplayers          -- list players in named session
help:     xplayers          -- list players in current session
help:     xrplayers         -- list players in named session
help:     newplayer         -- create a player in current session
help:     delplayer         -- destroy a player in current session
help:     setpname          -- change the name of the player with the given id
help:     setpblob          -- change the blob of the player with the given id
help:  group mgmt 
help:     groups            -- list groups in current session
help:     newgroup          -- create a group in current session
help:     delgroup          -- destroy a group in current session
help:     gaddplayer        -- add a player to a group
help:     gdelplayer        -- delete a player from a group
help:     gplayers          -- list players in given group
help:  player variables 
help:     pset              -- Set a variable of a player
help:     fpset             -- Set a variable of a player to a given file
help:     pget              -- Get value of a variable of a player
help:  misc 
help:     ping              -- measure round trip lag time to a player
help:     scap              -- Get capabilities of current session.
help:     enumapp           -- list available applications
help:     patch             -- Check whether patch is needed [apply]
help:     pickapp           -- pick an existing application for use with launchapp
help:     launchapp         -- freeze, start the application selected from pickapp, then destroy
help:     crash             -- cause an exception
help:  sending/receiving datagrams 
help:     send              -- send a packet to a given player or group
help:     chat              -- broadcast a chat message

The assert command

The assert command lets you refer to the results of past commands in a few special cases. The variables supported at the moment are You use the assert command to test whether one of these variables has the value you expected. For instance,
assert n_sessions > 0
makes sure at least one session was found. You may use the >, <, ==, and != comparison operators inside assert commands. If the condition does not evaluate to TRUE, the program is aborted with an error message.


The following examples will use nondebugging Windows dll's, so all the dll names will start in W and not end in D. If you want log files, substitute the debugging gtest (gtestd.exe) and the debugging dll's (e.g. wipx2d.dll).

Joining a game

Try starting a game on one machine as follows:
C:> gtest -n=wipx2.dll 
and joining it from another machine as follows:
C:> gtest -n=wipx2.dll 
join demo
newplayer Joe
When the player Joe is created, all other machines in the game will handle the dp_user_addPlayer_packet_t system message, and display a message on the screen.


To run gtest in batch mode, use the -s option to read from stdin, and redirect input. You can use the wait command to wait for an callback to complete, or the sleep command to wait for a fixed amount of time; gtest will continue listening for packets while it waits. For example, if contains
join demo
sleep 5
you can run it in gtest as follows:
C:> gtest -n=wipx2.dll -s <
and it will return to the DOS prompt automatically when it's done.

Scripts are great during debugging because they let you run regression tests. For example, to make sure that at least one game is active on the LAN, you could write a script

assert n_sessions > 0

There are example gtest scripts in the demo/gtest directory.

Dan Kegel