service_mock 0.2 → 0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5fc036750c9ea274d089cab6ba71e1216884bda1
-  data.tar.gz: 8760fda0af80a2d062fc25aab4d74e07f5ee8b6f
+  metadata.gz: d7fdc7bccb713c57d4015364a05509acc4fbd6c0
+  data.tar.gz: b2b8020335b3102cba37d8efd6b8c21baa4b8949
 SHA512:
-  metadata.gz: e4ec01c860396bb89a9e32311b78cc3831cdb8de0c480eff8f17d0948d5388570fa2c3a5426461daa0139d70393e72c39bcd1148e5c3c1a0ff2ee562865f9f83
-  data.tar.gz: 0f48213bb676c2fca31371dac6de2b784e5ce01ac2ddb7328f7a6547e1e77f1ef8ce2b299bdb65c22c33954328b2044fd18aedfecfaca968d416f4119cd7e46d
+  metadata.gz: 092ba99d6dd44fd75c64291bd163ea4a1a56b60bbba67e24ecec98b63470d12e79458ac57634bb596247488334bd9cdbfcefa07530261e9d5e396f1027f22513
+  data.tar.gz: 56b6032dc77a3ec75c6c7bf32c764b465911f1fd1bae10906b935d03b71c525839a0af154ce449ea7cdaee238299141ccb6fc03a4cc5a3519f409ec337afb824

data/ChangeLog

@@ -1,3 +1,7 @@
+=== Release 0.3 / 2016-06-27
+* Removed the config directory from the gem thereby reducing the size
+* Added documentation
+
 === Release 0.2 / 2016-06-16
 * Reorganized the imports to make it easier to utilize the rake tasks
 

data/README.md

