com.github.tashoyan.httpspy

Interface HttpSpy

All Known Implementing Classes:

CamelJettyHttpSpy

@NotThreadSafe
public interface HttpSpy

HTTP Spy - a spy for an HTTP server.

HTTP Spy runs on localhost and network port specified by getPort(). It provides HTTP service on the path getPath(). In addition, user can configure parameters like number of servicing threads, etc.

Typical usage is:

 
  HttpSpy httpSpy = ...
  // Start the spy server:
  httpSpy.start();
  // Setup expectations:
  httpSpy
   .expectRequests((new AbstractRequestExpectationListBuilder() {
  
       public void build() {
           expect(request()
                       .withBody(matching(CoreMatchers.containsString("Hello")))
                       .withHeader("h1", 0, matching(CoreMatchers.equalTo("v1")))
                       .withMethod(matching(CoreMatchers.equalTo("POST")))
                       .withPath(matching(CoreMatchers.equalTo("/path/")))
                       .andResponse(response()
                           .withStatus(200)
                           .withBody("OK")
                           .withHeader("h2", "v2")));
           expect(request()
                       .withBody(equalToXml(myXmlSample))
                       .andResponse(response()
                           .withStatus(500)
                           .withBody("Cannot help")
                           .withDelay(TimeUnit.MILLISECONDS, 1000)));
       }
  });
  ...
  // Execute requests...
  ...
  // Verify actual requests again expectations:
  httpSpy.verify();
  // Reset the spy server:
  httpSpy.reset();
  
  // Setup new expectations:
  httpSpy
   .expectRequests((new AbstractRequestExpectationListBuilder() {
  
       public void build() {
           expect(10, request()
                       .andResponse(response()));
       }
  });
  ...
  // Execute more requests...
  ...
  // Verify actual requests again expectations:
  httpSpy.verify();
  // Finally, stop the spy server:
  httpSpy.stop();
  
 

Multiple request expectations can be chained. After expectations are set, one can execute actual requests. HTTP Spy records actual requests for further verification and replies with responses specified via RequestExpectationListBuilder.response(). If a request expectation does not specify a response, then HTTP Spy will response with HTTP 400 status code and empty response body.

TODO Add support for responses based on actual request content. Currently response is based on the sequential number of actual request. When multiple threads concurrently service requests, only one response for all requests makes sense, as it is impossible to set expectations on the order of concurrently arriving requests.

During verification HTTP Spy checks that all request expectations are met. After verification, HTTP Spy can be stopped and all expectations reset. User can continue use this spy server with new request expectations. Note: Client application should not use cached HTTP connections after the spy server restart. A request with an outdated cached connection will fail.

Concurrency notes. All HTTP Spy methods are expected to be called in the only thread - typically main thread that executes a test. However, an implementation has to provide concurrent access to some data inside, for example:

• the list of request expectations;
• the list of recorded actual requests.

Method Summary

Modifier and Type	Method and Description
HttpSpy	expectRequests(RequestExpectationListBuilder builder) Sets request expectation.
String	getHostname() Gets host name.
String	getPath() Gets HTTP path.
int	getPort() Gets network port.
int	getServiceThreadsNumber() Gets number of threads that concurrently service incoming requests.
void	reset() Reset the spy server.
void	setServiceThreadsNumber(int serviceThreadsNumber) Sets threads number to concurrently service incoming requests.
void	start() Start the spy server.
void	stop() Stop the spy server.
void	verify() Verify that expectations are met.

Method Detail

getHostname

String getHostname()

Gets host name.

Returns:

Network host name where server runs.

getPort

int getPort()

Gets network port.

Returns:

Network port where server runs. Should be positive.

getPath

String getPath()

Gets HTTP path.

Returns:

HTTP path where server is available.

setServiceThreadsNumber

void setServiceThreadsNumber(int serviceThreadsNumber)

Sets threads number to concurrently service incoming requests.

This method guarantees that at least the specified number of threads will be available to service client requests. Depending on server implementation, the real number of servicing threads may be greater.

Parameters:

serviceThreadsNumber - Number of threads that service requests.

Throws:

IllegalArgumentException - threadsNumber is not positive.

IllegalStateException - The spy server has already started.

getServiceThreadsNumber

int getServiceThreadsNumber()

Gets number of threads that concurrently service incoming requests.

Returns:

Number of threads.

expectRequests

HttpSpy expectRequests(RequestExpectationListBuilder builder)

Sets request expectation.

Parameters:

builder - Builder for the list of request expectations.

Returns:

This object.

Throws:

IllegalArgumentException - builder is null, or builder has lists of different sizes for request expectations and responses.

start

void start()

Start the spy server.

After start the spy server services client requests.

Throws:

IllegalStateException - Already started.

verify

void verify()

Verify that expectations are met.

reset

void reset()

Reset the spy server.

The spy server resets all request expectations along with actual requests received and responses.

stop

void stop()

Stop the spy server.

The spy server stops servicing client requests and frees network resources. The spy server also resets itself.

See Also:

reset()