faraday-hot_mock 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bb26f02c836add4b2e94acfb00997c4d4b5df893240d05b664c357a361b2bc7
-  data.tar.gz: e302adfe01517cc6cafa86bc569652e5890a163776510b665502506a45a79eb4
+  metadata.gz: 25e4f2498095f7292d5e11855332f571948d41f93e16afb2b7d3e3f29bebd243
+  data.tar.gz: d0a18131c29b31575ae29064f995c0eca098305ea776768fec305ef758122009
 SHA512:
-  metadata.gz: 5dd69fdff2fa19a114557e6c307a7be3d45ae3acc36778c2aefe0fa84966441479336b9286743511424e85ae62a3a50b8937234311e30dd2f97786f396a2cdaa
-  data.tar.gz: 7e75041ce558508cfd07317e6c537b5b14a520c76f32abade2c39360d7136a053cf0b859013a104ea10528866bcbf62fd444fcfb6a7fdab4a3b9c31a046f6f75
+  metadata.gz: be6477e0289f117c0bbdd6e0b8d90d0b3bbe6897c51d61569d34b4bca8dffce90b34fce352e5aa9b2002acb2190373ce20ada2032ea629aceb9da4dedf7c3297
+  data.tar.gz: d6f897cc2f27bf7a4813968018acbbbcdedebb953790a19efa75544c6b51eaf85f1a3289cbe546f2d7443c5407a079a16727915589d890f737428ffa1d82aa63

data/README.md

@@ -81,14 +81,69 @@ It can also be a terrible idea if your mocks are designed for your specific need
 
 It's up to you and your team what makes sense.
 
-In most cases, it makes sense to check in the mocks for the test environment, and ignore all the rest so in most cases you should add to your `.gitignore`:
+In most cases, it makes sense to not check in the mocks for any environment, so in most cases you should add to your `.gitignore`:
 
 ```
 # Ignore Faraday HotMocks except in test env
 lib/faraday/mocks/**
-!lib/faraday/mocks/test
 ```
 
+If you're using scenarios, however, it's probably useful to check in any environment directory that has scenarios since they're only activated when a scenario is directly selected.
+
+### Scenarios
+
+You can use directories to conditionally group mocks. For example, you might want a "success" scenario and a "failure" scenario.
+
+To do that, simply create the `/scenarios/success` and `/scenarios/failure` subdirectories within `lib/faraday/mocks/#{Rails.env}/`, and place the appropriate mock files in each, probably with the same endpoints but with different responses.
+
+Then call `Faraday::HotMock.scenario = :success` or `Faraday::HotMock.scenario = :failure` to switch between them.
+
+When a scenario is active, only mocks in that scenario directory will be considered. If no matching mock is found in that scenario, then the real request will be made.
+
+To use the mocks not in the `scenarios` directory again, simply set `Faraday::HotMock.scenario = nil`.
+
+### VCR Mode
+
+VCR mode basically calls `Faraday::HotMock.record` on all requests made until it's turned off. You can start it with:
+
+```ruby
+Faraday::HotMock.vcr = true
+```
+
+Just like using `Faraday::HotMock.record` individually, these mocks are recorded to the main default file (`Faraday::HotMock.hot_mock_file`)
+
+You can also record directly into a scenario, which will create the scenario directory structure, switch the current scenario and begin recording responses. This will continue until you set `Faraday::HotMock.vcr` to `false` or another scenario name.
+
+```ruby
+Faraday::HotMock.vcr = :new_scenario
+```
+
+> NOTE: VCR Mode does not overwrite previously recorded mocks
+
+### Testing
+
+In tests, you can certainly use a mocking library of choice. In many cases, that might be easier. This is because Faraday::HotMock is built for quick iteration using runtime-loaded YAML files, which isn't needed in tests.
+
+If instead you want to use Faraday::HotMock, you can create mocked responses by hand, or use `Faraday::HotMock.mock!` to define mocks in a very similar way to other mocking libraries (similar to `stub_request` in WebMock, for example).
+
+The most basic setup would be:
+
+- Call `Faraday::HotMock.enable!` in your test setup
+- Call `Faraday::HotMock.disable!` in your test teardown
+- In a given test/spec or in a method, call `Faraday::HotMock.mock!(method: [method], url_pattern: [url], status: [status code], headers: [headers hash], body: [body])` to define a mock for that test/spec.
+- Remove the mock file in teardown by referencing `Faraday::HotMock.hot_mock_file` (via `File.delete` or `FileUtils.rm`) since you probably don't want them to persist between tests
+
+If you use scenarios, then you can do a bit less:
+
+- Call `Faraday::HotMock.enable!` in your test setup
+- Call `Faraday::HotMock.disable!` in your test teardown
+- Call `Faraday::HotMock.scenario = :your_scenario_name` in a given test/spec
+- Call `Faraday::HotMock.scenario = nil` in your test teardown if using scenarios
+
+Overall, this may be a bit more work but it has the advantage that you can use the same mocking mechanism in both development and testing, which can reduce surprises when moving code between the two.
+
+Small bonus: if you use `Faraday::HotMock` everywhere, you can remove the dependency for whichever mocking library/libraries you were using before.
+
 ### Convenience Methods
 
 You can enable or disable mocking programmatically with these methods:

data/lib/faraday/hot_mock/adapter.rb

@@ -18,16 +18,52 @@ module Faraday
       def call(env)
         super
 
-        if Rails.env.production?
+        if Rails.env.production? || Faraday::HotMock.disabled?
           return @fallback_adapter.new(@app, @options).call(env)
         end
 
