brainstem 1.0.0.pre.1 → 1.0.0

data/spec/brainstem/api_docs/builder_spec.rb

@@ -0,0 +1,100 @@
+require 'spec_helper'
+require 'brainstem/api_docs/builder'
+
+module Brainstem
+  module ApiDocs
+    describe Builder do
+      let(:dummy_environment_file) do
+        File.expand_path('../../../../spec/dummy/rails.rb', __FILE__)
+      end
+
+      let(:default_options) do
+        { args_for_introspector: { rails_environment_file: dummy_environment_file } }
+      end
+
+      let(:options) { {} }
+
+      subject { Builder.new(default_options.merge(options)) }
+
+
+      describe "#initialize" do
+        let(:introspector_method) { Object.new }
+        let(:options)             { { introspector_method: introspector_method } }
+
+        before do
+          any_instance_of(Builder) do |instance|
+            stub(instance) do |k|
+              k.build_introspector!
+              k.build_atlas!
+            end
+          end
+        end
+
+        it "sets all valid values given to it as options" do
+          expect(subject.introspector_method).to eq introspector_method
+        end
+      end
+
+
+      describe "introspection" do
+        let(:introspector_method)   { Object.new }
+        let(:args_for_introspector) { { blah: true } }
+        let(:introspector)          { Object.new }
+        let(:options) do
+          {
+            args_for_introspector: args_for_introspector,
+            introspector_method: introspector_method
+          }
+        end
+
+        before do
+          any_instance_of(Builder) do |instance|
+            stub(instance) do |k|
+              k.build_atlas!
+            end
+          end
+        end
+
+
+        it "passes the introspector method the introspector options" do
+          mock(introspector_method).call(args_for_introspector)
+          subject
+        end
+
+        it "creates an introspector" do
+          stub(introspector_method).call(args_for_introspector) { introspector }
+          expect(subject.introspector).to eq introspector
+        end
+      end
+
+
+      describe "modeling" do
+        let(:introspector)        { Object.new }
+        let(:atlas_method)        { Object.new }
+        let(:args_for_atlas)      { { blah: true } }
+        let(:atlas)               { Object.new }
+        let(:options)             { { atlas_method: atlas_method, args_for_atlas: args_for_atlas } }
+
+        before do
+          any_instance_of(Builder) do |instance|
+            stub(instance) do |inst|
+              inst.introspector { introspector }
+              inst.build_introspector!
+              inst.build_formatter!
+            end
+          end
+        end
+
+        it "passes the atlas method the introspector and the atlas options" do
+          mock(atlas_method).call(introspector, args_for_atlas)
+          subject
+        end
+
+        it "creates an atlas" do
+          mock(atlas_method).call(introspector, args_for_atlas) { atlas }
+          expect(subject.atlas).to eq atlas
+        end
+      end
+    end
+  end
+end

data/spec/brainstem/api_docs/controller_collection_spec.rb

@@ -0,0 +1,92 @@
+require 'spec_helper'
+require 'brainstem/api_docs/controller_collection'
+
+module Brainstem
+  module ApiDocs
+    describe ControllerCollection do
+      let(:controller) { Object.new }
+      let(:atlas)      { Object.new }
+      let(:options)    { {} }
+
+      subject { described_class.new(atlas, options) }
+
+      describe "#find_by_route" do
+        before do
+          stub(controller) do |c|
+            c.path    { "/posts" }
+            c.const   { Object }
+            c.action  { "index" }
+          end
+
+          subject << controller
+        end
+
+        context "when matches route" do
+          it "returns the matching controller" do
+            route = { controller: Object }
+            expect(subject.find_by_route(route)).to eq controller
+          end
+        end
+
+        context "when does not match route" do
+          it "returns nil" do
+            route = { controller: TrueClass }
+            expect(subject.find_by_route(route)).to eq nil
+          end
+        end
+      end
+
+
+      describe "#create_from_route" do
+        it "creates a new controller, adding it to the members" do
+          controller = subject.create_from_route(
+            path: "/posts",
+            controller: Object,
+            action: "index",
+            controller_name: "object"
+          )
+
+          expect(subject.first).to eq controller
+          expect(controller.const).to eq Object
+          expect(controller.name).to eq "object"
+          expect(controller.endpoints).to \
+            be_a Brainstem::ApiDocs::EndpointCollection
+          expect(controller.endpoints.count).to eq 0
+        end
+      end
+
+
+      describe "#find_or_create_from_route" do
+        let!(:existing_controller) { subject.create_from_route(
+          path: "/posts",
+          controller: Object,
+          action: "index",
+          controller_name: "object"
+        ) }
+
+        context "when has matching controller" do
+          let(:route) { { controller: Object, controller_name: "object" } }
+
+          it "returns that controller" do
+            subject.find_or_create_from_route(route)
+            expect(subject.count).to eq 1
+            expect(subject.last).to eq existing_controller
+          end
+        end
+
+        context "when no matching controller" do
+          let(:route) { { controller: TrueClass, controller_name: "true_class" } }
+
+          it "returns a new controller" do
+            new_controller = subject.find_or_create_from_route(route)
+            expect(subject.count).to eq 2
+            expect(subject.last).to eq new_controller
+          end
+        end
+      end
+
+      it_behaves_like "formattable"
+      it_behaves_like "atlas taker"
+    end
+  end
+end

