com.browsermob.api
Interface BrowserMob

public interface BrowserMob

The main control interface for BrowserMob scripts - All scripts must start here first. This object allows the script author to create both Real Bruwser User (RBU) and Virtual User (VU) scripts. This object is available as the variable browserMob from within the a JavaScript-enabled script. This object is effectively the "starting point" for all other scripts, as it serves as the interface for interacting with web sites (via openBrowser() and openHttpClient() as well as the mechanism for controling transactions and steps (via beginTransaction() and beginStep(String)).

This object also provides other useful functions, such as assistance with file uploads (filePath(String)), simulating "user think time" (pause(long)), and parameterizing tests with unique data (getUserNum() and getTxCount()).

Method Summary

TransactionStep	beginStep(java.lang.String step) Starts a BrowserMob step (must be called from within a transaction).
Transaction	beginTransaction() Starts a BrowserMob transaction.
void	closeBrowser() Terminates the active Selenium browser session.
void	endStep() Stops the current step.
void	endTransaction() Ends the current transaction.
java.lang.String	filePath(java.lang.String name) Returns the local path for the specified file name.
java.lang.String[]	findRegexMatches(java.lang.String content, java.lang.String regex) A simple way to find one or more regular expression matches against some content.
Transaction	getActiveTransaction() Returns the currently active transaction, which is useful for advanced use cases where the transaction object is being manipulated directly.
CSVTable	getCSV(java.lang.String name) Creates and returns a table of data backed by a Comma Separated Value file.
int	getTxCount() Returns the count of transactions that have been completed (regardless of success or failure) for this particular RBU/VU.
int	getUserNum() Returns the unique number for each independent RBU or VU in a load test.
boolean	isValidation() Indicates if the current execution environment is an actual real time script playback or if this is simply a script validation run that is used during script development.
void	log(java.lang.String log) Logs some text to the log buffer.
Selenium	openBrowser() Starts a Selenium browser session.
HttpClient	openHttpClient() Starts a basic HTTP client that is capabable of GET and POST requests, allowing the script author to simulate real web browsers.
void	pause(long pauseTimeInMs) Instructs the script to pause for a specified ammount of time.
void	quickStop() Normally when a load test is paused or the load level drops to fewer concurrent users, BrowserMob allows the actively running scripts to finish executing and complete the current transaction.
void	setSimulatedBps(int simulatedBps) Sets an artificial bits-per-second value for all data transfered to and from the RBU or VU.
void	stopExpected() Tells BrowserMob that the script is expecting that it could be stopped at any time and that if that happens, it should not be considered an error.
void	waitForNetworkTrafficToStop(long quietPeriodInMs, long timeoutInMs) Waits until no HTTP traffic associated with the current test has taken place for at least quietPeriodInMs.

Method Detail

openBrowser

Selenium openBrowser()

Starts a Selenium browser session. A call to this function indicates that the script is a Real Browser User script and will be billed accordingly. Only one browser is allowed to be open at a time, so any additional call to this will automatically close the previous one.

Returns:

an object representing the Selenium browser.

openHttpClient

HttpClient openHttpClient()

Starts a basic HTTP client that is capabable of GET and POST requests, allowing the script author to simulate real web browsers. A call to this function indicates that the script is a Virtual User script and will be billed accordingly.

Returns:

an object representing a virtual user, capable of issuing HTTP requests.

beginTransaction

Transaction beginTransaction()

Starts a BrowserMob transaction.

Returns:

a handle to the transaction object, which can be further manipulated for advanced use cases.

beginStep

TransactionStep beginStep(java.lang.String step)

Starts a BrowserMob step (must be called from within a transaction).

Parameters:

step - a description of the step, to be used for various reporting.

Returns:

a handle to the step object, which can be further manipulator for advanced use cases.

endStep

void endStep()

Stops the current step. Any activity (from either an RBU or a VU) will not be recorded until a new step is started.

pause

void pause(long pauseTimeInMs)
           throws java.lang.InterruptedException

Instructs the script to pause for a specified ammount of time. If we are in an active step and/or transaction, the pause time is added to those for reporting purposes automatically. Pause times are limited to 30 seconds during script validation, though the full time is honored during a real test playback, such as a load test.

Parameters:

pauseTimeInMs - the time to pause (in milliseconds).

Throws:

java.lang.InterruptedException - if the script is paused, stopped, or aborted during execution

endTransaction

void endTransaction()

Ends the current transaction. Any activity (from either an RBU or VU) will not be recorded until a new transaction is started.

getActiveTransaction

Transaction getActiveTransaction()

Returns the currently active transaction, which is useful for advanced use cases where the transaction object is being manipulated directly.

Returns:

the currently active transaction (or null if no transaction is active).

closeBrowser

void closeBrowser()

Terminates the active Selenium browser session.

setSimulatedBps

void setSimulatedBps(int simulatedBps)

Sets an artificial bits-per-second value for all data transfered to and from the RBU or VU. If the script is an RBU, the max value that can be set is 768KB/sec (6291456 bits/sec). If the script is a VU, the max value that can be set is 100KB/sec (819200 bits/sec).

Parameters:

simulatedBps - the bits-per-second to simulate.

getUserNum

int getUserNum()

Returns the unique number for each independent RBU or VU in a load test. The sequence starts at 0 and goes up to the max number of users participating in a load test. This function is especially useful for situations where data parameterization is required, such as typing an email address such as "test_user_X@example.com", where X is the user number.

Returns:

a number representing the RBU or VU in a load test.

getTxCount

int getTxCount()

Returns the count of transactions that have been completed (regardless of success or failure) for this particular RBU/VU. This count is not the total transaction count system wide, but rather just for the local user.

Returns:

the total number of transactions run for this local RBU or VU.

filePath

java.lang.String filePath(java.lang.String name)

Returns the local path for the specified file name. This path will resolve to a file on the local system that can be used for file uploads in a transaction.

Parameters:

name - the name of the file used by the script - usually a simple name like "foo.txt".

Returns:

the path on the local system.

log

void log(java.lang.String log)

Logs some text to the log buffer. Logs are only accessible for transactions run during development (such as script validation) and not during an actual load test.

Parameters:

log - the text to log.

isValidation

boolean isValidation()

Indicates if the current execution environment is an actual real time script playback or if this is simply a script validation run that is used during script development. This allows scripts to have slightly different behavior during validation than during a real playback, such as a during a load test. A common use for this function is to limit the "think time" simulated by the pause(long) function to a shorter time period when validating the script.

Returns:

true if the current context is a script validation, false otherwise.

stopExpected

void stopExpected()

Tells BrowserMob that the script is expecting that it could be stopped at any time and that if that happens, it should not be considered an error. This is most commonly used in conjuction with quickStop().

quickStop

void quickStop()

Normally when a load test is paused or the load level drops to fewer concurrent users, BrowserMob allows the actively running scripts to finish executing and complete the current transaction. Sometimes, especially for very long running scripts, such as testing a streaming video, it is desirable to interupt the script immediately. Calls to this function tell BrowserMob that when a "stop" event (such as a pause, ramp down, or end of a test) occur, the script should attempt to stop executing as quickly as possible. This is most commonly used in conjuction with $stopExpected().

getCSV

CSVTable getCSV(java.lang.String name)

Creates and returns a table of data backed by a Comma Separated Value file. This allows scripts to depend on data sets that can be helpful for more realistic testing, such as using a different username/password to login to a website each time the script runs.

Parameters:

name - the name of the CSV file, which you will be asked to upload by BrowserMob upon saving your script the first time.

Returns:

an object that represents the CSV table.

waitForNetworkTrafficToStop

void waitForNetworkTrafficToStop(long quietPeriodInMs,
                                 long timeoutInMs)

Waits until no HTTP traffic associated with the current test has taken place for at least quietPeriodInMs. If this function has to wait for longer than timeoutInMs an error will be thrown, causing the transaction to fail.

This function will generally, but not always, result in a pause time equal to the length of quietPeriodInMs, since it will need to wait that long to determin if no network traffic has taken place.

Parameters:

quietPeriodInMs - the period of time that we expect to not see any HTTP traffic.

timeoutInMs - the total time the function should wait before giving up and throwing an error.

findRegexMatches

java.lang.String[] findRegexMatches(java.lang.String content,
                                    java.lang.String regex)

A simple way to find one or more regular expression matches against some content. For example, the following code will extract all the text between any span tag that has a class of "foo":

 var matches = browserMob.findRegexMatches(resp.getBody(), '<span class="foo">([^<]*)<span>');
 

Parameters:

content - the content to match against.

regex - the regular expression to match, which should include one and only one regular expression group.

Returns:

an array of sub-strings from the content that match the supplied regular expression