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