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 controlling 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 stepLabel) Starts a BrowserMob step using the first step number in sequence (must be called from within a transaction).
TransactionStep	beginStep(java.lang.String stepLabel, int stepNbr) Starts a BrowserMob step using the specified step number in sequence (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.
TransactionStep	getActiveStep() Returns the currently active step, which is useful for advanced use cases where the step object is being manipulated directly.
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.
File	getFile(java.lang.String name) Returns a wrapped handle to an uploaded 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.
WebDriver	openBrowserWebDriver() Starts a WebDriver 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	pause(long pauseTimeInMs, boolean includeInTimeActive) 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	setDownstreamKbps(long downstreamKbps) Sets an artificial kilobits-per-second value for all data transfered to (downstream) the RBU or VU.
void	setLatency(long latency) Sets an artificial latency simulation for sending one full MTU (~1500 bytes on the internet).
void	setSimulatedBps(int simulatedBps) Deprecated. Use setDownstreamKbps(long), setUpstreamKbps(long) (long)}, and setLatency(long) (long)} instead
void	setUpstreamKbps(long upstreamKbps) Sets an artificial kilobits-per-second value for all data transfered from (upstream) 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.
boolean	waitFor(com.browsermob.agent.api.WaitForCallback callback, long timeoutInMs) Wait for the user specified function to return true.
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.

openBrowserWebDriver

WebDriver openBrowserWebDriver()

Starts a WebDriver 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 WebDriver 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 stepLabel)

Starts a BrowserMob step using the first step number in sequence (must be called from within a transaction).

Parameters:

stepLabel - 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.

beginStep

TransactionStep beginStep(java.lang.String stepLabel,
                          int stepNbr)

Starts a BrowserMob step using the specified step number in sequence (must be called from within a transaction).

Parameters:

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

stepNbr - the actual step sequence number within the step description label

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

pause

void pause(long pauseTimeInMs,
           boolean includeInTimeActive)
           throws java.lang.InterruptedException

Instructs the script to pause for a specified ammount of time. If includeInTimeActive is true, the pause time is considered part of the active transaction time. If includeInTimeActive is false and 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).

includeInTimeActive - 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).

getActiveStep

TransactionStep getActiveStep()

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

Returns:

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

closeBrowser

void closeBrowser()

Terminates the active Selenium browser session.

setSimulatedBps

void setSimulatedBps(int simulatedBps)

Deprecated. Use setDownstreamKbps(long), setUpstreamKbps(long) (long)}, and setLatency(long) (long)} instead

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.

setDownstreamKbps

void setDownstreamKbps(long downstreamKbps)

Sets an artificial kilobits-per-second value for all data transfered to (downstream) the RBU or VU. If the script is an RBU, the max value that can be set is 6500 Kbps. If the script is a VU, the max value that can be set is 1000 Kbps.

Parameters:

downstreamKbps - the kilobits-per-second to simulate.

setUpstreamKbps

void setUpstreamKbps(long upstreamKbps)

Sets an artificial kilobits-per-second value for all data transfered from (upstream) the RBU or VU. If the script is an RBU, the max value that can be set is 6500 Kbps. If the script is a VU, the max value that can be set is 1000 Kbps. Typically this value should be less than the downstream value to reflect a real internet user.

Parameters:

upstreamKbps - the kilobits-per-second to simulate.

setLatency

void setLatency(long latency)

Sets an artificial latency simulation for sending one full MTU (~1500 bytes on the internet). For high speed connections, such as FIOS, 1ms is fine. To simulate a slower ADSL connection, 50ms might make sense. For really slow dial-up connections, 200ms or more may be appropriate.

Parameters:

latency - the latency in milliseconds.

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.

Returns:

an object that represents the CSV table.

getFile

File getFile(java.lang.String name)

Returns a wrapped handle to an uploaded file. This is useful for reading file contents in scripts and for use in multipart post requests. For details on adding the file to a post request, see HttpPostRequest#addFileUpload(String, File).

Parameters:

name - the filename, which you will be asked to upload by BrowserMob upon saving your script.

Returns:

an object that represents the file.

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

waitFor

boolean waitFor(com.browsermob.agent.api.WaitForCallback callback,
                long timeoutInMs)

Wait for the user specified function to return true. If this function has to wait longer than timeoutInMs then false will be returned. The arguments passed in must be in in this form:

 browserMob.waitFor(function() {
     // Determine if the waitFor condition is satisfied and return a boolean value
     return isConditionSatisfied;
 }, 3000);
 

Parameters:

callback - the javascript function, in the form of function() { ... }

timeoutInMs - the total time the function should wait before giving up and returning false.