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

Fulfill returned value : Object that represent HAR

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

Starts a new page on the existing HAR

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

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

setBlackList(httpCodeStatus, regexp, [methodsRegexp])

Setup url to black list

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

LimitsSetterObject : object

Object for setting up limits of BrowserMob Proxy

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

setHeaders(headers)

Set and override HTTP Request headers

Fulfill returned value : undefined

overrideDNS(dns)

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

Fulfill returned value : undefined

setAutoAuthentication(auth, domain)

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

Fulfill returned value : undefined

setWait(waitObject)

Wait till all request are being made

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.

Fulfill returned value : undefined

setRedirectUrls(redirectObj)

Redirecting URL's

Fulfill returned value : undefined

removeRedirects()

Removes all URL redirection rules currently in effect

Fulfill returned value : undefined

setRetries(numberOfTries)

Setting the retry count

Fulfill returned value : undefined

clearDNSCache()

Empties the DNS cache

Fulfill returned value : undefined

setRequestInterception(rule)

Describe your own request interception. See details explanation here

Fulfill returned value : undefined

setResponseInterception(rule)

Describe your own response interception. See details explanation here

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

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

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*/});