requester 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5f3cc16c0a4d1f66db6398c2a4b19346a141c1ad
+  data.tar.gz: 5c36b763a9c82f1d59905c868301c652a84badd5
+SHA512:
+  metadata.gz: b422f66f43c02bdf78f8b2bfb95f44cf043b094265541ce449432497c22888e17c3aaa1e186a7fda2f509396bd2bed86af046d53f4a72ea7ef30a702168f4062
+  data.tar.gz: 54d90e4eb0a7845ed5598b464bf4f51698cff53a9c14d5f50ede06bc93ee2b1c9985c332a9b7a50b2d8666cf134640d832ddeea3a1f225579e71b1bba0f3c671

data/README.md

@@ -0,0 +1,400 @@
+# Requester
+
+## What is Requester?
+
+Requester coordinates json api requests and responses between the server test
+suite and the client test suite in Rails-based web applications.
+
+## How does it work?
+
+Requester captures the api requests and responses generated by a Rails test
+suite and writes them to a shared file. The client-side test suite (mocha,
+ember-test, etc) uses that file as the source for mocking out those
+same requests.
+
+Requester can be used with Rails API and any front end framework.
+
+## Why would you want this?
+
+Many web applications with extensive front-end rendering test the front-end
+ independently from the relied upon server-side api.  In these siutations, changes to the
+server-side api may go unnoticed by the front-end test suite leading to
+an a green test suite but a broken app.  Additionally, when an api change is
+communicated to the front-end team, effort is needed to ensure that the
+test suite api is mocked correctly.  Requester aims to save that effort
+and provide more transparency to api changes.
+
+## Usage
+
+Pretend we have a Rails app with a `DecksController` with
+ this set of tests:
+
+```ruby
+RSpec.describe DecksController, type: :request do
+  prepend Requester::Requests
+
+  before do
+    %w[diamonds hearts spades clubs].each do |suit|
+      Deck.create suit: suit, cards: "A 2 3 4 5 6 7 8 9 10 J Q K"
+    end
+  end
+
+  describe "GET /decks" do
+    it "works! (now write some real specs)" do
+      get decks_path
+      expect(response).to have_http_status(200)
+    end
+
+    it 'searches' do
+      get decks_path, { search: 'clubs' }, log_as: 'with search'
+      expect(response).to have_http_status(200)
+    end
+  end
+
+  describe 'show' do
+    it "works! (now write some real specs)" do
+      get deck_path(1), headers
+      expect(response).to have_http_status(200)
+    end
+  end
+
+  describe "PUT /decks" do
+    it "works! (now write some real specs)" do
+      headers = { 'ACCEPT' => 'application/json' }
+      xhr :put, deck_path(1), { deck: {cards: '10 J Q K'} }, headers
+      expect(response).to have_http_status(200)
+    end
+  end
+
+  describe "POST /decks" do
+    it "works! (now write some real specs)" do
+      headers = { 'ACCEPT' => 'application/json' }
+      post decks_path, { deck: { cards: "1 2 3", suit: 'horseshoes'} },  headers
+      expect(response).to have_http_status(201)
+    end
+  end
+end
+```
+
+Requester will generate JSON where the top level keys are controllers, followed by
+actions, then the response/request generated by testing that endpoint:
+
+```javascript
+//2017-07-11 13:34:11 UTC
+
+export default {
+  "decks": {
+    "index": {
+      "response": {
+        "status": 200,
+        "body": {
+          "data": [
+            {
+              "id": "1",
+              "type": "decks",
+              "attributes": {
+                "cards": "A 2 3 4 5 6 7 8 9 10 J Q K",
+                "suit": "diamonds"
+              }
+            },
+            {
+              "id": "2",
+              "type": "decks",
+              "attributes": {
+                "cards": "A 2 3 4 5 6 7 8 9 10 J Q K",
+                "suit": "hearts"
+              }
+            },
+            {
+              "id": "3",
+              "type": "decks",
+              "attributes": {
+                "cards": "A 2 3 4 5 6 7 8 9 10 J Q K",
+                "suit": "spades"
+              }
+            },
+            {
+              "id": "4",
+              "type": "decks",
+              "attributes": {
+                "cards": "A 2 3 4 5 6 7 8 9 10 J Q K",
+                "suit": "clubs"
+              }
+            }
+          ]
+        },
+        "message": "OK"
+      },
+      "request": {
+        "path": "/decks",
+        "method": "GET"
+      },
+      "with search": {
+        "response": {
+          "status": 200,
+          "body": {
+            "decks": {
+              "id": 4,
+              "suit": "clubs",
+              "cards": "A 2 3 4 5 6 7 8 9 10 J Q K"
+            }
+          },
+          "message": "OK"
+        },
+        "request": {
+          "path": "/decks?search=clubs",
+          "method": "GET",
+          "query_string": "search=clubs"
+        }
+      }
+    },
+    "show": {
+      "response": {
+        "status": 200,
+        "body": {
+          "data": {
+            "id": "1",
+            "type": "decks",
+            "attributes": {
+              "cards": "A 2 3 4 5 6 7 8 9 10 J Q K",
+              "suit": "diamonds"
+            }
+          }
+        },
+        "message": "OK"
+      },
+      "request": {
+        "path": "/decks/1",
+        "method": "GET"
+      }
+    },
+    "update": {
+      "response": {
+        "status": 200,
+        "body": {
+          "data": {
+            "id": "1",
+            "type": "decks",
+            "attributes": {
+              "cards": "10 J Q K",
+              "suit": "diamonds"
+            }
+          }
+        },
+        "message": "OK"
+      },
+      "request": {
+        "path": "/decks/1",
+        "method": "PUT",
+        "request_parameters": {
+          "deck": {
+            "cards": "10 J Q K"
+          }
+        },
+        "media_type": "application/x-www-form-urlencoded"
+      }
+    },
+    "create": {
+      "response": {
+        "status": 201,
+        "body": {
+          "data": {
+            "id": "5",
+            "type": "decks",
+            "attributes": {
+              "cards": "1 2 3",
+              "suit": "horseshoes"
+            }
+          }
+        },
+        "message": "Created"
+      },
+      "request": {
+        "path": "/decks",
+        "method": "POST",
+        "request_parameters": {
+          "deck": {
+            "cards": "1 2 3",
+            "suit": "horseshoes"
+          }
+        },
+        "media_type": "application/x-www-form-urlencoded"
+      }
+    }
+  }
+}
+```
+
+Now in your front end app, using whatever fake API, you can use this data
+to return responses you know work (assuming you ran requester with a green suite).
+You also have access to the requests.
+
+```javascript
+// meanwhile, in some fake server config in some JS framework...
+import responses from 'dummy-ui/tests/responses';
+
+myFakeApi.get('/decks', () => {
+  return data.decks.index.response.body;
+})
+```
+
+## Usage
+
+There is no magic involved in Requester. It simply prepends itself in your tests so it can log the request/response. Requester expects your tests to use a reasonable set of method calls to initiate a request (xhr, get, put, patch, post, delete, head).
+Requester won't actually do anything when you run your test suite normally.
+When you want to capture data, run `rake requester`.
+
+## Setup
+
+Install requester in your development and test groups
+
+```ruby
+gem 'requester'
+```
+
+The minimum required configuration is to tell Requester where you want the JSON
+dump to be stored for your front end, and dump the Requester logs when the suite ends.
+
+```ruby
+# rails_helper.rb
+
+Requester::Config.initialize do |config|
+  config.front_end_path = '/Users/you/code/my_ui/tests'
+end
+
+RSpec.configure do |config|
+  config.after :suite do
+    Requester::Logger.dump
+  end
+end
+```
+
+#### Config options
+
+* `file_name`: By default this is set to `'responses.js'`. If you want
+to use something different, set it here.
+* `additional_request_attributes`: By default the the following methods are called/logged on the request object:
+ - `path`, `method`, `request_parameters`, `query_string`, `media_type`.
+ You can add additional methods to be logged here.
+* `additional_response_attributes`: By default the the following methods are called/logged on the request object:
+ - `status`, `body`, `message`
+ You can add additional methods to be logged here.
+
+```ruby
+# rails_helper.rb
+
+Request::Config.initialize do |config|
+  config.file_name = 'rails_responses.js'
+  config.additional_request_attributes = [:ssl?]
+  config.additional_response_attributes = [:headers, :cookies]
+end
+```
+
+See below for other config options.
+
+You can set up your tests in a few ways:
+
+#### 1. Capture request/response for every test in the file
+
+Prepend `Requester::Requests` and every test in this group
+will have a log entry.
+
+```ruby
+RSpec.describe DecksController, type: :request do
+  prepend Requester::Requests
+
+  describe "GET /decks" do
+    it "works! (now write some real specs)" do
+      get decks_path
+      expect(response).to have_http_status(200)
+    end
+
+    it 'searches' do
+      get decks_path, { search: 'clubs' }, log_as: 'with search'
+      expect(response).to have_http_status(200)
+    end
+  end
+
+  describe 'show' do
+    it "works! (now write some real specs)" do
+      get deck_path(1), headers
+      expect(response).to have_http_status(200)
+    end
+  end
+```
+
+#### 2. Capture request/response for a describe/context block
+
+Prepend `Requester::Requests` and only the tests in this group
+will have a log entry.
+
+```ruby
+RSpec.describe DecksController, type: :request do
+
+  describe "GET /decks" do
+    prepend Requester::Requests
+
+    it "works! (now write some real specs)" do
+      get decks_path
+      expect(response).to have_http_status(200)
+    end
+
+    it 'searches' do
+      get decks_path, { search: 'clubs' }, log_as: 'with search'
+      expect(response).to have_http_status(200)
+    end
+  end
+
+  describe 'show' do
+    it "works! (now write some real specs)" do
+      get deck_path(1), headers
+      expect(response).to have_http_status(200)
+    end
+  end
+```
+
+#### 3. Capture request/response for individual tests
+
+```ruby
+  describe "GET /decks" do
+    it "works! (now write some real specs)" do
+      get decks_path
+
+      Requester.log_data(
+        request: request,
+        response: response,
+        controller: controller
+      )
+      expect(response).to have_http_status(200)
+    end
+
+    it 'searches' do
+      get decks_path, { search: 'clubs' }, log_as: 'with search'
+      expect(response).to have_http_status(200)
+    end
+  end
+```
+
+You will likely have tests hitting the same endpoint testing different things.
+For example, a test for an index action, and index with optional search params.
+Specify a `log_as` option when you have multiple tests hitting the same endpoint.
+Requester won't override an endpoint entry once it exists.
+
+```ruby
+  describe "GET /decks" do
+    it "works! (now write some real specs)" do
+      get decks_path
+      expect(response).to have_http_status(200)
+    end
+
+    it 'searches' do
+      get decks_path, { search: 'clubs' }, log_as: 'with search'
+      expect(response).to have_http_status(200)
+    end
+  end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Jason Cummings/requester.
+I am not looking to increase the scope of this gem, but I'll consider any ideas.

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "requester"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/requester.rb

@@ -0,0 +1,10 @@
+require 'requester/version'
+require 'requester/config'
+require 'requester/logger'
+require 'requester/requests'
+require 'requester/railtie' if defined?(Rails)
+
+module Requester
+  include Requester::Requests
+  extend Requester::Requests
+end

data/lib/requester/config.rb

@@ -0,0 +1,58 @@
+module Requester
+  class Config
+    class RequesterConfigError < StandardError; end
+
+    class << self
+      attr_accessor :file_name
+      attr_reader :front_end_path, :additional_response_attributes, :additional_request_attributes
+
+      def initialize(&block)
+        @file_name = 'responses.js'
+        @additional_request_attributes = []
+        @additional_response_attributes = []
+
+        class_exec(self, &block)
+      end
+
+      def front_end_path=(path)
+        @front_end_path = path
+
+        unless valid_path_to_front_end_app?
+          raise RequesterConfigError, config_error
+        end
+      end
+
+      def additional_request_attributes=(*args)
+        @additional_request_attributes = args.flatten
+      end
+
+      def additional_response_attributes=(*args)
+        @additional_response_attributes = args.flatten
+      end
+
+      def back_end_path
+        dir = defined?(RSpec) ? 'spec' : 'test'
+        File.join(Rails.root, dir)
+      end
+
+      def export_type
+        :es6
+      end
+
+      private
+
+      def valid_path_to_front_end_app?
+        front_end_path && File.exist?(front_end_path)
+      end
+
+      def config_error
+        <<-UIERROR
+          \n *********************************************************
+          \n Requester needs to know the path to your front end app
+          \n *********************************************************
+          \n
+        UIERROR
+      end
+    end
+  end
+end

data/lib/requester/logger.rb

@@ -0,0 +1,82 @@
+require_relative 'request'
+require_relative 'response'
+
+module Requester
+  class Logger
+    class << self
+      def log
+        @log ||= {}
+      end
+
+      def log_response(response, controller, **options)
+        write('response', controller, options) do
+          Requester::Response.generate(response)
+        end
+      end
+
+      def log_request(request, controller, **options)
+        write('request', controller, options) do
+          Requester::Request.generate(request)
+        end
+      end
+
+      def dump
+        return unless ENV['REQUESTER']
+
+        api_dump = File.new(back_end_file, 'w+')
+        ui_dump = File.new(front_end_file, 'w+')
+        json = JSON.pretty_generate(log)
+
+        # would like to support other types as well
+        case Requester::Config.export_type
+        when :es6
+          ui_dump.write(es6_export + json)
+          api_dump.write(es6_export + json)
+        end
+
+        puts <<-DUMP
+          \n**************************
+          \n Interceptor logs dumped at:
+          \n #{File.expand_path(front_end_file)}
+          \n #{File.expand_path(back_end_file)}
+          \n**************************
+        DUMP
+      ensure
+        api_dump.close if api_dump
+        ui_dump.close if ui_dump
+      end
+
+      private
+
+      def write(request_or_response, controller, **options, &block)
+        c_name = controller.controller_name
+        a_name = controller.action_name
+        log_as = options[:log_as]
+
+        log[c_name] ||= {}
+        log[c_name][a_name] ||= {}
+
+        json = block.call
+
+        if log_as
+          log[c_name][a_name][log_as] ||= {}
+          log[c_name][a_name][log_as][request_or_response] ||= json
+        else
+          log[c_name][a_name][request_or_response] ||= json
+        end
+      end
+
+      def es6_export
+        "//#{Time.zone.now}\n\nexport default "
+      end
+
+      def front_end_file
+        File.join(Requester::Config.front_end_path, Requester::Config.file_name)
+      end
+
+      def back_end_file
+        File.join(Requester::Config.back_end_path, Requester::Config.file_name)
+      end
+    end
+  end
+end

data/lib/requester/railtie.rb

@@ -0,0 +1,8 @@
+module Requester
+  class Railtie < Rails::Railtie
+    railtie_name :requester
+    rake_tasks do
+      load 'tasks/requester.rake'
+    end
+  end
+end

data/lib/requester/request.rb

@@ -0,0 +1,30 @@
+require_relative 'config'
+
+module Requester
+  class Request
+    def self.generate(request)
+      new(request).json
+    end
+
+    def initialize(request)
+      @request = request
+      @config = Requester::Config
+      @json = {
+        path: request.fullpath,
+        method: request.method
+      }
+    end
+
+    def json
+      @json.tap do |json|
+        json[:request_parameters] = @request.request_parameters if @request.request_parameters
+        json[:query_string] = @request.query_string if @request.query_string
+        json[:media_type] = @request.media_type if @request.media_type
+
+        Requester::Config.additional_request_attributes.each do |attr|
+          json[attr] = @request.public_send(attr)
+        end
+      end
+    end
+  end
+end

data/lib/requester/requests.rb

@@ -0,0 +1,27 @@
+require_relative 'config'
+
+module Requester
+  module Requests
+    REQUEST_TYPES = [
+      :xhr, :get, :put, :patch, :post, :delete, :head
+    ]
+
+    REQUEST_TYPES.each do |method|
+      define_method(method) do |*args, **options|
+        super(*args, **options)
+        log_data(options) if ENV['REQUESTER']
+      end
+    end
+
+    def log_data(**options)
+      Logger.log_response(response, controller, options)
+      Logger.log_request(request, controller, options)
+    end
+
+    def self.log_data(request:, response:, controller:, **options)
+      return unless ENV['REQUESTER']
+      Logger.log_response(response, controller, options)
+      Logger.log_request(request, controller, options)
+    end
+  end
+end

data/lib/requester/response.rb

@@ -0,0 +1,27 @@
+require 'json'
+
+module Requester
+  class Response
+
+    def self.generate(response)
+      new(response).json
+    end
+
+    def initialize(response)
+      @response = response
+      @json = {
+        status: response.status,
+        body: JSON.parse(response.body),
+        message: response.message
+      }
+    end
+
+    def json
+      @json.tap do |json|
+        Requester::Config.additional_response_attributes.each do |attr|
+          json[attr] = @response.public_send(attr)
+        end
+      end
+    end
+  end
+end

data/lib/requester/version.rb

@@ -0,0 +1,3 @@
+module Requester
+  VERSION = "0.1.0"
+end

data/lib/tasks/requester.rake

@@ -0,0 +1,20 @@
+desc 'Runs your specs and generates a JSON file based on the selected specs'
+
+task :requester do
+  ENV['REQUESTER'] = 'true'
+
+  command = defined?(RSpec) ? 'rspec' : 'rails test'
+
+  command += " #{ARGV[1..-1].join(' ')}"
+
+  puts(<<-COMMAND)
+    \n *********************************************************
+    \n Running requester using command: #{command.rstrip}
+    \n *********************************************************
+    \n
+  COMMAND
+
+  system(command)
+
+  ENV['REQUESTER'] = nil
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: requester
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jason Cummings
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-07-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: 
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/console
+- bin/setup
+- lib/requester.rb
+- lib/requester/config.rb
+- lib/requester/logger.rb
+- lib/requester/railtie.rb
+- lib/requester/request.rb
+- lib/requester/requests.rb
+- lib/requester/response.rb
+- lib/requester/version.rb
+- lib/tasks/requester.rake
+homepage: https://github.com/jsncmgs1/requester
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Requester coordinates json api requests and responses between the server
+  test suite and the client test suite in Rails-based web applications.
+test_files: []
+has_rdoc: