Automating Badboy with OLE

Badboy is built as a first-class COM object so that you can access it and automate it from external programs using your choice of programming or scripting language. For example, Badboy can be automated from VBScript, VBA (Visual Basic for Applications), and even from JScript. Badboy also exposes its OLE interface to JScript items running within Badboy scripts as the "window.badboy" object.

OLE Interface API

The following table lists the operations you can call to control Badboy through OLE.

Operation / PropertyDescription
currentThe id of the current play item (Read/Write property)
boolean openFile(BSTR* fileName)Causes the given file to be loaded. Note: this method is deprecated.
boolean openFile2(BSTR fileName)Causes the given file to be loaded.
void play()Causes playing to start (as if the user had clicked the "Play" button).
boolean isPlaying()Returns true if a play operation is in progress. If called after play finishes, returns false.
void sleep(LONG timeMs)Sleeps for the given time in milliseconds. This is useful when accessing via JScript as JScript does not have a native sleep operation.
ULONG saveResponseTimes(BSTR fileName)Saves response times to the given file.
void playAll(void)Starts playing but will play all the way through rather than pausing at Steps in the script.
LONG record(LONG id)Sets the recording point to the step with the given id, or the step containing the given item if it is not a step itself. If no step is found, fails and does not change the recording point or the recording state. To turn off recording, pass zero (0) as the recording id. If successful, returns the id of the item that became the recording Step as a result.
BSTR getVariableNames()Returns comma separated list of all defined variables
BSTR getVariable(BSTR variableName)Returns the value of the given variable.
void setVariable(BSTR variableName, BSTR variableValue)Sets the value of the given variable.
void getVariableProperty(BSTR variableName, BSTR propertyName) Returns the value of the specified property for the specified variable, if it exists.
  • name
  • currentValue
  • valueCount - number of values in variable's value list
  • value
  • obfuscate - "true" or "false"
  • autoVariableExpression - regex to use with auto update function
  • isAutoVariable - "true" or "false"
  • autoLink - "true" or "false"
void setVariableProperty(BSTR variableName, BSTR propertyName, BSTR propertyValue) Sets the value of the specified property for the given variable. Property values include:
  • name
  • currentValue
  • value
  • obfuscate - "true" or "false"
  • autoVariableExpression - regex to use with auto update function
  • isAutoVariable - "true" or "false"
  • autoLink - "true" or "false"
void deleteVariable(BSTR variableName)deletes the named variable including it's value list.
Object getResponse(LONG id)Search for and return the newest response under item with given id
void quit(void)Causes the Badboy instance to close/exit. NOTE: may be held in memory still depending on how the client holds the resources (it must release the reference).
void clearResponses(void)Deletes all responses in the Script. Use this in long running scripts to prevent Badboy from using an increasing amount of memory as it runs due to captured responses.
LONG seek(LONG id)Attempts to move the Badboy play engine to a position such that the given item (specified by its Id) will play next. Returns the Id of the actual item that will be played next after the seek() operation has been performed, or -1 if the seek() operation was unable to execute.
BSTR eval(BSTR expression)Evaluates the given expression, substituting variables according to Badboy's variable expression syntax. Variables may be referenced in the form "${name}" and values in variable value lists can be referenced using syntax "${name[index]}".
BOOL addValue(BSTR variableName, BSTR value); Adds the given value to the end of the given variables's value list.
LONG summary(LONG id, BSTR attribute)Returns the value of the requested summary attribute for the item in the script with the given id. Valid values of the attribute parameter are:
  • played
  • succeeded
  • failed
  • assertions
  • warnings
  • averageResponseTime
  • maxResponseTime
  • timeouts
void setUIOption(BSTR option, BSTR value); Controls aspects of the UI. Valid values of "option" include:
  • toolbars - "on" or "off"
void setSilent(BOOL isSilent) Sets "silent" mode on or off. Silent mode prevents any messages or other dialogs from showing that will halt the script from playing. This overrides settings that may exist on items such as Assertions. This is useful for playing scripts in an unsupervised setting without having to manually change configuration of items in the script.
BOOL save(BSTR format, BSTR fileName, BSTR options) Saves the script (or data exported from it) in the requested format. The "format" parameter can be one of:
  • BadboyScript - save script in binary format (*.bb)
  • Xml - save script in XML format (*.bx)
  • BadboyXml - export script to BadboyXML (*.xml) - not openable by Badboy
  • JMeter18 - export JMeter version of script
  • Report - save standard HTML Report
  • BrowserContent - content of current browser window

Options are a comma-separated list of attributes in the form "name1=value1,name2=value2". The only currently supported options are:

  • exportImages=true/false
  • includeResponseContent=true/false
versionProperty indicating the version of the installed version of Badboy.
BSTR progress(LONG id)returns a floating point value between 0 and 1 indicating the position of playback within the specified item.

Badboy also supports an OLE interface on the script items in the script. The script itself can be accessed as the "badboy.script" object and it and the children returned by it's operations support the Script Item interface in the following table:

NameDescription
long idRead-only property returning the id of this item in the script
Object find(LONG id)Find a given script item in the script, specified by it's Id and return it as an object.
Object nextReturn the next item after this one in the script
Object parentReturn the parent of this item in the script
long lengthRead-only property returning the number of direct children belonging to this item.
BSTR get(BSTR propertyName)return the value of the named property.
BOOL set(BSTR propertyName, BSTR propertyValue)Set the value of the named property.
Object at(LONG index)Returns the child of this item at specified index, if any.
BOOL removeAt(LONG index)Removes child at specified index, if it exists.

The above properties are supported on all items in a Badboy Script. Each type of item also has a list of named properties that are specific to that type, and which can be retrieved or set using the the "get()" and "set()" methods. See the Script Item Property Reference for full details of the properties available on individual item types.

Example 1:

This example shows how to set the name and value of a Form Value (a child of a Form Populator), in Badboy's script. The FormValue has the id 71:

    window.badboy.script.find(71).set("name","This is the new name!");
    window.badboy.script.find(71).set("value","This is the new value!");

Example 2:

This example shows how the Badboy OLE interface can be used to control Badboy with VBScript via the WSH (Windows Scripting Host). To run the example, save it as a file called "test.wsh" in your desktop, then double click the file. Make sure first that you have a script called "c:\test.bb" saved on your computer for it to open.

  '
  ' Example Program to Demonstrate OLE Scripting Access to Badboy
  '
  ' This program shows how you can manipulate Badboy as an OLE object 
  ' via the Windows Scripting Host.  You can load scripts and play them
  ' in a scripted environment this way.
  '
  ' Expect many more OLE methods & properties to be exposed in the future!
  '

  ' Create a Badboy instance
  Dim badboy
  Set badboy = WScript.CreateObject("Badboy.Document")

  ' Open a file to play
  badboy.openFile2("c:\test.bb")

  ' Note: at this point the window may be invisible.  If you want to see it 
  ' then you can set the visible property directly:
  ' badboy.Visible = true

  ' Tell badboy to start playing the script
  badboy.playAll

  ' If the script exits then the badboy instance will be destroyed.
  ' so sleep while it is playing to let it finish
  while badboy.isPlaying
      WScript.Sleep(1000)
  wend

  ' Get the number of failures
  failures = badboy.summary(1, "failed")

  ' Save response times
  badboy.saveResponseTimes("c:\\test.csv")

  MsgBox("Done with " & failures & " failures")

  

Badboy Documentation Generated on Mon Dec 29 22:28:42 EST 2008