Mirage

Mirage aids testing of your applications by hosting mock responses so that your applications do not have to talk to real endpoints. It's accessible via HTTP and has a RESTful interface.

Any ideas/improvements or feedback you have are greatly appreciated.

Information on how to use Mirage can be found here.

I hope you find it useful,

Leon

P.s. Mirage runs on Linux,MacOSX and Windows; Rubies 1.9.3+ and JRuby.

gem install mirage 

3.0.0 is now out the following is a description of what's new.

A full description of the functionality is also available in the projects feature files hosted on Relish. A lot of effort has gone in to trying to make these tests readable so if something is missing or unclear drop me a line.

Mirage is now configured using JSON. JSON is also used as the output format for Mirage's other operations.

You can now specify wild cards in the URI matcher. This means that a url such as '/*/world' would match '/hello/world' :)

You can now retrieve all data associated with a request that triggers a response. Previously only the the request body/query string was tracked. Now the full request, including HTTP headers are returned when querying '/requests/template_id'

Now you can specify as many parameter and body matchers as you want. These can be both litteral strings or Regex's

Previously, it was only possible to specify a single matcher and this would be applied against both the querystring and the request body.

You can now also specify matchers against HTTP headers.

Templates are now scored to find the most appropriate template when finding a match for a particular request. Previously the first potential match was returned even if there was a more appropriate template.

Litteral matchers are worth more in the scoring process than regex based ones for example.

Mirage is now accessible via: http://localhost:7001. I.e. 'mirage' has been removed from all resources

e.g. responses are now under http://localhost:7001/responses

Default templates used to be stored in a directory named 'responses'. The term 'response' was the incorrect word to describe what is now called a 'template'. Rather than rename this directory to templates, which is a directory name that may already be in use in your project, the default name for this directory has been changed to 'mirage'.

The old directory name can still be used if you use the client or command line interface to overide where the responses are loaded from

Perhaps the biggest addition to the client. Simply mixin Mirage::Template::Model in to a class, give it a method called body and there you have it... a class that can be used to put objects straight on to Mirage.

• All the methods you find on a standard response can then be used at the class level to set defaults.

• Add builder methods to your class using the builder_methods class method.

Example Usage: (See rdoc for full details)

class UserProfile
  extend Mirage::Template::Model
  
  endpoint '/users'
  http_method :get
  status 200
  content_type 'application/json'
  
  builder_methods :firstname, :lastname, :age
  
  def body
    {firstname: firstname, lastname: lastname, age: age}.to_json
  end
end


Mirage::Client.new.put UserProfile.new.firstname('Joe').lastname('blogs')

The client interface has been overhauled to make it more usable. It supports a couple of different ways of specifying a template to let to specify templates in the style that best suites your code. The block in the examples is executed in the scope of the template object itself so any method in it can be called. The template is also passed in to the block if you prefer to to call the methods on a variable.

Example Usage: (See rdoc for full details)

mirage = Mirage::Client.new
mirage.put('/users') do
  status 201
  http_method :put
  body 'response'
  
  required_body_content << 'Abracadabra'
  required_headers['Header'] = 'value'
  
  delay 1.5
end

# Template Model classes can be customised in exactly the same way

mirage.put UserProfile.new do
  status 404
  required_parameters[:name] = /joe.*/
end

A better UI :) it's on its way though!

Remove the repetition of setting things like the content-type each to time you put a response on to Mirage

Example Usage: (See rdoc for full details)

client = Mirage::Client.new do |defaults|
  defaults.content_type = "text/xml"
  defaults.delay = 0.5
end  

client.put("greeting", "hello") -> template put on to Mirage with a delay of 0.5 seconds and content-type text/xml configured

Nothing, this is a new feature. Let me know if you have any problems :)

The client API now includes the ability to start and stop Mirage locally. No more calling out to the command line.

Example Usage: (See rdoc for full details)

mirage_client = Mirage.start :port => 9001 #with out args start mirage on 7001 by default
Mirage.stop # stops the current running instance as long as only one is running  

Now powered by the mighty Thor, the stop subcommand has been enhanced.
Usage:

mirage stop -> As it always did, stops the current instances of Mirage as long as there is only one running instance.  
mirage stop -p port -> stops Mirage on a given port.    
mirage stop -p port1, port2... -> stop multiple instances of Mirage.  
mirage stop -p all -> stop all instances of mirage.  

You shouldn't have to do anything to move from the last version of Mirage to this one. Let me know if something stops working!