faraday-hot_mock 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca41f6d974866b895fa2ce0da58d30c61120d63c342dcb39d353346156692abe
-  data.tar.gz: f45729e717e06848776bca596533d8e4af59cf22eebd83ee5a0e4405ff003ec1
+  metadata.gz: 56228dde369003b5c2b7a68b7af56e2533c13d07ffc9dc997c8fe3a937c48f55
+  data.tar.gz: bc60f461818b035f6e3d14a28d6b6f9943d47bac85ce398013a91569fba6268f
 SHA512:
-  metadata.gz: af9f9770c7e9893202512044fc30502871766c4056541eb3f723fc4975948fa72d6d8567e4a751085dbbfd2f0fbbb0b32bcd4dae06d93862575763e9b1045a57
-  data.tar.gz: f99a15ab120d185c605ba7f9982c1e9925ca9fe8065645152236c3094fc6bcfe5db1878f6a8fcac5f1ae321cad235b97330ba58fe03e735f953882ac15a22f56
+  metadata.gz: 6398844d597bda4844ef3967f104dd6300ff9d9226128b34df2ef2ae096e740f0037b9708f53f70acf5151405a581d507a15ff4e3e9db3fc0d590bfabcdd8694
+  data.tar.gz: 3ee86b689589bb1cf24d012a47feddefe1e2d8074497953acf7ee85d1936a02387ec3124b07b2cd366345005a5e5dc73a67507e7b63452f209e05ed226905afa

data/README.md

@@ -6,6 +6,17 @@ This adapter attempts to make that simpler by parsing YAML files at runtime. If
 
 _**This adapter is meant for Faraday usage in Rails, not for Faraday that's used in other frameworks or situations.**_
 
+## Why Use Faraday::HotMock instead of VCR?
+
+VCR focuses on keeping HTTP requests out of tests - Faraday::HotMock focuses on simulating API responses during development.
+
+To use VCR in development would require wrapping code in VCR blocks, which must then be undone before deployment. Simple, but tedious and error-prone.
+
+Faraday::HotMock requires no code changes to the application - it doesn't mock anything in production, even if you try. So while the HotMock adapter is "used", it just passes requests to the default or adapter or specified fallback.
+
+VCR works with any HTTP library, Faraday::HotMock only works with Faraday. This is a critical limitation unless you use only or primarily Faraday.
+
+You could, ostensibly, replace VCR with Faraday::HotMock in tests. VCR is battle-tested, well-written and widely used, so it's likely a better choice for testing. But the goal is to make Faraday::HotMock just as useful in all non-production environments.
 
 ## How It Works
 
@@ -19,13 +30,12 @@ This means that if you have a Staging environment, or a UAT environment along wi
 
 You can organize your per-environment mocks as you see fit - all in one file, or split between descriptive directories and file names.
 
-
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "faraday-hot_mock", git: "https://github.com/seanhogge/faraday-hot_mock"
+gem "faraday-hot_mock"
 ```
 
 And then execute:
@@ -33,7 +43,6 @@ And then execute:
 $ bundle
 ```
 
-
 ## Usage
 
 Add this adapter to your middleware pipeline, making sure that it's last:
