fdoc 0.2.1

data/spec/fdoc/endpoint_scaffold_spec.rb

@@ -0,0 +1,242 @@
+require 'spec_helper'
+
+describe Fdoc::EndpointScaffold do
+  subject { described_class.new('spec/fixtures/network-GET.fdoc') }
+  let(:action_parameters) { {
+    "scaffold" => true,
+    "description" => "???",
+    "responseCodes" => []
+  } }
+
+  describe "#consume_request" do
+    request_params = {
+      "depth" => 5,
+      "max_connections" => 20,
+      "root_node" => "41EAF42"
+    }
+
+    before(:each) do
+      subject.request_parameters.should be_empty
+    end
+
+    it "creates properties for top-level keys, and populates them with examples" do
+      subject.consume_request(request_params, true)
+      subject.request_parameters["type"].should == nil
+      subject.request_parameters["properties"].should have(3).keys
+      subject.request_parameters["properties"]["depth"]["type"].should == "integer"
+      subject.request_parameters["properties"]["max_connections"]["example"].should == 20
+      subject.request_parameters["properties"]["root_node"]["type"].should == "string"
+    end
+
+    it "infers boolean types" do
+      bool_params = {
+        "with_cheese" => false,
+        "hold_the_lettuce" => true
+      }
+      subject.consume_request(bool_params)
+      subject.request_parameters["properties"].should have(2).keys
+      subject.request_parameters["properties"]["with_cheese"]["type"].should == "boolean"
+      subject.request_parameters["properties"]["hold_the_lettuce"]["type"].should == "boolean"
+    end
+
+    context "infers formats" do
+      it "detects date-time formats as objects, or as is08601 strings" do
+        datetime_params = {
+          "time_str" => Time.now.iso8601,
+          "time_obj" => Time.now
+        }
+        subject.consume_request(datetime_params)
+        subject.request_parameters["properties"].should have(2).keys
+        subject.request_parameters["properties"]["time_str"]["type"].should == "string"
+        subject.request_parameters["properties"]["time_str"]["format"].should == "date-time"
+        subject.request_parameters["properties"]["time_obj"]["type"].should == "string"
+        subject.request_parameters["properties"]["time_obj"]["format"].should == "date-time"
+      end
+
+      it "detects uri formats" do
+        uri_params = {
+          "sample_uri" => "http://my.example.com"
+        }
+        subject.consume_request(uri_params)
+        subject.request_parameters["properties"].should have(1).keys
+        subject.request_parameters["properties"]["sample_uri"]["type"].should == "string"
+        subject.request_parameters["properties"]["sample_uri"]["format"].should == "uri"
+      end
+
+      it "detects color formats (hex only for now)" do
+        color_params = { "page_color" => "#AABBCC" }
+        subject.consume_request(color_params)
+        subject.request_parameters["properties"]["page_color"]["type"].should == "string"
+        subject.request_parameters["properties"]["page_color"]["format"].should == "color"
+      end
+    end
+
+    it "uses strings (not symbols) as keys" do
+      mixed_params = {
+        :with_symbol => false,
+        "with_string" => true
+      }
+      subject.consume_request(mixed_params)
+      subject.request_parameters["properties"].should have(2).keys
+      subject.request_parameters["properties"].should have_key "with_symbol"
+      subject.request_parameters["properties"].should_not have_key :with_symbol
+      subject.request_parameters["properties"].should have_key "with_string"
+      subject.request_parameters["properties"].should_not have_key :with_string          
+    end
+    
+    it "uses strings (not symbols) for keys of nested hashes" do
+      mixed_params = {
+        "nested_object" => {
+          :with_symbol => false,
+          "with_string" => true
+        }
+      }
+
+      subject.consume_request(mixed_params)
+      subject.request_parameters["properties"]["nested_object"]["properties"].keys.sort.should == ["with_string", "with_symbol"]
+    end
+    
+    it "uses strings (not symbols) for nested hashes inside arrays" do
+      mixed_params = {
+        "nested_array" => [
+          {
+            :with_symbol => false,
+            "with_string" => true
+          }            
+        ]
+      }
+
+      subject.consume_request(mixed_params)
+      subject.request_parameters["properties"]["nested_array"]["items"]["properties"].keys.sort.should == ["with_string", "with_symbol"]
+    end
+
+    it "produces a valid JSON schema for the response" do
+      subject.consume_request(request_params)
+      subject.request_parameters["properties"].should have(3).keys
+      JSON::Validator.validate!(subject.request_parameters, request_params).should be_true
+    end
+  end
+
+  describe "#consume_response" do
+    let(:response_params) { {
+      "nodes" => [{
+          "id" => "12941",
+          "name" => "Bobjoe Smith",
+          "linked_to" => [ "111", "121", "999"]
+        }, {
+          "id" => "111",
+          "name" => "Sally",
+          "linked_to" => ["12941"]
+        }, {
+          "id" => "121",
+          "name" => "Captain Smellypants",
+          "linked_to" => ["12941", "999"]
+        }, {
+          "id" => "999",
+          "name" => "Linky McLinkface",
+          "linked_to" => ["12941", "121"]
+        }
+      ],
+      "root_node" => {
+        "id" => "12941",
+        "name" => "Bobjoe Smith",
+        "linked_to" => [ "111", "121", "999"]
+      },
+      "version" => 1,
+      "std_dev" => 1.231,
+      "updated_at" => nil
+    } }
+
+
+
+    context "for succesful responses" do
+      before(:each) do
+        subject.should have(0).response_codes
+      end
+
+      it "adds response codes" do
+        subject.consume_response({}, "200 OK")
+        subject.should have(1).response_codes
+
+        subject.consume_response({}, "201 Created")
+        subject.should have(2).response_codes
+      end
+
+     it "does not add duplicate response codes" do
+        subject.consume_response({}, "200 OK")
+        subject.should have(1).response_codes
+
+        subject.consume_response({}, "200 OK")
+        subject.should have(1).response_codes
+
+        subject.response_codes.each do |response|
+          response["description"].should == "???"
+        end
+      end
+
+      it "creates properties for top-level keys, and populates them with examples" do
+        subject.consume_response(response_params, "200 OK")
+        subject.response_parameters["type"].should == nil
+        subject.response_parameters["properties"].keys.should =~ ["nodes", "root_node", "std_dev", "version", "updated_at"]
+
+        subject.response_parameters["properties"]["nodes"]["type"].should == "array"
+        subject.response_parameters["properties"]["nodes"]["description"].should == "???"
+        subject.response_parameters["properties"]["nodes"]["required"].should == "???"
+
+        subject.response_parameters["properties"]["root_node"]["type"].should == "object"
+        subject.response_parameters["properties"]["root_node"]["description"].should == "???"
+        subject.response_parameters["properties"]["root_node"]["required"].should == "???"
+
+        subject.response_parameters["properties"]["version"]["type"].should == "integer"
+        subject.response_parameters["properties"]["std_dev"]["type"].should == "number"
+      end
+
+      it "populates items in arrays" do
+        subject.consume_response(response_params, "200 OK")
+        subject.response_parameters["properties"]["nodes"]["type"].should == "array"
+        subject.response_parameters["properties"]["nodes"]["items"]["type"].should == "object"
+        subject.response_parameters["properties"]["nodes"]["items"]["properties"].keys.sort.should == [
+          "id", "linked_to","name"]
+      end
+
+      it "turns nil into null" do
+        subject.consume_response(response_params, "200 OK")
+        subject.response_parameters["properties"]["updated_at"]["type"].should == "null"
+      end
+
+      it "uses strings (not symbols) as keys" do
+        mixed_params = {
+          :with_symbol => false,
+          "with_string" => true
+        }
+        subject.consume_response(mixed_params, "200 OK")
+        subject.response_parameters["properties"].should have(2).keys
+        subject.response_parameters["properties"].should have_key "with_symbol"
+        subject.response_parameters["properties"].should_not have_key :with_symbol
+        subject.response_parameters["properties"].should have_key "with_string"
+        subject.response_parameters["properties"].should_not have_key :with_string          
+      end
+
+      it "produces a valid JSON schema for the response" do
+        subject.consume_response(response_params, "200 OK")
+        JSON::Validator.validate!(subject.response_parameters, response_params).should be_true
+      end
+    end
+
+    context "for unsuccessful responses" do
+      it "adds response codes" do
+        subject.should have(0).response_codes
+        subject.consume_response({}, "400 Bad Request", false)
+        subject.should have(1).response_codes
+        subject.consume_response({}, "404 Not Found", false)
+        subject.should have(2).response_codes
+      end
+
+      it "does not modify the response_parameters" do
+        subject.response_parameters.should be_empty
+        subject.consume_response(response_params, "403 Forbidden", false)
+        subject.response_parameters.should be_empty
+      end
+    end
+  end
+end

