doc_repo 0.1.1 → 1.0.0.pre.beta.1

data/spec/doc_repo/repository_spec.rb

@@ -1,25 +1,337 @@
-require 'spec_helper'
+# frozen_string_literal: true
 
 RSpec.describe DocRepo::Repository do
 
-  it "yields the file block for a jpg" do
-    repo = DocRepo::Repository.new
+  def build_config(settings)
+    DocRepo::Configuration.new { |c|
+      settings.each do |name, value|
+        c.public_send "#{name}=", value
+      end
+    }
+  end
 
-    repo.respond("sonic_screwdriver.png") do |r|
-      expect { |b| r.redirect(&b) }.to yield_control
-      expect { |b| r.html(&b) }.not_to yield_control
+  def any_handler
+    DocRepo::ResultHandler.new do |h|
+      h.complete {}
+      h.error {}
+      h.not_found {}
+      h.redirect {}
     end
   end
 
-  it "determines the right mime type for a jpg" do
-    repo = DocRepo::Repository.new
+  shared_examples "requesting a slug" do |slug_reader|
+    let(:any_slug) { send slug_reader }
 
-    repo.respond("sonic_screwdriver.png") do |r|
-      r.redirect do |url|
-        expect( url ).to match %r{https://raw\..*/master/docs/sonic_screwdriver.png}
-      end
+    it "requires a block for handling the result" do
+      expect {
+        subject.request any_slug
+      }.to raise_error(/no block given/)
+    end
+
+    it "yields a result handler" do
+      null_handler = any_handler
+      expect { |b|
+        subject.request any_slug, result_handler: null_handler, &b
+      }.to yield_with_args null_handler
     end
   end
 
-end
+  describe "creating a repository" do
+    it "requires a configuration" do
+      expect {
+        DocRepo::Repository.new
+      }.to raise_error ArgumentError
+    end
+
+    it "duplicates the configuration to preserve state", :aggregate_failures do
+      a_config = DocRepo::Configuration.new
+      a_repo = DocRepo::Repository.new(a_config)
+      expect(a_repo.config).not_to eq a_config
+      expect(a_repo.config.to_h).to eq a_config.to_h
+    end
+
+    it "freezes its configuration to preserve state", :aggregate_failures do
+      a_config = DocRepo::Configuration.new
+      a_repo = DocRepo::Repository.new(a_config)
+      expect(a_repo.config).to be_frozen
+      expect(a_config).not_to be_frozen
+    end
+  end
+
+  it "has a repository name" do
+    a_repo = DocRepo::Repository.new(build_config(repo: "Any Repo Name"))
+    expect(a_repo.repo).to eq "Any Repo Name"
+  end
+
+  it "belongs to an org" do
+    a_repo = DocRepo::Repository.new(build_config(org: "Any Org"))
+    expect(a_repo.org).to eq "Any Org"
+  end
+
+  it "has a target branch" do
+    a_repo = DocRepo::Repository.new(build_config(branch: "Target Branch"))
+    expect(a_repo.branch).to eq "Target Branch"
+  end
+
+  it "has a document root path" do
+    a_repo = DocRepo::Repository.new(build_config(doc_root: "any/doc/path"))
+    expect(a_repo.doc_root).to eq "any/doc/path"
+  end
+
+  it "has a fallback extension" do
+    a_repo = DocRepo::Repository.new(build_config(fallback_ext: ".anything"))
+    expect(a_repo.fallback_ext).to eq ".anything"
+  end
+
+  it "has a set of supported document format extensions" do
+    a_repo = DocRepo::Repository.new(build_config(doc_formats: %w[.anything]))
+    expect(a_repo.doc_formats).to eq %w[.anything]
+  end
+
+  describe "generating a URI for a slug" do
+    it "defines the full repo path" do
+      a_repo = DocRepo::Repository.new(
+        build_config(
+          org: "AnyOrg",
+          repo: "any-repo",
+          branch: "target-branch",
+          doc_root: "doc/root/path",
+          fallback_ext: ".fallback",
+        )
+      )
+      expect(a_repo.uri_for("any-file.ext")).to eq(
+        "/AnyOrg/any-repo/target-branch/doc/root/path/any-file.ext"
+      )
+    end
+
+    it "applies the fallback extension when necessary" do
+      a_repo = DocRepo::Repository.new(build_config(fallback_ext: ".fallback"))
+      expect(a_repo.uri_for("any-document")).to end_with "/any-document.fallback"
+    end
+
+    it "supports a root document path", :aggregate_failures do
+      root_conf = build_config(org: "o", repo: "r", branch: "b", doc_root: "/")
+      a_repo = DocRepo::Repository.new(root_conf)
+      expect(a_repo.uri_for("any-file.ext")).to eq "/o/r/b/any-file.ext"
+
+      root_conf.doc_root = "/root/"
+      a_repo = DocRepo::Repository.new(root_conf)
+      expect(a_repo.uri_for("any-file.ext")).to eq "/o/r/b/root/any-file.ext"
+    end
+  end
+
+  describe "requesting a redirectable slug" do
+    subject(:a_repo) {
+      DocRepo::Repository.new(
+        build_config(
+          org: "org",
+          repo: "repo",
+          branch: "branch",
+          doc_root: "root",
+          doc_formats: %w[ custom ],
+        )
+      )
+    }
+
+    let(:a_redirectable_slug) { "slug.non_document" }
+
+    include_examples "requesting a slug", :a_redirectable_slug
+
+    it "yields the redirect result to the handler" do
+      expect { |b|
+        a_repo.request a_redirectable_slug do |result|
+          result.redirect(&b)
+        end
+      }.to yield_with_args(
+        an_instance_of(
+          DocRepo::Redirect
+        ).and(
+          have_attributes(url:<<~URL.chomp)
+            https://raw.githubusercontent.com/org/repo/branch/root/slug.non_document
+          URL
+        )
+      )
+    end
+
+    it "raises when a handler is not configured for redirection" do
+      expect {
+        a_repo.request a_redirectable_slug do |result|
+          # No-Op
+        end
+      }.to raise_error(
+        DocRepo::UnhandledAction,
+        /no result redirect handler defined/,
+      )
+    end
+  end
 
+  describe "requesting a document slug" do
+    subject(:a_repo) {
+      DocRepo::Repository.new(
+        build_config(
+          org: "org",
+          repo: "repo",
+          branch: "branch",
+          doc_root: "root",
+        ),
+        http_adapter: successful_http,
+      )
+    }
+
+    let(:a_doc_slug) { "any-doc-slug.md" }
+
+    let(:successful_http) {
+      instance_double("DocRepo::NetHttpAdapter", retrieve: the_document)
+    }
+
+    let(:the_document) {
+      instance_double("DocRepo::Doc", redirect?: false, success?: true)
+    }
+
+    include_examples "requesting a slug", :a_doc_slug
+
+    it "fetches the document from the remote site" do
+      expect(successful_http).to receive(:retrieve).with(
+        "/org/repo/branch/root/any-doc-slug.md"
+      )
+      a_repo.request(a_doc_slug, result_handler: any_handler) { }
+    end
+
+    it "yields the document to the handler" do
+      expect { |b|
+        a_repo.request a_doc_slug do |result|
+          result.complete(&b)
+        end
+      }.to yield_with_args the_document
+    end
+
+    it "raises when a handler is not configured for completion" do
+      expect {
+        a_repo.request a_doc_slug do |result|
+          # No-Op
+        end
+      }.to raise_error(
+        DocRepo::UnhandledAction,
+        /no result completion handler defined/,
+      )
+    end
+  end
+
+  describe "requesting a non-existant document slug" do
+    subject(:a_repo) {
+      DocRepo::Repository.new(
+        build_config(
+          org: "org",
+          repo: "repo",
+          branch: "branch",
+          doc_root: "root",
+        ),
+        http_adapter: not_found_http,
+      )
+    }
+
+    let(:missing_doc_slug) { "missing-doc-slug.md" }
+
+    let(:not_found_http) {
+      instance_double("DocRepo::NetHttpAdapter", retrieve: not_found_result)
+    }
+
+    let(:not_found_result) {
+      http_response = instance_double(
+        "Net::HTTPNotFound",
+        code: "404",
+        message: "Any Message",
+      )
+      DocRepo::HttpError.new("uri", http_response.as_null_object)
+    }
+
+    include_examples "requesting a slug", :missing_doc_slug
+
+    it "attempts to fetch the document from the remote site" do
+      expect(not_found_http).to receive(:retrieve).with(
+        "/org/repo/branch/root/missing-doc-slug.md"
+      )
+      a_repo.request(missing_doc_slug, result_handler: any_handler) { }
+    end
+
+    it "yields the error result to the `not_found` handler" do
+      expect { |b|
+        a_repo.request missing_doc_slug do |result|
+          result.not_found(&b)
+        end
+      }.to yield_with_args not_found_result
+    end
+
+    it "falls back to yielding the error result to the `error` handler " \
+       "without a `not_found` handler" do
+      expect { |b|
+        a_repo.request missing_doc_slug do |result|
+          result.error(&b)
+        end
+      }.to yield_with_args not_found_result
+    end
+
+    it "raises the error result without a configured handler" do
+      expect {
+        a_repo.request missing_doc_slug do |result|
+          # No-Op
+        end
+      }.to raise_error(DocRepo::HttpError, '404 "Any Message"')
+    end
+  end
+
+  describe "requesting a document slug", "which causes an error" do
+    subject(:a_repo) {
+      DocRepo::Repository.new(
+        build_config(
+          org: "org",
+          repo: "repo",
+          branch: "branch",
+          doc_root: "root",
+        ),
+        http_adapter: error_http,
+      )
+    }
+
+    let(:any_doc_slug) { "any-doc-slug.md" }
+
+    let(:error_http) {
+      instance_double("DocRepo::NetHttpAdapter", retrieve: error_result)
+    }
+
+    let(:error_result) {
+      http_response = instance_double(
+        "Net::HTTPClientError",
+        code: "400",
+        message: "Any Message",
+      )
+      DocRepo::HttpError.new("uri", http_response.as_null_object)
+    }
+
+    include_examples "requesting a slug", :any_doc_slug
+
+    it "attempts to fetch the document from the remote site" do
+      expect(error_http).to receive(:retrieve).with(
+        "/org/repo/branch/root/any-doc-slug.md"
+      )
+      a_repo.request(any_doc_slug, result_handler: any_handler) { }
+    end
+
+    it "yields the error result to the `error` handler" do
+      expect { |b|
+        a_repo.request any_doc_slug do |result|
+          result.error(&b)
+        end
+      }.to yield_with_args error_result
+    end
+
+    it "raises the error result without a configured handler" do
+      expect {
+        a_repo.request any_doc_slug do |result|
+          # No-Op
+        end
+      }.to raise_error(DocRepo::HttpError, '400 "Any Message"')
+    end
+  end
+
+end

data/spec/doc_repo/result_handler_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+RSpec.describe DocRepo::ResultHandler do
+
+  shared_examples "handling results of type" do |type|
+    subject(:a_handler) { DocRepo::ResultHandler.new }
+
+    it "requires a block" do
+      expect {
+        a_handler.public_send type
+      }.to raise_error ArgumentError, "Result handler block required"
+    end
+
+    it "does not evaluate the block when defined" do
+      expect { |b| a_handler.public_send type, &b }.not_to yield_control
+    end
+
+    it "stores the block" do
+      handler_strategy = -> { "Does Anything" }
+      expect {
+        a_handler.public_send type, &handler_strategy
+      }.to change {
+        a_handler[type.to_sym]
+      }.from(nil).to(handler_strategy)
+    end
+  end
+
+  it "creating a new handler yields itself when given a block" do
+    an_action = -> { }
+    a_handler = DocRepo::ResultHandler.new { |h| h.complete(&an_action) }
+    expect(a_handler[:complete]).to be an_action
+  end
+
+  it "has no actions by default" do
+    expect(DocRepo::ResultHandler.new.each.to_a).to be_empty
+  end
+
+  include_behavior "handling results of type", :complete
+  include_behavior "handling results of type", :error
+  include_behavior "handling results of type", :not_found
+  include_behavior "handling results of type", :redirect
+
+end

data/spec/doc_repo_spec.rb

@@ -6,13 +6,35 @@ RSpec.describe DocRepo do
     # Save and Reset the configuration
     original_config = DocRepo.configuration
     ex.run
-    DocRepo.instance_variable_set :@configuration, original_config
+    DocRepo.configuration = original_config
   end
 
-  it "yields the configuration" do
+  it "always has a configuration" do
+    original_config = DocRepo.configuration
+    expect {
+      DocRepo.configuration = nil
+    }.to change {
+      DocRepo.configuration
+    }.from(original_config).to an_instance_of(DocRepo::Configuration)
+  end
+
+  describe "modifying the configuration" do
+    it "yields the configuration" do
       expect { |b|
         DocRepo.configure(&b)
-      }.to yield_control
+      }.to yield_with_args DocRepo.configuration
+    end
+
+    it "reflects changes made by the block" do
+      DocRepo.configuration.branch = "Any Branch"
+      expect {
+        DocRepo.configure do |c|
+          c.branch = "Modified Branch"
+        end
+      }.to change {
+        DocRepo.configuration.branch
+      }.from("Any Branch").to "Modified Branch"
+    end
   end
 
 end

