|
| 1 | +BrowserMob Proxy |
| 2 | +================ |
| 3 | + |
| 4 | +BrowserMob Proxy is a simple utility that makes it easy to capture performance data from browsers, typically written using automation toolkits such as Selenium and Watir. |
| 5 | + |
| 6 | +Features |
| 7 | +-------- |
| 8 | + |
| 9 | +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 the [HAR format](http://groups.google.com/group/http-archive-specification). It addition it also can actually control HTTP traffic, such as: |
| 10 | + |
| 11 | + - blacklisting and whitelisting certain URL patterns |
| 12 | + - simulating various bandwidth and latency |
| 13 | + - remapping DNS lookups |
| 14 | + - flushing DNS caching |
| 15 | + - controlling DNS and request timeouts |
| 16 | + - automatic BASIC authorization |
| 17 | + |
| 18 | +REST API |
| 19 | +-------- |
| 20 | + |
| 21 | +To get started, first start the proxy by running `browsermob-proxy` or `browsermob-proxy.bat` in the bin directory: |
| 22 | + |
| 23 | + $ sh browsermob-proxy -port 9090 |
| 24 | + INFO 05/31 03:12:48 o.b.p.Main - Starting up... |
| 25 | + 2011-05-30 20:12:49.517:INFO::jetty-7.3.0.v20110203 |
| 26 | + 2011-05-30 20:12:49.689:INFO::started o.e.j.s.ServletContextHandler{/,null} |
| 27 | + 2011-05-30 20:12:49.820:INFO::Started [email protected]:9090 |
| 28 | + |
| 29 | +Once started, there won't be an actual proxy running until you create a new proxy. You can do this by POSTing to /proxy: |
| 30 | + |
| 31 | + [~]$ curl -X POST http://localhost:9090/proxy |
| 32 | + {"port":9091} |
| 33 | + |
| 34 | +Once that is done, a new proxy will be available on the port returned. All you have to do is point a browser to that proxy on that port. The following additional APIs will then be available: |
| 35 | + |
| 36 | + - DELETE /proxy/port - shuts down the proxy and closed the port |
| 37 | + - GET /proxy/port/har - returns the JSON/HAR content representing all the HTTP traffic passed through the proxy |
| 38 | + |
| 39 | +*TODO*: Other REST APIs supporting all the BrowserMob Proxy features will be added soon. |
| 40 | + |
| 41 | +Embedded Mode |
| 42 | +------------- |
| 43 | + |
| 44 | +If you're using Java and Selenium, the easiest way to get started is to embed the project directly in your test. First, you'll need to make sure that all the dependencies are imported in to the project. You can find them in the *lib* directory. Or, if you're using Maven, you can add this to your pom: |
| 45 | + |
| 46 | + <dependency> |
| 47 | + <groupId>org.browsermob</groupId> |
| 48 | + <artifactId>browsermob-proxy</artifactId> |
| 49 | + <version>2.0-SNAPSHOT</version> |
| 50 | + </dependency> |
| 51 | + |
| 52 | +*TODO*: We haven't yet released the artifacts to Maven's central repository, but we are working on it. The above will work as soon as it's ready. |
| 53 | + |
| 54 | +Once done, you can start a proxy using `org.browsermob.proxy.ProxyServer`: |
| 55 | + |
| 56 | + ProxyServer server = new ProxyServer(9090); |
| 57 | + server.start(); |
| 58 | + |
| 59 | +This class supports every feature that the proxy supports. In fact, the REST API is a subset of the methods exposed here, so new features will show up here before they show up in the REST API. Consult the Javadocs for the full API. |
| 60 | + |
| 61 | +Using With Selenium |
| 62 | +------------------- |
| 63 | + |
| 64 | +You can use the REST API with Selenium however you want. But if you're writing your tests in Java and using Selenium 2, this is the easiest way to use it: |
| 65 | + |
| 66 | + // start the proxy |
| 67 | + ProxyServer server = new ProxyServer(4444); |
| 68 | + server.start(); |
| 69 | + |
| 70 | + // get the Selenium proxy object |
| 71 | + Proxy proxy = server.seleniumProxy(); |
| 72 | + |
| 73 | + // configure it as a desired capability |
| 74 | + DesiredCapabilities capabilities = new DesiredCapabilities(); |
| 75 | + capabilities.setCapability(CapabilityType.PROXY, proxy); |
| 76 | + |
| 77 | + // start the browser up |
| 78 | + WebDriver driver = new FirefoxDriver(capabilities); |
| 79 | + |
| 80 | + // create a new HAR with the label "yahoo.com" |
| 81 | + server.newHar("yahoo.com"); |
| 82 | + |
| 83 | + // open yahoo.com |
| 84 | + driver.get("http://yahoo.com"); |
| 85 | + |
| 86 | + // get the HAR data |
| 87 | + Har har = server.getHar(); |
| 88 | + |
| 89 | + |
| 90 | +HTTP Request Manipulation |
| 91 | +------------------- |
| 92 | + |
| 93 | +While not yet available via the REST interface, you can manipulate the requests like so: |
| 94 | + |
| 95 | + server.addRequestInterceptor(new HttpRequestInterceptor() { |
| 96 | + @Override |
| 97 | + public void process(HttpRequest request, HttpContext context) throws HttpException, IOException { |
| 98 | + request.removeHeaders("User-Agent"); |
| 99 | + request.addHeader("User-Agent", "Bananabot/1.0"); |
| 100 | + } |
| 101 | + }); |
| 102 | + |
| 103 | +The interceptor is the type `org.apache.http.HttpRequestInterceptor`, which is part of the [Apache HTTP Client](http://hc.apache.org/httpcomponents-client-ga/) project. You can consult the API docs for the full set of options available to you in the interceptor. |
| 104 | + |
| 105 | +We will soon be adding support for this advanced capability in the REST interface as well, using JavaScript snippets that can be posted as the interceptor code. |
| 106 | + |
| 107 | +SSL Support |
| 108 | +----------- |
| 109 | + |
| 110 | +While the proxy supports SSL, it requires that a Certificate Authority be installed in to the browser. This allows the browser to trust all the SSL traffic coming from the proxy, which will be proxied using a classic man-in-the-middle technique. IT IS CRITICAL THAT YOU NOT INSTALL THIS CERTIFICATE AUTHORITY ON A BROWSER THAT IS USED FOR ANYTHING OTHER THAN TESTING. |
| 111 | + |
| 112 | +If you're doing testing with Selenium, you'll want to make sure that the browser profile that gets set up by Selenium not only has the proxy configured, but also has the CA installed. Unfortuantely, there is no API for doing this in Selenium, so you'll have to solve it uniquely for each browser type. We hope to make this easier in upcoming releases. |
0 commit comments