data/spec/fdoc/endpoint_spec.rb

@@ -0,0 +1,243 @@
+require 'spec_helper'
+
+describe Fdoc::Endpoint do
+  let(:endpoint) { test_service.open(*fdoc_fixture) }
+  let(:fdoc_fixture) { ["GET", "members/list"] }
+  let (:test_service) { Fdoc::Service.new('spec/fixtures') }
+  subject { endpoint }
+  
+  def remove_optional(obj)
+    case obj
+    when Hash
+      res = {}
+      obj.each do |k, v|
+        next if k =~ /optional/
+        res[k] = remove_optional(v)
+      end
+      obj.clear
+      obj.merge!(res)
+    when Array then obj.map { |v| remove_optional(v) }
+    else obj
+    end
+  end
+
+  describe "#verb" do
+    it "infers the verb from the filename and service" do
+      subject.verb.should == "GET"
+    end
+  end
+
+  describe "#path" do
+    it "infers its path from the filename and service" do
+      subject.path.should == "members/list"
+    end
+  end
+
+  describe "#consume_request" do
+    subject { endpoint.consume_request(params) }
+    let(:params) {
+      {
+        "limit" => 0,
+        "offset" => 100,
+        "order_by" => "name"
+      }
+    }
+    
+    context "with a well-behaved request" do
+      it "returns true" do
+        subject.should be_true
+      end
+    end
+
+    context "when the response contains additional properties" do
+      before { params.merge!("extra_goodness" => true) }
+
+      it "should have the unknown keys in the error message" do
+        expect { subject }.to raise_exception(JSON::Schema::ValidationError, /extra_goodness/)
+      end
+    end
+
+    context "when the response contains an unknown enum value" do
+      before { params.merge!("order_by" => "some_stuff") }
+
+      it "should have the value in the error messages" do
+        expect { subject }.to raise_exception(JSON::Schema::ValidationError, /some_stuff/)
+      end
+    end
+
+    context "when the response encounters an object of an known type" do
+      before { params.merge!("offset" => "woot") }
+      
+      it "should have the Ruby type in the error message" do
+        expect { subject }.to raise_exception(JSON::Schema::ValidationError, /String/)
+      end
+    end
+    
+    context "complex examples" do
+      let(:fdoc_fixture) { ["GET", "/members/list/complex-params"] }
+      let(:params) {
+        {
+          "toplevel_param" => "here",
+          "optional_nested_array" => [
+            {
+              "required_param" => "here",
+              "optional_param" => "here"
+            }
+          ],          
+          "required_nested_array" => [
+            {
+              "required_param" => "here",
+              "optional_param" => "here",
+              "optional_second_nested_object" => {
+                "required_param" => "here",
+                "optional_param" => "here"
+              }
+            },
+          ],         
+          "optional_nested_object" => {
+            "required_param" => "here",
+            "optional_param" => "here"
+          },
+          "required_nested_object" => {
+            "required_param" => "here",
+            "optional_param" => "here",
+            "optional_second_nested_object" => {
+              "required_param" => "here",
+              "optional_param" => "here"
+            }
+          },
+        }
+      }
+      
+      it "is successful" do
+        subject.should be_true
+      end
+      
+      context "with no optional keys" do        
+        before { remove_optional(params) }
+
+        it "does not contain optional keys" do
+          params.keys.sort.should == ["required_nested_array", "required_nested_object", "toplevel_param"]
+        end
+        
+        it "is successful" do
+          subject.should be_true
+        end        
+      end
+      
+      context "non documented field added" do
+        before { params.merge!("non_documented" => true) }
+        it "raises an error" do
+          expect { subject }.to raise_exception(JSON::Schema::ValidationError, /non_documented/)
+        end
+      end
+      
+      context "non document field in an optional array" do
+        before { params["optional_nested_array"][0].merge!("non_documented" => true) }
+
+        it "raises an error" do
+          expect { subject }.to raise_exception(JSON::Schema::ValidationError, /non_documented/)
+        end
+      end
+      
+      context "non document field in a required array" do
+        before { params["required_nested_array"][0].merge!("non_documented" => true) }
+
+        it "raises an error" do
+          expect { subject }.to raise_exception(JSON::Schema::ValidationError, /non_documented/)
+        end
+      end
+
+      context "non document field in an optional object" do
+        before { params["optional_nested_object"].merge!("non_documented" => true) }
+
+        it "raises an error" do
+          expect { subject }.to raise_exception(JSON::Schema::ValidationError, /non_documented/)
+        end
+      end
+
+      context "non document field in a required object" do
+        before { params["required_nested_object"].merge!("non_documented" => true) }
+
+        it "raises an error" do
+          expect { subject }.to raise_exception(JSON::Schema::ValidationError, /non_documented/)
+        end
+      end
+      
+      context "non document field in a deeply nested object" do
+        before { params["required_nested_object"]["optional_second_nested_object"].merge!("non_documented" => true) }
+
+        it "raises an error" do
+          expect { subject }.to raise_exception(JSON::Schema::ValidationError, /non_documented/)
+        end
+      end
+      
+      context "required field in a deeply nested object is missing" do
+        before { params["required_nested_object"]["optional_second_nested_object"].delete("required_param") }
+
+        it "raises an error" do
+          expect { subject }.to raise_exception(JSON::Schema::ValidationError, /required_param/)
+        end
+      end
+      
+      context "non document field in a deeply nested object in an array" do
+        before { params["required_nested_array"][0]["optional_second_nested_object"].merge!("non_documented" => true) }
+
+        it "raises an error" do
+          expect { subject }.to raise_exception(JSON::Schema::ValidationError, /non_documented/)
+        end
+      end
+      
+      context "required field in a deeply nested object is missing" do
+        before { params["required_nested_array"][0]["optional_second_nested_object"].delete("required_param") }
+
+        it "raises an error" do
+          expect { subject }.to raise_exception(JSON::Schema::ValidationError, /required_param/)
+        end
+      end
+    end
+  end
+
+  describe "#consume_response" do
+    good_response_params = {
+      "members" => [
+        {"name" => "Captain Smelly Pants"},
+        {"name" => "Sally Pants"},
+        {"name" => "Joe Shorts"}
+      ]
+    }
+
+    it "throws an error when there is no response corresponding to the success-code error" do
+      expect { subject.consume_response(good_response_params, "404 Not Found") }.to raise_exception Fdoc::UndocumentedResponseCode
+      expect { subject.consume_response(good_response_params, "200 OK", false) }.to raise_exception Fdoc::UndocumentedResponseCode
+    end
+
+    context "for successful responses" do
+      it "validates the response parameters against the schema" do
+        subject.consume_response(good_response_params, "200 OK").should be_true
+      end
+
+      context "with unknown keys" do
+        it "throws an error when there an unknown key at the top level" do
+          bad_params = good_response_params.merge({"extra_goodness" => true})
+          expect { subject.consume_response(bad_params, "200 OK") }.to raise_exception JSON::Schema::ValidationError
+        end
+
+        it "throws an error when there is an unknown key a few layers deep" do
+          bad_nested_params = good_response_params.dup
+          bad_nested_params["members"][0]["smelliness"] = "the_max"
+          expect { subject.consume_response(bad_nested_params, "200 OK") }.to raise_exception JSON::Schema::ValidationError
+        end
+      end
+    end
+
+    context "for unsuccessful responses" do
+      context "when there is a valid success-code response" do
+        it "does not throw an error with bad response parameters" do
+          bad_params = good_response_params.merge({"extra_goodness" => true})
+          subject.consume_response(bad_params, "400 Bad Request", false).should be_true
+        end
+      end
+    end
+  end
+end