Quick start

NOTE: This documentation applies to version 2 of mirage. If you are Version 3 stick to the Readme and I will update this very soon!

5 minute Quick Start

In the first 2 minutes we are going to:

• run Mirage
• Use the Mirage ruby client to set a response
• Use a browser to get that response back
• Sit and wait for the second minute to go by...

In the next 2 minutes we will use the Mirage client to

• set a response with a pattern
• check what Mirage recorded when you hit it
• pat self on back

In the last minute we will take a quick look at response templates. (Ok that might take two minutes)

###Exercise 1:
Start the clock

1. First we need to get Mirage running, do this by opening a command prompt and running:
   mirage start
   Mirage is now running, see for yourself by going to the Mirage home page: http://localhost:7001/mirage

2. Next, lets get straight to it by setting a response on Mirage. In a file called 'mirage_practise.rb' type the following:
   require 'rubygems'
require 'mirage/client'
client = Mirage::Client.new
puts client.put('greeting', 'Hello from Mirage!')

3. Run it! ruby mirage_practise.rb
   The number 1 just appeared didn't it? This is the response id. The response id is unique and one is given to every response that is set on to Mirage. Response ids are used to make call backs to Mirage to do various things. We will be using them later.

4. Now lets get the response back. Use your browser to go to: http://localhost:7001/mirage/responses/greeting. You should now be seeing 'Hello from Mirage!'. What just happened? Well you hit Mirage on the end point you had just set and the response that you primed has been sent back to you. Simples :)

5. Well that was so quick that we must be ahead of schedule. Sit back and watch the second hand take a trip around the clock (or just carry on).

###Exercise 2:

1. In a file called 'mirage_practise2.rb' type the following:
   require 'rubygems'
require 'mirage'
client = Mirage::Client.new
response_id = client.put('greeting', 'Hi Joe') do |response|
response.pattern = 'Joe'
end

   This script is going to create a new client and set a response for greeting that will only be returned if the request contains the word 'Joe' in its query string or body. On setting this response the set method returns the unique id assigned by Mirage to this response which we are storing in the variable 'response_id'.

2. Run it

  ruby mirage_practise2.rb   

Go to http://localhost:7001/mirage and you should see the response that we set in exercise 1 and your new response for Joe.  

3. The Mirage home page is designed to let you look at the responses you set and to look request that triggered it. Click the response for Joe you will see 'Hi Joe'. As you can see from the address in your browser, clicking this link is the same as going to: http://localhost:7001/mirage/templates/2. The number 2 at the end of this URL is the response id that was given to our response, this is the value that will have been set in the response_id variable in our script.

4. Lets get the response back. Add the following to mirage_practise2.rb
   puts open('http://localhost:7001/mirage/responses/greeting?name=Joe').read

   This line is going to print the result of using the client to get the greeting response and sending 'Hello my name is Joe' in the request body. Re-run the script and you should see 'Hi Joe'. Did you? You did? well done :)

5. Earlier I mentioned that the you could use the Mirage home page to look at the last request that triggered a particular response. Click the 'track' link next to the response for Joe and see that the request sent by the client has been stored. In the browser address bar we can see that URL for doing this is: http://localhost:7001/mirage/requests/2. Again, we have the number 2 at the end of this URL because it is the unique id of our response.

6. Now let's use the client to do the same thing. In order to do this we need to use the unique id that we assigned to the response_id variable. In mirage_practise2.rb type the following:
   puts "Mirage recorded: #{client.request(response_id)}"

   Re-run the script and you should see 'Mirage recorded: Hello my name is Joe'. Well did you?

7. Exercise 2 is done with, Commence back patting.

###Exercise 3:

1. Mirage lets you templatize responses so that you can replace bits of it for things found in the request. If what you are looking for is a request parameter then simply put ${parameter_name} into the relevant location in your response. If what you are looking for is going to be in the request body then you can use a regular expression. Lets have a go. In mirage_practise2.rb put the following:
   clever_response = 'Hi ${name}, how are you?'
client.put('clever_greeting', clever_response)
puts open('http://localhost:7001/mirage/responses/clever_greeting?name=Fred').read

   Run the script and you should see 'Hi Fred, how are you?'. You can also set your templates up to pull values from the request body as well. Take a look here for more details.

And there you have it, that's it, the end, you've done it and well done you!