herr 0.7.3

data/lib/her/version.rb

@@ -0,0 +1,3 @@
+module Her
+  VERSION = "0.7.3"
+end

data/spec/api_spec.rb

@@ -0,0 +1,131 @@
+# encoding: utf-8
+require File.join(File.dirname(__FILE__), "spec_helper.rb")
+
+describe Her::API do
+  subject { Her::API.new }
+
+  context "initialization" do
+    describe ".setup" do
+      it "creates a default connection" do
+        Her::API.setup :url => "https://api.example.com"
+        Her::API.default_api.base_uri.should == "https://api.example.com"
+      end
+    end
+
+    describe "#setup" do
+      context "when using :url option" do
+        before { subject.setup :url => "https://api.example.com" }
+        its(:base_uri) { should == "https://api.example.com" }
+      end
+
+      context "when using the legacy :base_uri option" do
+        before { subject.setup :base_uri => "https://api.example.com" }
+        its(:base_uri) { should == "https://api.example.com" }
+      end
+
+      context "when setting custom middleware" do
+        before do
+          class Foo; end;
+          class Bar; end;
+
+          subject.setup :url => "https://api.example.com" do |connection|
+            connection.use Foo
+            connection.use Bar
+          end
+        end
+
+        specify { subject.connection.builder.handlers.should == [Foo, Bar] }
+      end
+
+      context "when setting custom options" do
+        before { subject.setup :foo => { :bar => "baz" }, :url => "https://api.example.com" }
+        its(:options) { should == { :foo => { :bar => "baz" }, :url => "https://api.example.com" } }
+      end
+    end
+
+    describe "#request" do
+      before do
+        class SimpleParser < Faraday::Response::Middleware
+          def on_complete(env)
+            env[:body] = { :data => env[:body] }
+          end
+        end
+      end
+
+      context "making HTTP requests" do
+        let(:parsed_data) { subject.request(:_method => :get, :_path => "/foo")[:parsed_data] }
+        before do
+          subject.setup :url => "https://api.example.com" do |builder|
+            builder.use SimpleParser
+            builder.adapter(:test) { |stub| stub.get("/foo") { |env| [200, {}, "Foo, it is."] } }
+          end
+        end
+
+        specify { parsed_data[:data].should == "Foo, it is." }
+      end
+
+      context "making HTTP requests while specifying custom HTTP headers" do
+        let(:parsed_data) { subject.request(:_method => :get, :_path => "/foo", :_headers => { "X-Page" => 2 })[:parsed_data] }
+
+        before do
+          subject.setup :url => "https://api.example.com" do |builder|
+            builder.use SimpleParser
+            builder.adapter(:test) { |stub| stub.get("/foo") { |env| [200, {}, "Foo, it is page #{env[:request_headers]["X-Page"]}."] } }
+          end
+        end
+
+        specify { parsed_data[:data].should == "Foo, it is page 2." }
+      end
+
+      context "parsing a request with the default parser" do
+        let(:parsed_data) { subject.request(:_method => :get, :_path => "users/1")[:parsed_data] }
+        before do
+          subject.setup :url => "https://api.example.com" do |builder|
+            builder.use Her::Middleware::FirstLevelParseJSON
+            builder.adapter :test do |stub|
+              stub.get("/users/1") { |env| [200, {}, MultiJson.dump({ :id => 1, :name => "George Michael Bluth", :errors => ["This is a single error"], :metadata => { :page => 1, :per_page => 10 } })] }
+            end
+          end
+        end
+
+        specify do
+          parsed_data[:data].should == { :id => 1, :name => "George Michael Bluth" }
+          parsed_data[:errors].should == ["This is a single error"]
+          parsed_data[:metadata].should == { :page => 1, :per_page => 10 }
+        end
+      end
+
+      context "parsing a request with a custom parser" do
+        let(:parsed_data) { subject.request(:_method => :get, :_path => "users/1")[:parsed_data] }
+        before do
+          class CustomParser < Faraday::Response::Middleware
+            def on_complete(env)
+              json = MultiJson.load(env[:body], :symbolize_keys => true)
+              errors = json.delete(:errors) || []
+              metadata = json.delete(:metadata) || {}
+              env[:body] = {
+                :data => json,
+                :errors => errors,
+                :metadata => metadata,
+              }
+            end
+          end
+
+          subject.setup :url => "https://api.example.com" do |builder|
+            builder.use CustomParser
+            builder.use Faraday::Request::UrlEncoded
+            builder.adapter :test do |stub|
+              stub.get("/users/1") { |env| [200, {}, MultiJson.dump(:id => 1, :name => "George Michael Bluth")] }
+            end
+          end
+        end
+
+        specify do
+          parsed_data[:data].should == { :id => 1, :name => "George Michael Bluth" }
+          parsed_data[:errors].should == []
+          parsed_data[:metadata].should == {}
+        end
+      end
+    end
+  end
+end

