realweb

= RealWeb

Boot a rack app to use as a real endpoint for tests.

== Why?

We found this very useful for gems that hit an API. Rather than mocking out all the URIs with FakeWeb, you can just write a sample rack app that looks like the API you're expecting. It's not uncommon to have 5+ different small rack apps that reflect different behaviors of your remote server. We created things like broken.ru that always responds with 500s, forbidden.ru that is always 403, and healthy.ru that always returns happy path responses.

Another useful way to use this is with paired client/server libraries. We use RealWeb to boot up the real rack server and hit it with the client from within the specs.

== Usage

# fixtures/config.ru
run lambda { |env| [200, { 'Content-Type' => 'application/json' }, '[{thing: 1}, {thing: 2}]'] }

# thing_api_spec.rb
describe MyLibrary do
  before(:each) do
    @server = RealWeb.start_server("fixtures/config.ru")
  end

  after(:each) do
    @server.stop
  end

  it "runs an action that would normally hit the api" do
    MyLibrary.get_list_of_things_from_api(@server.base_uri).should_not be_empty
  end
end

RealWeb.start_server boots the given config.ru in a fork. When you call stop on the server object, the server process is killed.

The example above is an extremely simplistic rack app. We usually use Sinatra apps for RealWeb backends.

== Threaded Server

You can specifically boot a server in a thread instead of a fork with start_server_in_thread. This can allow you to manipulate the state of the RealWeb server. Use at your own risk. This can lead to harder to comprehend tests. Actually reaching behind a "mock" api to change it's behavior during the test run is not ideal.