Browsermob-proxy-client-nodejs

HTTP client is interacting with BrowserMobProxy backend trough REST API. With LittleProxy implementation only. ##Installation

npm i browsermob-proxy-client-nodejs

##Example

const bmpClient = require('browsermob-proxy-client-nodejs');

const bmpHost = '127.0.0.1'; //ip where BrowserMob Proxy was started
const bmpPort = 9090; //tcp port where BrowserMob Proxy was started

let browserMobProxyClient = undefined;

(new bmpClient(bmpHost, bmpPort)).create()
  .then((client) => {
    //Browser Mob Client
    browserMobProxyClient = client;
  })
  .then(() => {
  //start capture a traffic
    return browserMobProxyClient.newHar();
  })
  .then(() => {
    //make some request through browsermob proxy, that has started above
    const proxy = `http://${bmpHost}:${browserMobProxyClient.port}` 
    return makeSomeRequestThroughProxy(proxy); //it is a imaginary function
  })
  .then(() => {
    //get HAR
    return browserMobProxyClient.getHar();
  })
 .then((har) => {
    //make some action with HAR
    console.log(har);
  })
 .catch((value) => {done(new Error(value));});

##Usage First, you must start BrowserMob Proxy something like :

java -jar ./path/to/browsermobproxy.jar -port 9090

Ok, we may start coding:

Include browsermob-proxy-client-nodejs module in your application :

const bmp = require('browsermob-proxy-client-nodejs');

Create an object(bmpSet) for service set of browserMob Proxy instances. :

const bmpHost = '127.0.0.1';
const bmpPort = 9090; 

const bmpSet = new bmp(bmpHost, bmpPort);

Now, we are ready to create client for interacting with BrowserMob Proxy. Then, we can invoke all methods, that described below. Each method is Promise.

bmpSet.create()
  .then((client) => {
    return client.close();
  });

If you want control all of clients instance, you may use controllingMethods. Each method is Promise, too.

bmpSet.getProxiesList()
  .then((list) => {
    console.log(list);
    //print : [{port : 8080}, {port : 8081}, {port : 8083}]
  });

##Client methods

newHar([boolCaptureHeaders], [boolCaptureBody], [boolCaptureAllContent], [pageRef], [pageTitle])

Creates a new HAR attached to the proxy and returns the HAR content if there was a previous HAR

Param	Type	Default	Description
[boolCaptureHeaders]	boolean	true	capture headers or not
[boolCaptureBody]	boolean	false	capture content bodies or not
[boolCaptureAllContent]	boolean	false	capture binary content or not.
[pageRef]	string	"Page 1"	the string name of the first page ref that should be used in the HAR
[pageTitle]	string	"Page 1"	the title of first HAR page

Fulfill returned value : Object that represent HAR

startPage([newPageTitleObject], [pageRef], [pageTitle])

Starts a new page on the existing HAR

Param	Type	Default	Description
[newPageTitleObject]	object		-
[pageRef]	string	"Page N"	The string name of the first page ref that should be used in the HAR.
[pageTitle]	string	"Page N"	The title of new HAR page

Fulfill returned value : undefined

close()

Shuts down the proxy and closes the port.

Fulfill returned value : undefined

getHar()

Returns the JSON/HAR content representing all the HTTP traffic passed through the proxy (provided you have already created the HAR with this method)

Fulfill returned value : Object that represent HAR

getWhiteList()

Displays whitelisted items

Fulfill returned value : Array of urls which have set before by setWhiteList() method

setWhiteList(httpCodeStatus, regexps)

Sets a list of URL patterns to whitelist

Param	Type	Description
httpCodeStatus	number	the HTTP status code to return for URLs that do not match the whitelist.
regexps	string	a comma separated list of regular expressions.

Fulfill returned value : undefined

clearWhiteList()

Clears all URL patterns from the whitelist

Fulfill returned value : undefined

getBlackList()

Displays blacklisted items

Fulfill returned value : Array of object that represent black list item

Fulfill returned value description : It's one object desccription from array