data/spec/collection_spec.rb

@@ -0,0 +1,26 @@
+require 'spec_helper'
+
+describe Her::Collection do
+
+  let(:items) { [1, 2, 3, 4] }
+  let(:metadata) { { :name => 'Testname' } }
+  let(:errors) { { :name => ['not_present'] } }
+
+  describe "#new" do
+    context "without parameters" do
+      subject { Her::Collection.new }
+
+      it { should eq([]) }
+      its(:metadata) { should eq({}) }
+      its(:errors) { should eq({}) }
+    end
+
+    context "with parameters" do
+      subject { Her::Collection.new(items, metadata, errors) }
+
+      it { should eq([1,2,3,4]) }
+      its(:metadata) { should eq({ :name => 'Testname' }) }
+      its(:errors) { should eq({ :name => ['not_present'] }) }
+    end
+  end
+end

data/spec/middleware/accept_json_spec.rb

@@ -0,0 +1,10 @@
+# encoding: utf-8
+require "spec_helper"
+
+describe Her::Middleware::AcceptJSON do
+  it "adds an Accept header" do
+    described_class.new.add_header({}).tap do |headers|
+      headers["Accept"].should == "application/json"
+    end
+  end
+end

data/spec/middleware/first_level_parse_json_spec.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+require "spec_helper"
+
+describe Her::Middleware::FirstLevelParseJSON do
+  subject { described_class.new }
+  let(:body_without_errors) { "{\"id\": 1, \"name\": \"Tobias Fünke\", \"metadata\": 3}" }
+  let(:body_with_errors) { "{\"id\": 1, \"name\": \"Tobias Fünke\", \"errors\": { \"name\": [ \"not_valid\", \"should_be_present\" ] }, \"metadata\": 3}" }
+  let(:body_with_malformed_json) { "wut." }
+  let(:body_with_invalid_json) { "true" }
+  let(:empty_body) { '' }
+  let(:nil_body) { nil }
+
+  it "parses body as json" do
+    subject.parse(body_without_errors).tap do |json|
+      json[:data].should == { :id => 1, :name => "Tobias Fünke" }
+      json[:metadata].should == 3
+    end
+  end
+
+  it "parses :body key as json in the env hash" do
+    env = { :body => body_without_errors }
+    subject.on_complete(env)
+    env[:body].tap do |json|
+      json[:data].should == { :id => 1, :name => "Tobias Fünke" }
+      json[:metadata].should == 3
+    end
+  end
+
+  it 'ensures the errors are a hash if there are no errors' do
+    subject.parse(body_without_errors)[:errors].should eq({})
+  end
+
+  it 'ensures the errors are a hash if there are no errors' do
+    subject.parse(body_with_errors)[:errors].should eq({:name => [ 'not_valid', 'should_be_present']})
+  end
+
+  it 'ensures that malformed JSON throws an exception' do
+    expect { subject.parse(body_with_malformed_json) }.to raise_error(Her::Errors::ParseError, 'Response from the API must behave like a Hash or an Array (last JSON response was "wut.")')
+  end
+
+  it 'ensures that invalid JSON throws an exception' do
+    expect { subject.parse(body_with_invalid_json) }.to raise_error(Her::Errors::ParseError, 'Response from the API must behave like a Hash or an Array (last JSON response was "true")')
+  end
+
+  it 'ensures that a nil response returns an empty hash' do
+    subject.parse(nil_body)[:data].should eq({})
+  end
+
+  it 'ensures that an empty response returns an empty hash' do
+    subject.parse(empty_body)[:data].should eq({})
+  end
+
+  context 'with status code 204' do
+    it 'returns an empty body' do
+      env = { :status => 204 }
+      subject.on_complete(env)
+      env[:body].tap do |json|
+        json[:data].should == { }
+      end
+    end
+  end
+end

