You can think of Testbench as an SVG viewer, with extra debugging features which are useful for Volity UI scripting. Alternatively, you can think of Testbench as Gamut with all the network code stripped out.
Download Testbench from the [Volity release page].
Running Testbench
Launch the Testbench.jar file in the standard manner for your operating system (probably double-clicking it). Or type
java -jar Testbench.jar
A dialog box will appear which prompts you to choose an SVG file or a Zip file containing UI data.
You can also specify a UI file on the command line. Type
java -jar Testbench.jar UIFILE
...where UIFILE can be an SVG file, a directory containing UI data, or a Zip file containing such a directory. (See SVG UI file strategy.)
When you have selected a UI, you will see what looks like a Gamut window:
The main pane shows your UI. Below that is a "chat" log; in Testbench, this shows status messages. Below that is a message-input line. Javascript commands typed here are executed directly inside your UI.
The "Reload" menu command reloads the UI file, redisplays it, and starts the scripting context over from scratch. If you're editing the UI, use "Reload" after you make any change.
Starting and Ending Games
Above the UI are "Start Game" / "End Game" buttons, and a pop-up menu. This is your control over the simulated referee.
(The contents of the pop-up menu are inferred from any seattokens.xml you have in your UI's locale directory. If you have no localization files, the menu will contain only "seat.html" class=wikipagelink>seat ID into the pop-up field.)
When you start Testbench, the UI is displayed as if you had joined a new table, in setup phase. You are not seated.
If you select a seat in the pop-up menu and then press "game_observation.html" class=wikipagelink>observer.
Future expansion: Add buttons for suspension/unsuspension. Prevent the "Start Game" button from being pressed twice in a row, as is currently possible. React to the pop-up seating menu immediately -- a player normally sits down well before the game starts.
Debugging Features
As noted above, you can type any Javascript command in the message line. It will be executed immediately. This allows you to adjust variables and simulate RPCs from the referee.
A shortcut: typing
? EXPRESSION
...will evaluate EXPRESSION and print its value in the message pane.
To simulate an incoming RPC, type
game.methodname(arg1, arg2, ...);
Do not do this:
rpc(methodname, arg1, arg2, ...);
That invokes the function which your UI uses to send RPCs. In the Testbench environment, the rpc() function prints its arguments to the message pane, and has no other effect.
testbench.xml
You can add additional buttons to the Testbench toolbar by including a testbench.xml file in your UI directory. This file is ignored by regular Volity clients; but Testbench parses it for debugging commands.
The format of the file:
<?xml version="1.0"?> <testbench> <button name="Print"> literalmessage($X); </button> <field name="X" /> <field name="Y" type="int" /> </testbench>
A <button> tag creates a button. (The name attribute will be the button's name.) The text of the <button> tag should be one or more Javascript statements.
The button is effectively a macro for a debugging command; pushing it executes the button's text. (But note that the "?" shortcut is not available in button macros. Call the literalmessage() function to print messages.)
A <field> tag creates a text-entry field. (Again, name is the field's name. type="int" restricts the field to be an integer.) Any occurrence of $name in a debugging command is substituted with the current value of the named field. The value is expressed as a string literal (or, for an int field, an integer literal). So, in the example above, the contents of the X field are printed directly to the message pane.
Yes, $name substitutions apply to Javascript commands you type in the message pane, as well as button macros. Use "$$" if you want a literal "$". Also, remember that a (string) field produces a double-quoted string literal, not the exact text from the field. A debugging command like
literalmessage("Hello $X"); // wrong!
...will come out looking like
literalmessage("Hello "xfield""); // wrong!
...which is not valid Javascript. Instead, use this:
literalmessage("Hello " + $X);
Bugs
No doubt many, but here are the worst:
- When the UI sends an RPC to the simulated referee, there is no way for it to receive a reply. Then again, there's no way for that to happen in Gamut either. Stay tuned.