Name	Type	Description
urlPattern	string	incoming regexp for blocking
statusCode	number	incoming http code is returned for blocked url
httpMethodPattern	string	incoming regular expression for matching HTTP method (GET, POST, PUT, etc). If null processing all HTTP method.
method	string	regular expression for matching HTTP method (GET, POST, PUT, etc). If null processing all HTTP method.
responseCode	number	http code is returned for blocked url
pattern	string	incoming regexp for blocking

setBlackList(httpCodeStatus, regexp, [methodsRegexp])

Setup url to black list

Param	Type	Description
httpCodeStatus	number	The HTTP status code to return for URLs that are blacklisted
regexp	string	The blacklist regular expression
[methodsRegexp]	string	The regular expression for matching HTTP method (GET, POST, PUT, etc). Optional, by default processing all HTTP method

Fulfill returned value : undefined

clearBlackList()

Clears all URL patterns from the blacklist

Fulfill returned value : undefined

setLimits([browserMobProxyLimitObject])

Sets the downstream bandwidth limit in kbps

Param	Type
[browserMobProxyLimitObject]	LimitsSetterObject

LimitsSetterObject : object

Object for setting up limits of BrowserMob Proxy

Name	Type	Default	Description
downstreamKbps	number		Downstream bandwidth limit in kbps
downstreamBps	number		Downstream bandwidth limit in bit per second
upstreamKbps	number		Upstream bandwidth limit in kbps
upstreamBps	number		Upstream bandwidth limit in bit per second
downstreamMaxKB	number		Specifies how many kilobytes in total the client is allowed to download through the proxy
upstreamMaxKB	number		Specifies how many kilobytes in total the client is allowed to upload through the proxy
latency	number	0	Add the given latency to each HTTP request. By default all requests are invoked without latency
enable	boolean	false	A boolean that enable bandwidth limiter. Setting any of the properties above will implicitly enable throttling
payloadPercentage	number		Specifying what percentage of data sent is payload, e.g. use this to take into account overhead due to tcp/ip
maxBitsPerSecond	number		The max bits per seconds you want this instance of StreamManager to respect

Fulfill returned value : undefined

getLimits()

Displays the amount of data remaining to be uploaded/downloaded until the limit is reached

Fulfill returned value : LimitsGetterObject

Fulfill returned value description :

LimitsGetterObject : object

Object describes amount of data remaining to be uploaded/downloaded until the limit is reached

Name	Type	Description
maxUpstreamKB	number	Show maxUpstreamKB set by setLimits
maxDownstreamKB	number	Show maxDownstreamKB set by setLimits
remainingUpstreamKB	number	Show how many kilobytes will be uploaded before the limit is reached
remainingDownstreamKB	number	Show how many kilobytes will be downloaded before the limit is reached

setHeaders(headers)

Set and override HTTP Request headers

Param	Type	Description
headers	object	Represents set of headers, where key is a header name and value is a value of HTTP header

Fulfill returned value : undefined

overrideDNS(dns)

Overrides normal DNS lookups and remaps the given hosts with the associated IP address

Param	Type	Description
dns	object	Represents set of of hosts, where key is a host name and value is a IP address which associated with host name

Fulfill returned value : undefined

setAutoAuthentication(auth, domain)

Sets automatic basic authentication for the specified domain. This method supports only BASIC authentication.

Param	Type	Description
auth	object	Object describes authentication data
auth.username	string	Login
auth.password	string	Password
domain	string	At the domain will be applying basic auth

Fulfill returned value : undefined

setWait(waitObject)

Wait till all request are being made

Param	Type	Description
waitObject	object	Object describes waits data
waitObject.quietPeriodInMs	number	amount of time after which network traffic will be considered "stopped"
waitObject.timeoutInMs	number	maximum amount of time to wait for network traffic to stop

Fulfill returned value : undefined

setTimeouts(timeoutObj)

Handles different proxy timeouts. The new LittleProxy implementation requires that all timeouts be set before start Proxy, because of it tests skipped.