data/spec/middleware/second_level_parse_json_spec.rb

@@ -0,0 +1,35 @@
+# encoding: utf-8
+require "spec_helper"
+
+describe Her::Middleware::SecondLevelParseJSON do
+  subject { described_class.new }
+
+  context "with valid JSON body" do
+    let(:body) { "{\"data\": 1, \"errors\": 2, \"metadata\": 3}" }
+    it "parses body as json" do
+      subject.parse(body).tap do |json|
+        json[:data].should == 1
+        json[:errors].should == 2
+        json[:metadata].should == 3
+      end
+    end
+
+    it "parses :body key as json in the env hash" do
+      env = { :body => body }
+      subject.on_complete(env)
+      env[:body].tap do |json|
+        json[:data].should == 1
+        json[:errors].should == 2
+        json[:metadata].should == 3
+      end
+    end
+  end
+
+  context "with invalid JSON body" do
+    let(:body) { '"foo"' }
+    it 'ensures that invalid JSON throws an exception' do
+      expect { subject.parse(body) }.to raise_error(Her::Errors::ParseError, 'Response from the API must behave like a Hash or an Array (last JSON response was "\"foo\"")')
+    end
+  end
+
+end

data/spec/model/associations_spec.rb

@@ -0,0 +1,416 @@
+# encoding: utf-8
+require File.join(File.dirname(__FILE__), "../spec_helper.rb")
+
+describe Her::Model::Associations do
+  context "setting associations without details" do
+    before { spawn_model "Foo::User" }
+    subject { Foo::User.associations }
+
+    context "single has_many association" do
+      before { Foo::User.has_many :comments }
+      its([:has_many]) { should eql [{ :name => :comments, :data_key => :comments, :default => [], :class_name => "Comment", :path => "/comments", :inverse_of => nil }] }
+    end
+
+    context "multiple has_many associations" do
+      before do
+        Foo::User.has_many :comments
+        Foo::User.has_many :posts
+      end
+
+      its([:has_many]) { should eql [{ :name => :comments, :data_key => :comments, :default => [], :class_name => "Comment", :path => "/comments", :inverse_of => nil }, { :name => :posts, :data_key => :posts, :default => [], :class_name => "Post", :path => "/posts", :inverse_of => nil }] }
+    end
+
+    context "single has_one association" do
+      before { Foo::User.has_one :category }
+      its([:has_one]) { should eql [{ :name => :category, :data_key => :category, :default => nil, :class_name => "Category", :path => "/category" }] }
+    end
+
+    context "multiple has_one associations" do
+      before do
+        Foo::User.has_one :category
+        Foo::User.has_one :role
+      end
+
+      its([:has_one]) { should eql [{ :name => :category, :data_key => :category, :default => nil, :class_name => "Category", :path => "/category" }, { :name => :role, :data_key => :role, :default => nil, :class_name => "Role", :path => "/role" }] }
+    end
+
+    context "single belongs_to association" do
+      before { Foo::User.belongs_to :organization }
+      its([:belongs_to]) { should eql [{ :name => :organization, :data_key => :organization, :default => nil, :class_name => "Organization", :foreign_key => "organization_id", :path => "/organizations/:id" }] }
+    end
+
+    context "multiple belongs_to association" do
+      before do
+        Foo::User.belongs_to :organization
+        Foo::User.belongs_to :family
+      end
+
+      its([:belongs_to]) { should eql [{ :name => :organization, :data_key => :organization, :default => nil, :class_name => "Organization", :foreign_key => "organization_id", :path => "/organizations/:id" }, { :name => :family, :data_key => :family, :default => nil, :class_name => "Family", :foreign_key => "family_id", :path => "/families/:id" }] }
+    end
+  end
+
+  context "setting associations with details" do
+    before { spawn_model "Foo::User" }
+    subject { Foo::User.associations }
+
+    context "in base class" do
+      context "single has_many association" do
+        before { Foo::User.has_many :comments, :class_name => "Post", :inverse_of => :admin, :data_key => :user_comments, :default => {} }
+        its([:has_many]) { should eql [{ :name => :comments, :data_key => :user_comments, :default => {}, :class_name => "Post", :path => "/comments", :inverse_of => :admin }] }
+      end
+
+      context "single has_one association" do
+        before { Foo::User.has_one :category, :class_name => "Topic", :foreign_key => "topic_id", :data_key => :topic, :default => nil }
+        its([:has_one]) { should eql [{ :name => :category, :data_key => :topic, :default => nil, :class_name => "Topic", :foreign_key => "topic_id", :path => "/category" }] }
+      end
+
+      context "single belongs_to association" do
+        before { Foo::User.belongs_to :organization, :class_name => "Business", :foreign_key => "org_id", :data_key => :org, :default => true }
+        its([:belongs_to]) { should eql [{ :name => :organization, :data_key => :org, :default => true, :class_name => "Business", :foreign_key => "org_id", :path => "/organizations/:id" }] }
+      end
+    end
+
+    context "in parent class" do
+      before { Foo::User.has_many :comments, :class_name => "Post" }
+
+      describe "associations accessor" do
+        subject { Class.new(Foo::User).associations }
+        its(:object_id) { should_not eql Foo::User.associations.object_id }
+      its([:has_many]) { should eql [{ :name => :comments, :data_key => :comments, :default => [], :class_name => "Post", :path => "/comments", :inverse_of => nil }] }
+      end
+    end
+  end
+
+  context "handling associations without details" do
+    before do
+      Her::API.setup :url => "https://api.example.com" do |builder|
+        builder.use Her::Middleware::FirstLevelParseJSON
+        builder.use Faraday::Request::UrlEncoded
+        builder.adapter :test do |stub|
+          stub.get("/users/1") { |env| [200, {}, { :id => 1, :name => "Tobias Fünke", :comments => [{ :comment => { :id => 2, :body => "Tobias, you blow hard!", :user_id => 1 } }, { :comment => { :id => 3, :body => "I wouldn't mind kissing that man between the cheeks, so to speak", :user_id => 1 } }], :role => { :id => 1, :body => "Admin" }, :organization => { :id => 1, :name => "Bluth Company" }, :organization_id => 1 }.to_json] }
+          stub.get("/users/2") { |env| [200, {}, { :id => 2, :name => "Lindsay Fünke", :organization_id => 2 }.to_json] }
+          stub.get("/users/1/comments") { |env| [200, {}, [{ :comment => { :id => 4, :body => "They're having a FIRESALE?" } }].to_json] }
+          stub.get("/users/2/comments") { |env| [200, {}, [{ :comment => { :id => 4, :body => "They're having a FIRESALE?" } }, { :comment => { :id => 5, :body => "Is this the tiny town from Footloose?" } }].to_json] }
+          stub.get("/users/2/comments/5") { |env| [200, {}, { :comment => { :id => 5, :body => "Is this the tiny town from Footloose?" } }.to_json] }
+          stub.get("/users/2/role") { |env| [200, {}, { :id => 2, :body => "User" }.to_json] }
+          stub.get("/users/1/role") { |env| [200, {}, { :id => 3, :body => "User" }.to_json] }
+          stub.get("/users/1/posts") { |env| [200, {}, [{:id => 1, :body => 'blogging stuff', :admin_id => 1 }].to_json] }
+          stub.get("/organizations/1") { |env| [200, {}, { :organization =>  { :id => 1, :name => "Bluth Company Foo" } }.to_json] }
+          stub.post("/users") { |env| [200, {}, { :id => 5, :name => "Mr. Krabs", :comments => [{ :comment => { :id => 99, :body => "Rodríguez, nasibisibusi?", :user_id => 5 } }], :role => { :id => 1, :body => "Admin" }, :organization => { :id => 3, :name => "Krusty Krab" }, :organization_id => 3 }.to_json] }
+          stub.put("/users/5") { |env| [200, {}, { :id => 5, :name => "Clancy Brown", :comments => [{ :comment => { :id => 99, :body => "Rodríguez, nasibisibusi?", :user_id => 5 } }], :role => { :id => 1, :body => "Admin" }, :organization => { :id => 3, :name => "Krusty Krab" }, :organization_id => 3 }.to_json] }
+          stub.delete("/users/5") { |env| [200, {}, { :id => 5, :name => "Clancy Brown", :comments => [{ :comment => { :id => 99, :body => "Rodríguez, nasibisibusi?", :user_id => 5 } }], :role => { :id => 1, :body => "Admin" }, :organization => { :id => 3, :name => "Krusty Krab" }, :organization_id => 3 }.to_json] }
+
+          stub.get("/organizations/2") do |env|
+            if env[:params]["admin"] == "true"
+              [200, {}, { :organization => { :id => 2, :name => "Bluth Company (admin)" } }.to_json]
+            else
+              [200, {}, { :organization => { :id => 2, :name => "Bluth Company" } }.to_json]
+            end
+          end
+        end
+      end
+
+      spawn_model "Foo::User" do
+        has_many :comments, class_name: "Foo::Comment"
+        has_one :role
+        belongs_to :organization
+        has_many :posts, :inverse_of => :admin
+      end
+      spawn_model "Foo::Comment" do
+        belongs_to :user
+        parse_root_in_json true
+      end
+      spawn_model "Foo::Post" do
+        belongs_to :admin, :class_name => 'Foo::User'
+      end
+
+      spawn_model "Foo::Organization" do
+        parse_root_in_json true
+      end
+
+      spawn_model "Foo::Role"
+
+      @user_with_included_data = Foo::User.find(1)
+      @user_without_included_data = Foo::User.find(2)
+    end
+
+    let(:user_with_included_data_after_create) { Foo::User.create }
+    let(:user_with_included_data_after_save_existing) { Foo::User.save_existing(5, :name => "Clancy Brown") }
+    let(:user_with_included_data_after_destroy) { Foo::User.new(:id => 5).destroy }
+    let(:comment_without_included_parent_data) { Foo::Comment.new(:id => 7, :user_id => 1) }
+
+    it "maps an array of included data through has_many" do
+      @user_with_included_data.comments.first.should be_a(Foo::Comment)
+      @user_with_included_data.comments.length.should == 2
+      @user_with_included_data.comments.first.id.should == 2
+      @user_with_included_data.comments.first.body.should == "Tobias, you blow hard!"
+    end
+
+    it "does not refetch the parents models data if they have been fetched before" do
+      @user_with_included_data.comments.first.user.object_id.should == @user_with_included_data.object_id
+    end
+
+    it "does fetch the parent models data only once" do
+      comment_without_included_parent_data.user.object_id.should == comment_without_included_parent_data.user.object_id
+    end
+
+    it "does fetch the parent models data that was cached if called with parameters" do
+      comment_without_included_parent_data.user.object_id.should_not == comment_without_included_parent_data.user.where(:a => 2).object_id
+    end
+
+    it "uses the given inverse_of key to set the parent model" do
+      @user_with_included_data.posts.first.admin.object_id.should == @user_with_included_data.object_id
+    end
+
+    it "fetches data that was not included through has_many" do
+      @user_without_included_data.comments.first.should be_a(Foo::Comment)
+      @user_without_included_data.comments.length.should == 2
+      @user_without_included_data.comments.first.id.should == 4
+      @user_without_included_data.comments.first.body.should == "They're having a FIRESALE?"
+    end
+
+    it "fetches has_many data even if it was included, only if called with parameters" do
+      @user_with_included_data.comments.where(:foo_id => 1).length.should == 1
+    end
+
+    it "fetches data that was not included through has_many only once" do
+      @user_without_included_data.comments.first.object_id.should == @user_without_included_data.comments.first.object_id
+    end
+
+    it "fetches data that was cached through has_many if called with parameters" do
+      @user_without_included_data.comments.first.object_id.should_not == @user_without_included_data.comments.where(:foo_id => 1).first.object_id
+    end
+
+    it "maps an array of included data through has_one" do
+      @user_with_included_data.role.should be_a(Foo::Role)
+      @user_with_included_data.role.object_id.should == @user_with_included_data.role.object_id
+      @user_with_included_data.role.id.should == 1
+      @user_with_included_data.role.body.should == "Admin"
+    end
+
+    it "fetches data that was not included through has_one" do
+      @user_without_included_data.role.should be_a(Foo::Role)
+      @user_without_included_data.role.id.should == 2
+      @user_without_included_data.role.body.should == "User"
+    end
+
+    it "fetches has_one data even if it was included, only if called with parameters" do
+      @user_with_included_data.role.where(:foo_id => 2).id.should == 3
+    end
+
+    it "maps an array of included data through belongs_to" do
+      @user_with_included_data.organization.should be_a(Foo::Organization)
+      @user_with_included_data.organization.id.should == 1
+      @user_with_included_data.organization.name.should == "Bluth Company"
+    end
+
+    it "fetches data that was not included through belongs_to" do
+      @user_without_included_data.organization.should be_a(Foo::Organization)
+      @user_without_included_data.organization.id.should == 2
+      @user_without_included_data.organization.name.should == "Bluth Company"
+    end
+
+    it "fetches belongs_to data even if it was included, only if called with parameters" do
+      @user_with_included_data.organization.where(:foo_id => 1).name.should == "Bluth Company Foo"
+    end
+
+    it "can tell if it has a association" do
+      @user_without_included_data.has_association?(:unknown_association).should be false
+      @user_without_included_data.has_association?(:organization).should be true
+    end
+
+    it "fetches the resource corresponding to a named association" do
+      @user_without_included_data.get_association(:unknown_association).should be_nil
+      @user_without_included_data.get_association(:organization).name.should == "Bluth Company"
+    end
+
+    it "pass query string parameters when additional arguments are passed" do
+      @user_without_included_data.organization.where(:admin => true).name.should == "Bluth Company (admin)"
+      @user_without_included_data.organization.name.should == "Bluth Company"
+    end
+
+    it "fetches data with the specified id when calling find" do
+      comment = @user_without_included_data.comments.find(5)
+      comment.id.should eq(5)
+    end
+
+    it "'s associations responds to #empty?" do
+      @user_without_included_data.organization.respond_to?(:empty?).should be_truthy
+      @user_without_included_data.organization.should_not be_empty
+    end
+
+    it 'includes has_many relationships in params by default' do
+      params = @user_with_included_data.to_params
+      params[:comments].should be_kind_of(Array)
+      params[:comments].length.should eq(2)
+    end
+
+    [:create, :save_existing, :destroy].each do |type|
+      context "after #{type}" do
+        let(:subject) { self.send("user_with_included_data_after_#{type}")}
+
+        it "maps an array of included data through has_many" do
+          subject.comments.first.should be_a(Foo::Comment)
+          subject.comments.length.should == 1
+          subject.comments.first.id.should == 99
+          subject.comments.first.body.should == "Rodríguez, nasibisibusi?"
+        end
+
+        it "maps an array of included data through has_one" do
+          subject.role.should be_a(Foo::Role)
+          subject.role.id.should == 1
+          subject.role.body.should == "Admin"
+        end
+      end
+    end
+  end
+
+  context "handling associations with details" do
+    before do
+      Her::API.setup :url => "https://api.example.com" do |builder|
+        builder.use Her::Middleware::FirstLevelParseJSON
+        builder.use Faraday::Request::UrlEncoded
+        builder.adapter :test do |stub|
+          stub.get("/users/1") { |env| [200, {}, { :id => 1, :name => "Tobias Fünke", :organization => { :id => 1, :name => "Bluth Company Inc." }, :organization_id => 1 }.to_json] }
+          stub.get("/users/4") { |env| [200, {}, { :id => 1, :name => "Tobias Fünke", :organization => { :id => 1, :name => "Bluth Company Inc." } }.to_json] }
+          stub.get("/users/2") { |env| [200, {}, { :id => 2, :name => "Lindsay Fünke", :organization_id => 1 }.to_json] }
+          stub.get("/users/3") { |env| [200, {}, { :id => 2, :name => "Lindsay Fünke", :company => nil }.to_json] }
+          stub.get("/companies/1") { |env| [200, {}, { :id => 1, :name => "Bluth Company" }.to_json] }
+        end
+      end
+
+      spawn_model "Foo::User" do
+        belongs_to :company, :path => "/organizations/:id", :foreign_key => :organization_id, :data_key => :organization
+      end
+
+      spawn_model "Foo::Company"
+
+      @user_with_included_data = Foo::User.find(1)
+      @user_without_included_data = Foo::User.find(2)
+      @user_with_included_nil_data = Foo::User.find(3)
+      @user_with_included_data_but_no_fk = Foo::User.find(4)
+    end
+
+    it "maps an array of included data through belongs_to" do
+      @user_with_included_data.company.should be_a(Foo::Company)
+      @user_with_included_data.company.id.should == 1
+      @user_with_included_data.company.name.should == "Bluth Company Inc."
+    end
+
+    it "does not map included data if it’s nil" do
+      @user_with_included_nil_data.company.should be_nil
+    end
+
+    it "fetches data that was not included through belongs_to" do
+      @user_without_included_data.company.should be_a(Foo::Company)
+      @user_without_included_data.company.id.should == 1
+      @user_without_included_data.company.name.should == "Bluth Company"
+    end
+
+    it "does not require foreugn key to have nested object" do
+      @user_with_included_data_but_no_fk.company.name.should == "Bluth Company Inc."
+    end
+  end
+
+  context "object returned by the association method" do
+    before do
+      spawn_model "Foo::Role" do
+        def present?
+          "of_course"
+        end
+      end
+      spawn_model "Foo::User" do
+        has_one :role
+      end
+    end
+
+    let(:associated_value) { Foo::Role.new }
+    let(:user_with_role) do
+      Foo::User.new.tap { |user| user.role = associated_value }
+    end
+
+    subject { user_with_role.role }
+
+    it "doesnt mask the object's basic methods" do
+      subject.class.should == Foo::Role
+    end
+
+    it "doesnt mask core methods like extend" do
+      committer = Module.new
+      subject.extend  committer
+      associated_value.should be_kind_of committer
+    end
+
+    it "can return the association object" do
+      subject.association.should be_kind_of Her::Model::Associations::Association
+    end
+
+    it "still can call fetch via the association" do
+      subject.association.fetch.should eq associated_value
+    end
+
+    it "calls missing methods on associated value" do
+      subject.present?.should == "of_course"
+    end
+
+    it "can use association methods like where" do
+      subject.where(role: 'committer').association.
+        params.should include :role
+    end
+  end
+
+  context "building and creating association data" do
+    before do
+      spawn_model "Foo::Comment"
+      spawn_model "Foo::User" do
+        has_many :comments
+      end
+    end
+
+    context "with #build" do
+      it "takes the parent primary key" do
+        @comment = Foo::User.new(:id => 10).comments.build(:body => "Hello!")
+        @comment.body.should == "Hello!"
+        @comment.user_id.should == 10
+      end
+    end
+
+    context "with #create" do
+      before do
+        Her::API.setup :url => "https://api.example.com" do |builder|
+          builder.use Her::Middleware::FirstLevelParseJSON
+          builder.use Faraday::Request::UrlEncoded
+          builder.adapter :test do |stub|
+            stub.get("/users/10") { |env| [200, {}, { :id => 10 }.to_json] }
+            stub.post("/comments") { |env| [200, {}, { :id => 1, :body => Faraday::Utils.parse_query(env[:body])['body'], :user_id => Faraday::Utils.parse_query(env[:body])['user_id'].to_i }.to_json] }
+          end
+        end
+
+        Foo::User.use_api Her::API.default_api
+        Foo::Comment.use_api Her::API.default_api
+      end
+
+      it "takes the parent primary key and saves the resource" do
+        @user = Foo::User.find(10)
+        @comment = @user.comments.create(:body => "Hello!")
+        @comment.id.should == 1
+        @comment.body.should == "Hello!"
+        @comment.user_id.should == 10
+        @user.comments.should == [@comment]
+      end
+    end
+
+    context "with #new" do
+      it "creates nested models from hash attibutes" do
+        user = Foo::User.new(:name => "vic", :comments => [{:text => "hello"}])
+        user.comments.first.text.should == "hello"
+      end
+
+      it "assigns nested models if given as already constructed objects" do
+        bye = Foo::Comment.new(:text => "goodbye")
+        user = Foo::User.new(:name => 'vic', :comments => [bye])
+        user.comments.first.text.should == 'goodbye'
+      end
+    end
+  end
+end