data/spec/brainstem/api_docs/controller_spec.rb

@@ -0,0 +1,225 @@
+require 'spec_helper'
+require 'brainstem/api_docs/controller'
+
+module Brainstem
+  module ApiDocs
+    describe Controller do
+      subject       { described_class.new(atlas, options) }
+      let(:atlas)   { Object.new }
+      let(:options) { {} }
+
+      describe "#initialize" do
+        it "yields self if given a block" do
+          block = Proc.new { |s| s.name = "bork bork" }
+          expect(described_class.new(atlas, &block).name).to eq "bork bork"
+        end
+      end
+
+
+      describe "#add_endpoint" do
+        let(:endpoint) { Object.new }
+
+        it "adds the endpoint to its list" do
+          expect(subject.endpoints.count).to eq 0
+          subject.add_endpoint(endpoint)
+          expect(subject.endpoints.count).to eq 1
+        end
+      end
+
+
+      describe "derived fields" do
+        let(:lorem)          { "lorem ipsum dolor sit amet" }
+        let(:const)          { Object.new }
+        let(:default_config) { {} }
+        let(:show_config)    { {} }
+        let(:nodoc)          { false }
+        let(:options)        { { const: const } }
+
+        before do
+          stub(const) do |constant|
+            constant.configuration { {
+              :_default => default_config,
+              :show => show_config
+            } }
+
+            constant.to_s { "Api::V1::ClassName" }
+          end
+        end
+
+
+        describe "configuration helpers" do
+          describe "#contextual_documentation" do
+            let(:default_config) { { title: { info: info, nodoc: nodoc } } }
+            let(:info)           { lorem }
+
+            context "when has the key" do
+              let(:key) { :title }
+
+              context "when not nodoc" do
+                context "when has info" do
+                  it "is truthy" do
+                    expect(subject.contextual_documentation(key)).to be_truthy
+                  end
+
+                  it "is the info" do
+                    expect(subject.contextual_documentation(key)).to eq lorem
+                  end
+                end
+
+                context "when has no info" do
+                  let(:info) { nil }
+
+                  it "is falsey" do
+                    expect(subject.contextual_documentation(key)).to be_falsey
+                  end
+                end
+              end
+
+              context "when nodoc" do
+                let(:nodoc) { true }
+
+                it "is falsey" do
+                  expect(subject.contextual_documentation(key)).to be_falsey
+                end
+              end
+            end
+
+            context "when doesn't have the key" do
+              let(:key) { :herp }
+
+              it "is falsey" do
+                expect(subject.contextual_documentation(key)).to be_falsey
+              end
+            end
+          end
+
+
+          describe "#default_configuration" do
+            let(:default_config) { { title: nil } }
+
+            it "returns the default key of the configuration" do
+              expect(subject.default_configuration).to eq default_config
+            end
+          end
+        end
+
+
+        describe "#nodoc?" do
+          let(:default_config) { { nodoc: nodoc } }
+
+          context "when nodoc in default" do
+            let(:nodoc) { true }
+
+            it "is true" do
+              expect(subject.nodoc?).to eq true
+            end
+          end
+
+          context "when not nodoc in default" do
+            it "is false" do
+              expect(subject.nodoc?).to eq false
+            end
+          end
+        end
+
+
+        describe "#title" do
+          context "when present" do
+            let(:default_config) { { title: { info: lorem, nodoc: nodoc } } }
+
+            context "when nodoc" do
+              let(:nodoc) { true }
+
+              it "falls back to the controller class" do
+                expect(subject.title).to eq "ClassName"
+              end
+            end
+
+            context "when documentable" do
+              it "shows the title" do
+                expect(subject.title).to eq lorem
+              end
+            end
+          end
+
+          context "when absent" do
+            it "falls back to the controller class" do
+              expect(subject.title).to eq "ClassName"
+            end
+          end
+        end
+
+
+        describe "#description" do
+          context "when present" do
+            let(:default_config) { { description: { info: lorem, nodoc: nodoc } } }
+
+            context "when nodoc" do
+              let(:nodoc) { true }
+
+              it "shows nothing" do
+                expect(subject.description).to eq ""
+              end
+            end
+
+            context "when documentable" do
+              it "shows the description" do
+                expect(subject.description).to eq lorem
+              end
+            end
+          end
+
+          context "when absent" do
+            it "shows nothing" do
+              expect(subject.description).to eq ""
+            end
+          end
+        end
+      end
+
+
+      describe "#suggested_filename" do
+        let(:const)          { Object.new }
+
+        before do
+          stub(const) do |constant|
+            constant.to_s { "Api::V1::ClassName" }
+          end
+        end
+
+
+        it "gsubs namespace, filename and extension" do
+          instance = described_class.new(atlas,
+            filename_pattern: "controllers/{{namespace}}/{{name}}_controller.{{extension}}",
+            name: 'api/v1/abc',
+            const: const,
+          )
+
+          stub(instance).extension { "xyz" }
+
+          expect(instance.suggested_filename(:xyz)).to \
+            eq "controllers/api/v1/abc_controller.xyz"
+        end
+      end
+
+
+      describe "#suggested_filename_link" do
+        it "gsubs filename and extension" do
+
+          instance = described_class.new(atlas,
+            filename_link_pattern: "controllers/{{name}}_controller.{{extension}}.foo",
+            name: 'abc'
+          )
+
+          stub(instance).extension { "xyz" }
+
+          expect(instance.suggested_filename_link(:xyz)).to eq "controllers/abc_controller.xyz.foo"
+        end
+      end
+
+
+      it_behaves_like "formattable"
+      it_behaves_like "atlas taker"
+    end
+  end
+end

