browsermob-proxy

# BrowserMob Proxy BrowserMob Proxy allows you to manipulate HTTP requests and responses, capture HTTP content, and export performance data as a [HAR file](http://www.softwareishard.com/blog/har-12-spec/). BMP works well as a standalone proxy server, but it is especially useful when embedded in Selenium tests. The latest version of BrowserMob Proxy is 2.1.2, powered by [LittleProxy](https://github.com/adamfisk/LittleProxy). If you're running BrowserMob Proxy within a Java application or Selenium test, get started with [Embedded Mode](#getting-started-embedded-mode). If you want to run BMP from the command line as a standalone proxy, start with [Standalone](#getting-started-standalone). ### Getting started: Embedded Mode To use BrowserMob Proxy in your tests or application, add the `browsermob-core` dependency to your pom: ```xml <dependency> <groupId>net.lightbody.bmp</groupId> <artifactId rel='nofollow' onclick='return false;'>browsermob-core</artifactId> <version>2.1.2</version> <scope>test</scope> </dependency> ``` Start the proxy: ```java BrowserMobProxy proxy = new BrowserMobProxyServer(); proxy.start(0); int port = proxy.getPort(); // get the JVM-assigned port // Selenium or HTTP client configuration goes here ``` Then configure your HTTP client to use a proxy running at the specified port. **Using with Selenium?** See the [Using with Selenium](#using-with-selenium) section. ### Getting started: Standalone To run in standalone mode from the command line, first download the latest release from the [releases page](https://github.com/lightbody/browsermob-proxy/releases), or [build the latest from source](#building-the-latest-from-source). Start the REST API: ```sh ./browsermob-proxy -port 8080 ``` Then create a proxy server instance: ```sh curl -X POST http://localhost:8080/proxy {"port":8081} ``` The "port" is the port of the newly-created proxy instance, so configure your HTTP client or web browser to use a proxy on the returned port. For more information on the features available in the REST API, see [the REST API documentation](#rest-api). ## Changes since the 2.1-beta series **The `browsermob-core-littleproxy` module is now `browsermob-core`** After six beta releases, the LittleProxy implementation now supports more features and is more stable than the legacy implementation. To reflect that level of maturity and long-term support, the `browsermob-core` module now uses LittleProxy by default. **Note about Legacy support**: In the 2.1-betas, if you were using the `ProxyServer` or `LegacyProxyServer` classes, use the `browsermob-core-legacy` module in 2.1.0 and higher. *LittleProxy support for `LegacyProxyServer` has moved to `BrowserMobProxyServerLegacyAdapter`*. Using the LittleProxy implementation with the `LegacyProxyServer` interface is still fully supported as a means to help you transition from 2.0.0. Unlike the 2.1-beta series, the `BrowserMobProxyServer` class no longer implements `LegacyProxyServer`; however, the `BrowserMobProxyServerLegacyAdapter` can be used to integrate legacy code with the new LittleProxy interface. You must still use the `browsermob-core-legacy` module when using the LegacyAdapter. ```java LegacyProxyServer proxy = new BrowserMobProxyServerLegacyAdapter(); proxy.setPort(8081); // method only supported by the legacy interface proxy.start(); ``` ## Changes since 2.0.0 The new [BrowserMobProxyServer class](browsermob-core/src/main/java/net/lightbody/bmp/BrowserMobProxyServer.java) has replaced the legacy ProxyServer implementation. The legacy implementation is no longer actively supported; all new code should use `BrowserMobProxyServer`. We highly recommend that existing code migrate to the new implementation. The most important changes from 2.0 are: - [Separate REST API and Embedded Mode modules](#embedded-mode). Include only the functionality you need. - [New BrowserMobProxy interface](browsermob-core/src/main/java/net/lightbody/bmp/BrowserMobProxy.java). The new interface will completely replace the legacy 2.0 ProxyServer contract in version 3.0 and higher. - [LittleProxy support](#littleproxy-support). More stable and more powerful than the legacy Jetty back-end. ### New BrowserMobProxy API BrowserMob Proxy 2.1 includes a [new BrowserMobProxy interface](browsermob-core/src/main/java/net/lightbody/bmp/BrowserMobProxy.java) to interact with BrowserMob Proxy programmatically. The new interface defines the functionality that BrowserMob Proxy will support in future releases (including 3.0+). To ease migration, both the legacy (Jetty-based) ProxyServer class and the new, LittleProxy-powered BrowserMobProxy class support the new BrowserMobProxy interface. We _highly_ recommend migrating existing code to the BrowserMobProxy interface using the `BrowserMobProxyServer` class. ### Using the LittleProxy implementation with 2.0.0 code The legacy interface, implicitly defined by the ProxyServer class, has been extracted into `net.lightbody.bmp.proxy.LegacyProxyServer` and is now officially deprecated. The new LittleProxy-based implementation will implement LegacyProxyServer for all 2.1.x releases. This means you can switch to the LittleProxy-powered implementation with minimal change to existing code ([with the exception of interceptors](#http-request-manipulation)): ```java // With the Jetty-based 2.0.0 release, BMP was created like this: ProxyServer proxyServer = new ProxyServer(); proxyServer.start(); // [...] // To use the LittleProxy-powered 2.1.2 release, simply change to // the LegacyProxyServer interface and the adapter for the new // LittleProxy-based implementation: LegacyProxyServer proxyServer = new BrowserMobProxyServerLegacyAdapter(); proxyServer.start(); // Almost all deprecated 2.0.0 methods are supported by the // new BrowserMobProxyServerLegacyAdapter implementation, so in most cases, // no further code changes are necessary ``` LegacyProxyServer will not be supported after 3.0 is released, so we recommend migrating to the `BrowserMobProxy` interface as soon as possible. The new interface provides additional functionality and is compatible with both the legacy Jetty-based ProxyServer implementation [(with some exceptions)](new-interface-compatibility.md) and the new LittleProxy implementation. If you must continue using the legacy Jetty-based implementation, include the `browsermob-core-legacy` artifact instead of `browsermob-core`. ## Features and Usage The proxy is programmatically controlled via a REST interface or by being embedded directly inside Java-based programs and unit tests. It captures performance data in the [HAR format](http://groups.google.com/group/http-archive-specification). In addition it can actually control HTTP traffic, such as: - blacklisting and whitelisting certain URL patterns - simulating various bandwidth and latency - remapping DNS lookups - flushing DNS caching - controlling DNS and request timeouts - automatic BASIC authorization ### REST API **New in 2.1:** The REST API now supports LittleProxy. As of 2.1.0-beta-3, LittleProxy is the default implementation. (You may specify `--use-littleproxy false` to disable LittleProxy in favor of the legacy Jetty 5-based implementation.) To get started, first start the proxy by running `browsermob-proxy` or `browsermob-proxy.bat` in the bin directory: $ sh browsermob-proxy -port 8080 INFO 05/31 03:12:48 o.b.p.Main - Starting up... 2011-05-30 20:12:49.517:INFO::jetty-7.3.0.v20110203 2011-05-30 20:12:49.689:INFO::started o.e.j.s.ServletContextHandler{/,null} 2011-05-30 20:12:49.820:INFO::Started SelectChannelConnector@0.0.0.0:8080 Once started, there won't be an actual proxy running until you create a new proxy. You can do this by POSTing to /proxy: [~]$ curl -X POST http://localhost:8080/proxy {"port":8081} or optionally specify your own port: [~]$ curl -X POST -d '