@@ -52,11 +61,11 @@ Optionally, specify a fallback adapter (`Faraday.default_adapter` is the default
 @conn = Faraday.new(url: "https://dog.ceo/api/") do |faraday|
   faraday.request :json
   faraday.response :json
-  faraday.adapter :hot_mock, fallback: :cool_community_adapter
+  faraday.adapter :hot_mock, fallback: :cool_community_adapter # only useful if the default adapter isn't already :cool_community_adapter!
 end
 ```
 
-Then add the switch: `tmp/mocking-#{Rails.env}.txt`. Just like Rails' own `tmp/caching-dev.txt` file, this will toggle HotMock on when present, and off when not present.
+Then add the switch: `tmp/mocking-#{Rails.env}.txt` (or use the [convenience method](#convenience-methods)). Just like Rails' own `tmp/caching-dev.txt` file, this will toggle HotMock on when present, and off when not present.
 
 > ⚠️ REMEMBER: For caching, it's `tmp/caching-dev.txt`, but for mocking it's `tmp/mocking-development.txt`
 
@@ -64,7 +73,21 @@ Now, create the directory `lib/faraday/mocks/` and a subdirectory for each envir
 
 > ⚠️ REMEMBER: it's `lib/faraday/mocks`, not `app/lib/faraday/mocks`
 
-Consider adding these directories to .gitignore unless you want mocks to be shared.
+### Git Ignore?
+
+It can be useful to share mocks with others, or to ensure you don't ever lose them.
+
+It can also be a terrible idea if your mocks are designed for your specific needs, and can cause noise in PRs and commits.
+
+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`:
+
+```
+# Ignore Faraday HotMocks except in test env
+lib/faraday/mocks/**
+!lib/faraday/mocks/test
+```
 
 ### Convenience Methods
 
@@ -76,19 +99,27 @@ Faraday::HotMock.disable!  # deletes tmp/mocking-#{Rails.env}.txt
 Faraday::HotMock.toggle!  # creates tmp/mocking-#{Rails.env}.txt if missing, deletes if present
 ```
 
-In addition, you can check if mocking is enabled with:
+You can check if mocking is enabled with:
 
 ```ruby
 Faraday::HotMock.enabled?  # returns true/false;
 Faraday::HotMock.disabled?  # returns true/false;
 ```
 
-These methods have limited use, but can be helpful in scripting scenarios.
+You can check if a given url and method will match against a mock with:
+
+```ruby
+Faraday::HotMock.mocked?(method: 'GET', url: 'https://vendorname.com/api/v1/endpoint')  # returns matching mock or false
+```
+
+These methods have limited use, but can be helpful in scripting scenarios, or to skip tedious file creation and deletion.
 
 ### Defining Mocks
 
+You can simply create a YAML file in `lib/faraday/mocks/#{Rails.env}/` with one or more mock definitions by hand:
+
 ```yaml
-# lib/faraday/mocks/development/vendor_name_mocks.yml
+# lib/faraday/mocks/development/any_name_you_like.yml
 - url_pattern: vendorname.com.*/endpoint
   method: POST
   status: 418
@@ -98,12 +129,14 @@ These methods have limited use, but can be helpful in scripting scenarios.
     error: I'm a teapot
 ```
 
+Or you can do the same in the default mock file for the current environment: `lib/faraday/mocks/#{Rails.env}/hot_mocks.yml`.
+
 Now, any POST request made to `vendorname.com/api/v1/endpoint` will return a mock 418 response with a JSON body. A GET to the same endpoint will make the actual call.
 
 If you edit the file to be:
 
 ```yaml
-# lib/faraday/mocks/development/vendor_name_mocks.yml
+# lib/faraday/mocks/development/any_name_you_like.yml
 - url_pattern: vendorname.com.*/endpoint
   method: POST
   status: 503
@@ -115,7 +148,27 @@ If you edit the file to be:
 
 then the next request made to `vendorname.com/api/v1/endpoint` will return a mock 503 response with a JSON body. No need to reload anything.
 
-This lets you quickly simulate any type of response you need.
+If you want to add a mock from the Rails console, you can use `Faraday::HotMock.mock!(method: [method], url_pattern: [url_pattern], status: [status], headers: [headers], body: [body])`. This will add the mock to the default mock file for the current environment.
+
+A mock can be recorded by calling `Faraday::HotMock.record(method: [method], url: [url])`. This will make the actual call and then store the response in the default mock file for the current environment: `lib/faraday/mocks/#{Rails.env}/hot_mocks.yml`.
+
+If a mock already exists for that method and URL, no request will be made and `false` will be returned.
+
+Use `Faraday::HotMock.record!` (with a bang) to force recording even if a mock already exists. This will remove the old matching mock and put the new one in its place.
+
+> ⚠️ WARNING: Recording does not remove any mocks from custom files, only from the default `hot_mocks.yml` file. If there are duplicates between custom files and the default file, there is no guarantee which one will be used.
+
+Once recorded, you can easily edit the mock file to change status codes, headers, or body content as needed.
+
+If you need to know where the mock file is located, you can call `Faraday::HotMock.hot_mock_file`, which will return the full path to the default mock file for the current environment.
+
+### REGEX and You(r Mocks)
+
+When recording a mock, you must pass a full URL. However, when defining mocks in YAML files, you can use regular expressions for more flexible matching.
+
+Remember that once recorded, the `url_pattern` can be adjusted.
+
+### Disabling Mocks
 
 If you want to disable mocks, you can:
 
@@ -127,14 +180,10 @@ If you want to disable mocks, you can:
 - Delete the directory
 - Use the [convenience methods](#convenience-methods)
 
-If you'd rather keep the file(s) around, just delete `tmp/mocking-development.txt`. That will globally disable any mocked responses.
-
-
 ## Contributing
 
 Fork, work, PR while following the [Code of Conduct](https://github.com/seanhogge/faraday-hot_mock/CODE_OF_CONDUCT.md)
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/faraday/hot_mock/adapter.rb

@@ -9,60 +9,25 @@ module Faraday
     class Adapter < Faraday::Adapter
       def initialize(app, options = {})
         super(app)
-        @mock_dir = options[:mock_dir] || default_mock_dir
         @enabled_file = options[:enabled_file] || "tmp/mocking-#{Rails.env}.txt"
         fallback = options[:fallback] || Faraday.default_adapter
         @fallback_adapter = Faraday::Adapter.lookup_middleware(fallback)
-        @mocks = load_mocks
+        @mocks = Faraday::HotMock.mocks
       end
 
       def call(env)
         super
-        if mocking_enabled? && @mocks && (mock = find_mock(env.method, env.url))
-          save_response(env, mock["status"] || 200, mock["body"] || "", mock["headers"] || {})
-        else
-          @fallback_adapter.new(@app, @options).call(env)
-        end
-      end
-
-      private
 
-      def load_mocks
-        return [] unless Dir.exist?(Rails.root.join @mock_dir)
-
-        mocks = []
-
-        yaml_files.each do |file|
-          file_mocks = YAML.load_file(file)
-          mocks.concat(file_mocks) if file_mocks.is_a?(Array)
+        if Rails.env.production?
+          return @fallback_adapter.new(@app, @options).call(env)
         end
 
-        mocks
-      end
-
-      def mocking_enabled?
-        File.exist?(Rails.root.join @enabled_file)
-      end
-
-      def default_mock_dir
-        rails_env = defined?(Rails) ? Rails.env : ENV["RAILS_ENV"] || "development"
-        "lib/faraday/mocks/#{rails_env}"
-      end
-
-      def find_mock(method, url)
-        return nil unless @mocks.any?
-
-        @mocks.find do |mock|
-          url_matches = Regexp.new(mock["url_pattern"]).match?(url.to_s)
-          method_matches = mock["method"].nil? || mock["method"].to_s.upcase == method.to_s.upcase
-
-          url_matches && method_matches
+        if Faraday::HotMock.enabled? && (mock = Faraday::HotMock.mocked?(method: env.method, url: env.url))
+          save_response(env, mock["status"] || 200, mock["body"] || "", mock["headers"] || {})
+        else
+          @fallback_adapter.new(@app, @options).call(env)
         end
       end
-
-      def yaml_files
-        Dir.glob(File.join(Rails.root.join(@mock_dir), "**", "*.{yml,yaml}"))
-      end
     end
   end
 end

data/lib/faraday/hot_mock/version.rb

@@ -1,5 +1,5 @@
 module Faraday
   module HotMock
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/faraday/hot_mock.rb

@@ -5,31 +5,140 @@ require "faraday"
 
 module Faraday
   module HotMock
-    module_function
+    extend self
 
     def disable!
-      FileUtils.rm_f(Rails.root.join("tmp/mocking-#{Rails.env}.txt"))
+      FileUtils.rm_f(hot_mocking_file)
     end
 
     def disabled?
-      !File.exist?(Rails.root.join("tmp/mocking-#{Rails.env}.txt"))
+      !File.exist?(hot_mocking_file)
     end
 
     def enable!
-      FileUtils.touch(Rails.root.join("tmp/mocking-#{Rails.env}.txt"))
+      FileUtils.touch(hot_mocking_file)
     end
 
     def enabled?
-      File.exist?(Rails.root.join("tmp/mocking-#{Rails.env}.txt"))
+      File.exist?(hot_mocking_file)
     end
 
     def toggle!
-      if File.exist?(Rails.root.join("tmp/mocking-#{Rails.env}.txt"))
+      if File.exist?(hot_mocking_file)
         disable!
       else
         enable!
       end
     end
+
+    def delete_mock(method:, url:)
+      return unless File.exist?(hot_mock_file)
+
+      mocks = YAML.load_file(hot_mock_file) || []
+
+      mocks.reject! { |entry| entry["url_pattern"] == url && entry["method"].to_s.upcase == method.to_s.upcase }
+
+      File.write(hot_mock_file, mocks.to_yaml)
+    end
+
+    def mock!(method:, url:, status:, headers: {}, body: nil)
+      FileUtils.touch(hot_mock_file)
+
+      mocks = YAML.load_file(hot_mock_file) || []
+
+      mocks.reject! { |entry| entry["url_pattern"] == url && entry["method"].to_s.upcase == method.to_s.upcase }
+
+      mocks << {
+        "method"      => method.to_s.upcase,
+        "url_pattern" => url,
+        "status"      => status,
+        "headers"     => headers,
+        "body"        => body
+      }
+
+      File.write(hot_mock_file, mocks.to_yaml)
+    end
+
+    def mocked?(method:, url:)
+      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:)
+      return false if mocked?(method:, url:)
+
+      faraday = Faraday.new
+
+      response = faraday.send(method.downcase.to_sym, url)
+
+      FileUtils.touch(hot_mock_file)
+
+      hot_mocks = YAML.load_file(hot_mock_file) || []
+
+      hot_mocks << {
+        "method"      => method.to_s.upcase,
+        "url_pattern" => url,
+        "status"      => response.status,
+        "headers"     => response.headers.to_h.merge("x-hotmock-recorded-at" => Time.now.utc.iso8601),
+        "body"        => response.body
+      }
+
+      File.write(hot_mock_file, hot_mocks.to_yaml)
+    rescue Faraday::Error => e
+      puts "Error recording mock for #{method.upcase} #{url}: #{e.message}"
+    end
+
+    def record!(method:, url:)
+      faraday = Faraday.new
+
+      response = faraday.send(method.downcase.to_sym, url)
+
+      FileUtils.touch(hot_mock_file)
+
+      hot_mocks = YAML.load_file(hot_mock_file) || []
+
+      hot_mocks.reject! { |entry| entry["url_pattern"] == url && entry["method"].to_s.upcase == method.to_s.upcase }
+
+      hot_mocks << {
+        "method"      => method.to_s.upcase,
+        "url_pattern" => url,
+        "status"      => response.status,
+        "headers"     => response.headers.to_h.merge("x-hotmock-recorded-at" => Time.now.utc.iso8601),
+        "body"        => response.body
+      }
+
+      File.write(hot_mock_file, hot_mocks.to_yaml)
+    rescue Faraday::Error => e
+      puts "Error recording mock for #{method.upcase} #{url}: #{e.message}"
+    end
+
+    def hot_mock_dir
+      Rails.root.join "lib/faraday/mocks/#{Rails.env}"
+    end
+
+    def hot_mocking_file
+      Rails.root.join "tmp/mocking-#{Rails.env}.txt"
+    end
+
+    def hot_mock_file
+      Rails.root.join(hot_mock_dir, "hot_mocks.yml")
+    end
+
+    def mocks
+      return [] unless Dir.exist?(hot_mock_dir)
+
+      mocks = []
+
+      all_hot_mock_files.each do |file|
+        file_mocks = YAML.load_file(file)
+        mocks.concat(file_mocks) if file_mocks.is_a?(Array)
+      end
+
+      mocks
+    end
+
+    def all_hot_mock_files
+      Dir.glob(File.join(hot_mock_dir, "**", "*.{yml,yaml}"))
+    end
   end
 end
 

metadata

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