data/spec/brainstem/api_docs/endpoint_collection_spec.rb

@@ -0,0 +1,144 @@
+require 'spec_helper'
+require 'brainstem/api_docs/endpoint_collection'
+
+module Brainstem
+  module ApiDocs
+    describe EndpointCollection do
+      let(:atlas)    { Object.new }
+      let(:options)  { {} }
+      let(:endpoint) { Object.new }
+
+      subject { described_class.new(atlas, options) }
+
+
+      describe "#find_from_route" do
+        let(:controller) { stub!.const { Object }.subject }
+
+        before do
+          stub(endpoint) do |c|
+            c.path            { "/posts" }
+            c.http_methods    { ["GET", "POST"] }
+            c.controller      { controller }
+            c.controller_name { "object" }
+            c.action          { "index" }
+          end
+
+          subject << endpoint
+        end
+
+        context "when matches route" do
+          it "returns the matching controller" do
+            route = { controller: Object, path: "/posts", action: "index" }
+            expect(subject.find_by_route(route)).to eq endpoint
+          end
+        end
+
+        context "when does not match route" do
+          it "returns nil" do
+            routes = [
+              { controller: TrueClass, path: "/posts", action: "index" },
+              { controller: Object,    path: "/wrong", action: "index" },
+              { controller: Object,    path: "/posts", action: "wrong" },
+            ]
+
+            routes.each do |route|
+              expect(subject.find_by_route(route)).to eq nil
+            end
+          end
+        end
+      end
+
+
+      describe "#create_from_route" do
+        it "creates a new endpoint, adding it to the members" do
+          controller = Object.new
+
+          endpoint = subject.create_from_route({
+            path:            "/posts",
+            http_methods:    ["GET"],
+            controller_name: "object",
+            action:          "index",
+          }, controller)
+
+          expect(subject.first).to eq endpoint
+          expect(endpoint.controller).to eq controller
+          expect(endpoint.controller_name).to eq "object"
+          expect(endpoint.action).to eq "index"
+          expect(endpoint.path).to eq "/posts"
+          expect(endpoint.http_methods).to eq ["GET"]
+        end
+      end
+
+
+      describe "#only_documentable" do
+        let(:endpoint_2) { Object.new }
+
+        before do
+          stub(endpoint).nodoc? { false }
+          stub(endpoint_2).nodoc? { true }
+
+          subject << endpoint
+          subject << endpoint_2
+        end
+
+        it "returns a new collection with members that are not nodoc" do
+          new_clxn = subject.only_documentable
+
+          expect(new_clxn).to be_a described_class
+          expect(new_clxn).to include endpoint
+          expect(new_clxn).not_to include endpoint_2
+        end
+      end
+
+
+      describe "#with_declared_presented_class" do
+        let(:endpoint_2) { Object.new }
+
+        before do
+          stub(endpoint).declared_presented_class { Class.new }
+          stub(endpoint_2).declared_presented_class { nil }
+          subject << endpoint
+          subject << endpoint_2
+        end
+
+        it "returns a new collection with members that have declared presents" do
+          new_clxn = subject.with_declared_presented_class
+
+          expect(new_clxn).to be_a described_class
+          expect(new_clxn).to include endpoint
+          expect(new_clxn).not_to include endpoint_2
+        end
+      end
+
+
+      describe "#with_actions_in_controller" do
+        let(:endpoint_2) { Object.new }
+        let(:const) do
+          Class.new do
+            def show
+            end
+          end
+        end
+
+        before do
+          stub(endpoint).action { :show }
+          stub(endpoint_2).action { :index }
+          subject << endpoint
+          subject << endpoint_2
+        end
+
+        it "returns a new collection with members that the const responds to" do
+          new_clxn = subject.with_actions_in_controller(const)
+
+          expect(new_clxn).to be_a described_class
+          expect(new_clxn).to include endpoint
+          expect(new_clxn).not_to include endpoint_2
+        end
+      end
+
+
+      it_behaves_like "formattable"
+      it_behaves_like "atlas taker"
+    end
+  end
+end