-        if Faraday::HotMock.enabled? && (mock = Faraday::HotMock.mocked?(method: env.method, url: env.url))
-          save_response(env, mock["status"] || 200, mock["body"] || "", mock["headers"] || {})
+        if Faraday::HotMock.vcr && !Faraday::HotMock.mocked?(method: env.method, url: env.url)
+          case Faraday::HotMock.vcr
+          when Symbol, String
+            Faraday::HotMock.record(method: env.method, url: env.url, into_scenario: Faraday::HotMock.vcr)
+          else
+            Faraday::HotMock.record(method: env.method, url: env.url)
+          end
+        end
+
+        if (mock = Faraday::HotMock.mocked?(method: env.method, url: env.url))
+          interpolate(mock, env) if mock_interpolated?(mock)
+
+          mock_response!(env, mock)
         else
           @fallback_adapter.new(@app, @options).call(env)
         end
       end
+
+      private
+
+      def mock_interpolated?(mock)
+        mock.key?("interpolate") && mock["body"].is_a?(Hash)
+      end
+
+      def interpolate(mock, env)
+        request_hash = JSON.parse(env.request_body) rescue {}
+
+        interpolated_hash = mock["interpolate"].transform_values do |v|
+          v = request_hash[v]
+        end.compact
+
+        mock["body"].merge!(interpolated_hash || {})
+      end
+
+      def mock_response!(env, mock)
+        save_response(
+          env,
+          mock["status"] || 200,
+          mock["body"] || "",
+          (mock["headers"] || {}).merge(Faraday::HotMock::HEADERS[:mocked] => "true")
+        )
+      end
     end
   end
 end

data/lib/faraday/hot_mock/version.rb

@@ -1,5 +1,5 @@
 module Faraday
   module HotMock
-    VERSION = "0.4.1"
+    VERSION = "0.6.0"
   end
 end

data/lib/faraday/hot_mock.rb

@@ -7,6 +7,14 @@ module Faraday
   module HotMock
     extend self
 
+    attr_accessor :scenario, :vcr
+
+    HEADERS = {
+      recorded: "x-hot-mock-recorded-at",
+      mocked: "x-hot-mocked"
+    }
+    FILE_NAME = "hot_mocks.yml"
+
     def disable!
       FileUtils.rm_f(hot_mocking_file)
     end
@@ -31,7 +39,7 @@ module Faraday
       end
     end
 
-    def delete_mock(method:, url:)
+    def delete(method:, url:)
       return unless File.exist?(hot_mock_file)
 
       mocks = YAML.load_file(hot_mock_file) || []
@@ -64,22 +72,25 @@ module Faraday
       mocks.find { |entry| entry["method"].to_s.upcase == method.to_s.upcase && Regexp.new(entry["url_pattern"]).match?(url.to_s) } || false
     end
 
-    def record(method:, url:)
+    def record(method:, url:, into_scenario: nil)
+      self.scenario = into_scenario if into_scenario.present?
+
       return false if mocked?(method:, url:)
 
       faraday = Faraday.new
 
       response = faraday.send(method.downcase.to_sym, url)
 
+      FileUtils.mkdir_p(hot_mock_dir)
       FileUtils.touch(hot_mock_file)
 
       hot_mocks = YAML.load_file(hot_mock_file) || []
 
       hot_mocks << {
         "method"      => method.to_s.upcase,
-        "url_pattern" => url,
+        "url_pattern" => url.to_s,
         "status"      => response.status,
-        "headers"     => response.headers.to_h.merge("x-hotmock-recorded-at" => Time.now.utc.iso8601),
+        "headers"     => response.headers.to_h.merge(HEADERS[:recorded] => Time.now.utc.iso8601),
         "body"        => response.body
       }
 
@@ -101,9 +112,9 @@ module Faraday
 
       hot_mocks << {
         "method"      => method.to_s.upcase,
-        "url_pattern" => url,
+        "url_pattern" => url.to_s,
         "status"      => response.status,
-        "headers"     => response.headers.to_h.merge("x-hotmock-recorded-at" => Time.now.utc.iso8601),
+        "headers"     => response.headers.to_h.merge(HEADERS[:recorded] => Time.now.utc.iso8601, "x-hot-mock" => "true"),
         "body"        => response.body
       }
 
@@ -113,7 +124,15 @@ module Faraday
     end
 
     def hot_mock_dir
-      Rails.root.join "lib/faraday/mocks/#{Rails.env}"
+      if self.scenario
+        Rails.root.join "lib/faraday/mocks/#{Rails.env}/scenarios/#{self.scenario}"
+      else
+        Rails.root.join "lib/faraday/mocks/#{Rails.env}"
+      end
+    end
+
+    def scenario_dir
+      Rails.root.join "lib/faraday/mocks/#{Rails.env}/scenarios"
     end
 
     def hot_mocking_file
@@ -121,7 +140,7 @@ module Faraday
     end
 
     def hot_mock_file
-      Rails.root.join(hot_mock_dir, "hot_mocks.yml")
+      Rails.root.join(hot_mock_dir, FILE_NAME)
     end
 
     def mocks
@@ -138,7 +157,11 @@ module Faraday
     end
 
     def all_hot_mock_files
-      Dir.glob(File.join(hot_mock_dir, "**", "*.{yml,yaml}"))
+      if scenario.present?
+        Dir.glob(File.join(hot_mock_dir, "**", "*.{yml,yaml}"))
+      else
+        Dir.glob(File.join(hot_mock_dir, "**", "*.{yml,yaml}")).reject { |path| path.include?("/scenarios/") }
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: faraday-hot_mock
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Sean Hogge