@@ -1,8 +1,210 @@
 # ServiceMock
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/service_mock`. To experiment with that code, run `bin/console` for an interactive prompt.
+ServiceMock is a Ruby gem that provides a wrapper over the [WireMock](http://wiremock.org)
+library.  The gem provides the ability to perform many actions on a WireMock instance
+including starting, stopping, and several ways to stub out calls.  It is highly
+recommended that you take the time to read the WireMock documentation and understand
+the how the library works.
 
+This gem can be used to help you virtualize services for your tests.  For example, if you
+are unable to achieve effective test data management with the backend systems you can
+use this gem (with WireMock) to simulate (or mock) the services while controlling the
+data that is returned.
 
+ServiceMock also provides two built-in rake task that can be used to start and stop an
+instance of WireMock.  The rake task need to be executed on the machine that the server
+will run - there is no ability for remote start and stop.
+
+## Usage
+
+### Using the API
+
+All interaction with the WireMock services is via calls to an instance of
+`ServiceMock::Server`.  On your local machine you can `start` and `stop` an
+instance of the server process.  On local and remove machines you can also
+use one of several methods to create stubs (specify request/response data)
+as well as tell the server to `save` in-memory stubs, `reset_mappings` to
+remove all of the stubs you have provided and `reset_all` which completely
+clears all mappings and files that you have setup for WireMock to return
+as your system under test interacts with it.
+
+When you create your instance of `ServiceMock::Server` you need to provide
+some information.  The required piece of data is the version of WireMock
+you will be using.  If the name of the WireMock jar file you will be using
+is `wiremock-standalone-2.0.10-beta.jar` then the version you should provide
+is `standalone-2.0.10-beta`.  In other words, take off the initial `wiremock-`
+and the trailing `.jar` and this is your version.  The other optional value
+you can provide is the working directory - the location where the WireMock
+jar is located.  By default the working directory is set to `config/mocks`.
+You will initialize the server like this:
+
+```ruby
+# uses default working directory
+my_server = ServiceMock::Server.new('standalone-2.0.10-beta')
+ 
+# or this sets the working directory
+my_server = ServiceMock::Server.new('standalone-2.0.10-beta', '/path/to/jar')
+```
+
+There are two additional values (inherit_io and wait_for_process) that 
+are defaulted to `false`.  If set to `true`, `inherit_io` will cause our
+instance to 'inherit' the standard out and in for the running WireMock
+process.  When `wait_for_process` is set to `true` it will cause the
+call to `start` to block until the underlying WireMock process exits.
+These values can be overwritten in the call to `start` as described below.
+
+#### Starting the Server
+
+You start the server by calling the `start` method but it doesn't end there.
+There are a large number of parameters you can set to control the way that
+WireMock runs.  These are set via a block that is passed to the `start` method.
+
+```ruby
+my_server.start do |server|
+  server.port = 8081
+  server.record_mappings = true
+  server.root_dir = /path/to/root
+  server.verbose = true
+end
+```
+
+The values that can be set are:
+
+| value  | description  |
+|--------|--------------|
+| port  | The port to listen on for http request |
+| https_port | The port to listen on for https request |
+| https_keystore | Path to the keystore file containing an SSL certificate to use with https |
+| keystore_password | Password to the keystore if something other than "password" |
+| https_truststore | Path to a keystore file containing client certificates |
+| truststore_password | Optional password to the trust store.  Defaults to "password" if not specified |
+| https_reuire_client_cert | Force clients to authenticate with a client certificate |
+| verbose | print verbose output from the running process. Values are `true` or `false` |
+| root_dir | Sets the root directory under which `mappings` and `__files` reside.  This defaults to the current directory |
+| record_mappings | Record incoming requests as stub mappings |
+| match_headers | When in record mode, capture request headers with the keys specified |
+| proxy_all | proxy all requests through to another URL. Typically used in conjunction with `record_mappings` such that a session on another service can be recorded |
+| preserve_host_header | When in proxy mode, it passes the Host header as it comes from the client through to the proxied service |
+| proxy_via | When proxying requests, route via another proxy server. Useful when inside a corporate network that only permits internet access via an opaque proxy |
+| enable_browser_proxy | Run as a browser proxy |
+| no_request_journal | Disable the request journal, which records incoming requests for later verification |
+| max_request_journal_entries | Sets maximum number of entries in request journal.  When this limit is reached oldest entries will be discarded |
+
+In addition, as mentioned before, you can set the `inherit_io` and `wait_for_process` options
+to `true` inside of the block.
+
+### Stubbing service calls
+
+Please read the [WireMock stubbing](http://wiremock.org/stubbing.html) 
+documentation so you understand the message structures that are used.
+It is very important that you understand this first. Those details will
+not be covered here.
+
+There are three methods that can be used to stub services.  
+
+```ruby
+my_server.stub(string_containing_json_stub)
+
+my_server.stub_with_file(file_containing_json_stub)
+
+my_server.stub_with_erb(erbfile_containing_json_stub, hash_with_values)
+```
+
+The first method is pretty self-explanatory.  You simply pass a string
+that contains the json stub and the server contacts the running server
+process and sets it up.  The second method takes a full path to a file 
+that contains the json stub.
+
+The third method is where things get interesting.  It allows you to provide
+an [ERB](https://docs.puppet.com/puppet/latest/reference/lang_template_erb.html)
+file that will become your json stub.  ERB stands for Embedded Ruby and
+allows you to insert Ruby code inside any type of file - including json.
+Using this ability to allows us to build templates of the service messages.
+It is quite common to mock a service many times and while the structure
+is the same with each mock the data supplied and returned is different.
+Using templates allows us to simply write the template once and then 
+supply the data for each mock.
+
+The third method takes the full path to an erb file that contains the
+json stub and a `Hash` that contains `key=>value` combinations that will
+fill in the data elements in the template.
+
+If you set the port value when you started the server you will need to 
+do the same via a block when stubbing.  
+
+```ruby
+my_server.stub(string_containing_json_stub) do |server|
+  server.port = 8081
+end
+```
+
+### Other capabilities
+
+There are additional methods that provide access to the running WireMock
+server. If you changed the port during startup then you will need to do
+so here as well.  The methods are:
+
+```ruby
+my_server.stop
+```
+
+Stops the running WireMock server if it is running locally.
+ 
+```ruby
+my_server.save
+```
+ 
+Writes all of the stubs to disk so they are available the next time
+the server starts.
+
+```ruby
+my_server.reset_mappings
+```
+
+Removes the stubs that have been created since WireMock was started.
+
+```ruby
+my_server.reset_all
+```
+
+Removes all stubs, file based stubs, and request logs from the WireMock
+server.
+
+### Using the Rake Tasks
+
+There are two rake tasks that are provided to make it easy to start and
+stop the WireMock server when working locally.  You can simply add
+the following to your `Rakefile`:
+
+```ruby
+require 'service_mock'
+require 'service_mock/rake/rake_tasks'
+
+WIREMOCK_VERSION = 'standalone-2.0.10-beta'
+ServiceMock::Rake::StartServerTask.new(:start_server, WIREMOCK_VERSION)
+ServiceMock::Rake::StopServerTask.new(:stop_server, WIREMOCK_VERSION)
+```
+
+Any parameter that can be passed to the `start` method can also be passed
+to the rake task.
+
+```ruby
+ServiceMock::Rake::StartServerTask.new(:start_server, WIREMOCK_VERSION) do |server|
+  server.port = 8081
+  server.record_mappings = true
+  server.root_dir = /path/to/root
+  server.verbose = true
+end
+```
+
+If you set the port in the start task then you will also need to set it
+in the stop task.
+
+```ruby
+ServiceMock::Rake::StopServerTask.new(:stop_server, WIREMOCK_VERSION) do |server|
+  server.port = 8081
+end
+```
 
 ## Installation
 
@@ -20,17 +222,20 @@ Or install it yourself as:
 
     $ gem install service_mock
 
-## Usage
-
-
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. 
+Then, run `rake spec` to run the tests. You can also run `bin/console` 
+for an interactive prompt that will allow you to experiment.
+
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/service_mock. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at 
+https://github.com/cheezy/service_mock. This project is intended to 
+be a safe, welcoming space for collaboration, and contributors are 
+expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) 
+code of conduct.
 

data/lib/service_mock/server.rb

@@ -4,6 +4,40 @@ require 'erb'
 require 'ostruct'
 require 'service_mock/render_subtemplate'
 
+#
+# All interaction with the WireMock services is via calls to an instance of
+# +ServiceMock::Server+.  On your local machine you can +start+ and +stop+ an
+# instance of the server process.  On local and remove machines you can also
+# use one of several methods to create stubs (specify request/response data)
+# as well as tell the server to +save+ in-memory stubs, +reset_mappings+ to
+# remove all of the stubs you have provided and +reset_all+ which completely
+# clears all mappings and files that you have setup for WireMock to return
+# as your system under test interacts with it.
+#
+# When you create your instance of +ServiceMock::Server+ you need to provide
+# some information.  The required piece of data is the version of WireMock
+# you will be using.  If the name of the WireMock jar file you will be using
+# is +wiremock-standalone-2.0.10-beta.jar+ then the version you should provide
+# is +standalone-2.0.10-beta+.  In other words, take off the initial +wiremock-+
+# and the trailing +.jar+ and this is your version.  The other optional value
+# you can provide is the working directory - the location where the WireMock
+# jar is located.  By default the working directory is set to +config/mocks+.
+# You will initialize the server like this:
+#
+#   # uses default working directory
+#   my_server = ServiceMock::Server.new('standalone-2.0.10-beta')
+#
+#   # or this sets the working directory
+#   my_server = ServiceMock::Server.new('standalone-2.0.10-beta', '/path/to/jar')
+#
+# There are two additional values (inherit_io and wait_for_process) that
+# are defaulted to +false+.  If set to +true+, +inherit_io+ will cause our
+# instance to 'inherit' the standard out and in for the running WireMock
+# process.  When +wait_for_process+ is set to +true+ it will cause the
+# call to +start+ to block until the underlying WireMock process exits.
+# These values can be overwritten in the call to +start+.
+#
+
 module ServiceMock
   class Server
     include CommandLineOptions
@@ -18,27 +52,75 @@ module ServiceMock
       self.wait_for_process = false
     end
 
+    #
+    # You start the server by calling the `start` method but it doesn't end there.
+    # There are a large number of parameters you can set to control the way that
+    # WireMock runs.  These are set via a block that is passed to the `start` method.
+    #
+    #   my_server.start do |server|
+    #     server.port = 8081
+    #     server.record_mappings = true
+    #     server.root_dir = /path/to/root
+    #     server.verbose = true
+    #   end
+    #
+    # The values that can be set are:
+    #
+    # [port]  The port to listen on for http request
+    # [https_port] The port to listen on for https request
+    # [https_keystore] Path to the keystore file containing an SSL certificate to use with https
+    # [keystore_password] Password to the keystore if something other than "password"
+    # [https_truststore] Path to a keystore file containing client certificates
+    # [truststore_password] Optional password to the trust store.  Defaults to "password" if not specified
+    # [https_reuire_client_cert] Force clients to authenticate with a client certificate
+    # [verbose] print verbose output from the running process. Values are +true+ or +false+
+    # [root_dir] Sets the root directory under which +mappings+ and +__files+ reside.  This defaults to the current directory
+    # [record_mappings] Record incoming requests as stub mappings
+    # [match_headers] When in record mode, capture request headers with the keys specified
+    # [proxy_all] proxy all requests through to another URL. Typically used in conjunction with _record_mappings_ such that a session on another service can be recorded
+    # [preserve_host_header] When in proxy mode, it passes the Host header as it comes from the client through to the proxied service
+    # [proxy_via] When proxying requests, route via another proxy server. Useful when inside a corporate network that only permits internet access via an opaque proxy
+    # [enable_browser_proxy] Run as a browser proxy
+    # [no_request_journal] Disable the request journal, which records incoming requests for later verification
+    # [max_request_journal_entries] Sets maximum number of entries in request journal.  When this limit is reached oldest entries will be discarded
+    #
+    # In addition, as mentioned before, you can set the +inherit_io+ and +wait_for_process+ options
+    # to +true+ inside of the block.
+    #
     def start
       yield self if block_given?
       start_process
     end
 
+    #
+    # Stops the running WireMock server if it is running locally.
+    #
     def stop
       yield self if block_given?
       http.post('/__admin/shutdown', '')
     end
 
+    #
+    # Create a stub based on the value provided.
+    #
     def stub(message)
       yield self if block_given?
       http.post('/__admin/mappings/new', message)
     end
 
+    #
+    # Create a stub using the information in the provided filename.
+    #
     def stub_with_file(filename)
       yield self if block_given?
       content = File.open(filename, 'rb') {|file| file.read}
       stub(content)
     end
 
+    #
+    # Create a stub using the erb template provided.  The +Hash+ second
+    # parameter contains the values to be inserted into the +ERB+.
+    #
     def stub_with_erb(filename, hsh)
       yield self if block_given?
       template = File.open(filename, 'rb') {|file| file.read}
@@ -46,16 +128,27 @@ module ServiceMock
       stub(erb_content)
     end
 
+    #
+    # Writes all of the stubs to disk so they are available the next time
+    # the server starts.
+    #
     def save
       yield self if block_given?
       http.post('/__admin/mappings/save', '')
     end
 
+    #
+    # Removes the stubs that have been created since WireMock was started.
+    #
     def reset_mappings
       yield self if block_given?
       http.post('/__admin/mappings/reset', '')
     end
 
+    #
+    # Removes all stubs, file based stubs, and request logs from the WireMock
+    # server.
+    #
     def reset_all
       yield self if block_given?
       http.post('/__admin/reset', '')
@@ -63,7 +156,6 @@ module ServiceMock
 
     private
 
-
     def data_binding(hsh)
       OpenStruct.include ::ServiceMock::RenderSubTemplate
       OpenStruct.new(hsh).instance_eval { binding }

data/lib/service_mock/version.rb

@@ -1,3 +1,3 @@
 module ServiceMock
-  VERSION = "0.2"
+  VERSION = "0.3"
 end

data/lib/service_mock.rb

@@ -4,6 +4,22 @@ require 'service_mock/server'
 require 'service_mock/render_subtemplate'
 require 'service_mock/rake/rake_tasks'
 
+#
+# ServiceMock is a Ruby gem that provides a wrapper over the [WireMock](http://wiremock.org)
+# library.  The gem provides the ability to perform many actions on a WireMock instance
+# including starting, stopping, and several ways to stub out calls.  It is highly
+# recommended that you take the time to read the WireMock documentation and understand
+#the how the library works.
+#
+# This gem can be used to help you virtualize services for your tests.  For example, if you
+# are unable to achieve effective test data management with the backend systems you can
+# use this gem (with WireMock) to simulate (or mock) the services while controlling the
+# data that is returned.
+#
+# ServiceMock also provides two built-in rake task that can be used to start and stop an
+# instance of WireMock.  The rake task need to be executed on the machine that the server
+# will run - there is no ability for remote start and stop.
+#
 module ServiceMock
 
 end

data/service_mock.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/cheezy/service_mock"
 
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|config)/}) }
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: service_mock
 version: !ruby/object:Gem::Version
-  version: '0.2'
+  version: '0.3'
 platform: ruby
 authors:
 - Jeffrey S. Morgan
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-06-16 00:00:00.000000000 Z
+date: 2016-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: childprocess
@@ -85,8 +85,6 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
-- config/mocks/wiremock-1.58-standalone.jar
-- config/mocks/wiremock-standalone-2.0.10-beta.jar
 - lib/service_mock.rb
 - lib/service_mock/command_line_options.rb
 - lib/service_mock/rake/base_task.rb