data/spec/spec_helper.rb

@@ -1,22 +1,107 @@
+# Conventionally, all specs live under a `spec` directory, which RSpec adds to
+# the `$LOAD_PATH`.  The generated `.rspec` file contains `--require
+# spec_helper` which will cause this file to always be loaded, without a need
+# to explicitly require it in any files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need
+# it.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+
 # This is a very warning riddled gem, load it before we enable warnings
 require 'rouge'
 
 RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
   config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
     expectations.include_chain_clauses_in_custom_matcher_descriptions = true
   end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
   config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
     mocks.verify_partial_doubles = true
   end
-  config.filter_run :focus
-  config.run_all_when_everything_filtered = true
+
+  # This option will default to `:apply_to_host_groups` in RSpec 4 (and will
+  # have no way to turn it off -- the option exists only for backwards
+  # compatibility in RSpec 3). It causes shared context metadata to be
+  # inherited by the metadata hash of host groups and examples, rather than
+  # triggering implicit auto-inclusion in groups with matching metadata.
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+
+  # This allows you to limit a spec run to individual examples or groups
+  # you care about by tagging them with `:focus` metadata. When nothing
+  # is tagged with `:focus`, all examples get run. RSpec also provides
+  # aliases for `it`, `describe`, and `context` that include `:focus`
+  # metadata: `fit`, `fdescribe` and `fcontext`, respectively.
+  config.filter_run_when_matching :focus
+
+  # Allows RSpec to persist some state between runs in order to support
+  # the `--only-failures` and `--next-failure` CLI options. We recommend
+  # you configure your source control system to ignore this file.
+  config.example_status_persistence_file_path = "spec/examples.txt"
+
+  # Limits the available syntax to the non-monkey patched syntax that is
+  # recommended. For more details, see:
+  #   - http://rspec.info/blog/2012/06/rspecs-new-expectation-syntax/
+  #   - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   - http://rspec.info/blog/2014/05/notable-changes-in-rspec-3/#zero-monkey-patching-mode
   config.disable_monkey_patching!
+
+  # This setting enables warnings. It's recommended, but in some cases may
+  # be too noisy due to issues in dependencies.
   config.warnings = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
   if config.files_to_run.one?
-    config.default_formatter = 'doc'
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = "doc"
   end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  #config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
   Kernel.srand config.seed
+
+  # Custom shared example aliases for better output grammar
+  config.alias_it_should_behave_like_to :include_behavior
 end
 
+require 'webmock/rspec'
+
 # Load our lib after warnings are enabled so we can fix them
 require 'doc_repo'

data/spec/support/in_memory_cache.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module DocRepo
+  module Spec
+    class InMemoryCache
+      def initialize
+        @cache = {}
+        @options = {}
+      end
+
+      attr_reader :cache, :options
+
+      def clear
+        cache.clear
+        options.clear
+      end
+
+      def keys
+        cache.keys
+      end
+
+      def fetch(name, opts = nil, &block)
+        options[name] = opts
+        cache[name] = cache.fetch(name, &block)
+      end
+
+      def write(name, value, opts = nil)
+        options[name] = opts
+        cache[name] = value
+      end
+    end
+  end
+end