mirage

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.

Installation

gem install mirage 

What's New?

3.0.0

---

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.

What's new in the Server:

1: Mirage uses JSON as its communucations medium

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

2: Wildcards are now supported in the URI.

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

3: Full Request Data now tracked

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'

4. Parameters and body content matchers are now specified seperately

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.

5. HTTP Header matchers

You can now also specify matchers against HTTP headers.

6. More advanced template resolution.

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.

7. The url has changed

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

8. Default responses directory renamed to mirage

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

What's new in the Client:

1. Template Models

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')

Client interface

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

What you don't get

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

2.4.0

---

What do I get?

1: Configure your client with defaults for each of your responses

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

What do I have to do to upgrade?

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

2.3.0

---

What do I get?

1: Run more than one instance of Mirage per machine.

2: Programmatic interface for starting and stopping Mirage

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  

3: Updated command line interface

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.  

What do I have to do to upgrade?

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!