Param	Type	Description
timeoutObj	object	Describes timeout object
timeoutObj.requestTimeout	number	Request timeout in milliseconds. timeout value of -1 is interpreted as infinite timeout.
timeoutObj.readTimeout	number	Read timeout in milliseconds. Which is the timeout for waiting for data or, put differently, a maximum period inactivity between two consecutive data packets. A timeout value of zero is interpreted as an infinite timeout.
timeoutObj.connectionTimeout	number	Determines the timeout in milliseconds until a connection is established. A timeout value of zero is interpreted as an infinite timeout.
timeoutObj.dnsCacheTimeout	number	Sets the maximum length of time that records will be stored in this Cache. A nonpositive value disables this feature

Fulfill returned value : undefined

setRedirectUrls(redirectObj)

Redirecting URL's

Param	Type	Description
redirectObj		Describes redirect object
redirectObj.matchRegex	string	a matching URL regular expression
redirectObj.replace	string	replacement URL

Fulfill returned value : undefined

removeRedirects()

Removes all URL redirection rules currently in effect

Fulfill returned value : undefined

setRetries(numberOfTries)

Setting the retry count

Param	Type	Description
numberOfTries	number	The number of times a method will be retried

Fulfill returned value : undefined

clearDNSCache()

Empties the DNS cache

Fulfill returned value : undefined

setRequestInterception(rule)

Describe your own request interception. See details explanation here

Param	Type	Description
rule	string	a string which determines interceptor rules.

Fulfill returned value : undefined

setResponseInterception(rule)

Describe your own response interception. See details explanation here

Param	Type	Description
rule	string	a string which determines interceptor rules.

Fulfill returned value : undefined

##Controlling methods

getProxiesList()

Receives list of all proxies, which were started.

Fulfill returned value : Array of object that represent proxy info

Fulfill returned value description : It's one object description from array

proxyInfo : object

Object that represent proxy info

Name	Type	Description
port	number	tcp port, where proxy was started

create()

Creates new instance of browserMob Proxy Client

Fulfill returned value : Instance of browserMob Proxy Client

getOwnProxiesList()

Returns own proxy list. Returned proxies belong only to current instance of browserMob Proxy Client

Fulfill returned value : Array of object that represent proxy info

Fulfill returned value description : It's one object description from array

proxyInfo : object

Object that represent proxy info

Name	Type	Description
port	number	tcp port, where proxy was started

closeAllOwnProxies()

Closes all proxies belong to current set of BrowserMob Proxy clients.

Fulfill returned value : undefined

##If you use a some webdriver module for Node.JS

Suppose you are using webdriverio and want change User-Agent header. Let's go

const bmp = require('browsermob-proxy-client-nodejs');
const webdriverio = require('webdriverio');

//helper for starting browser trough our Browser Mob Proxy
const initWithProxy = (seleniumPort, proxyHost, proxyPort) => {
    const options = {
        port : seleniumPort,
        desiredCapabilities: {
            browserName: 'firefox',
            proxy : {
                proxyType : 'manual',
                httpProxy : `${proxyHost}:${proxyPort}`
            }
        }
    };
    return webdriverio.remote(options).init();
};

//connection info (browserMob Proxy and Selenium)
const bmpHost = '127.0.0.1';
const bmpPort = 9090;

const seleniumPort = 4444;

//create browsermob proxy controlling instance
const bmpSet = new bmp(bmpHost, bmpPort);

//rule for change header
const headerName = 'User-Agent';
const headerValue = 'YOUR AWESOME USER';
const interceptionRule = `request.headers().add('${headerName}', '${headerValue}');`;

//here we will be storing client instance
let  browserMobProxyClient = undefined;

//create browsermob client instance
bmpSet.create()
  .then((client) => {
      //Browser Mob Client
      browserMobProxyClient = client;
      //set up our or override current header
      return browserMobProxyClient.setRequestInterception(interceptionRule);
  })
  .then(() => {
    //Create new selenium session
    return initWithProxy(seleniumPort, bmpHost, browserMobProxyClient.port)
    .url(moronHTTPUrl);
  })
  .catch((error) => {/*error handling*/});