force 0.0.1

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+require 'simplecov'
+SimpleCov.start
+
+require 'bundler/setup'
+Bundler.require :default, :test
+require 'faye' unless RUBY_PLATFORM == 'java'
+
+require 'webmock/rspec'
+
+WebMock.disable_net_connect!
+
+RSpec.configure do |config|
+  config.order = 'random'
+  config.filter_run :focus => true
+  config.run_all_when_everything_filtered = true
+end
+
+# Requires supporting ruby files with custom matchers and macros, etc,
+# in spec/support/ and its subdirectories.
+Dir[File.join(File.dirname(__FILE__), "support/**/*.rb")].each {|f| require f}

data/spec/support/client_integration.rb

@@ -0,0 +1,45 @@
+module ClientIntegrationExampleGroup
+  def self.included(base)
+    base.class_eval do
+      let(:oauth_token)    { '00Dx0000000BV7z!AR8AQAxo9UfVkh8AlV0Gomt9Czx9LjHnSSpwBMmbRcgKFmxOtvxjTrKW19ye6PE3Ds1eQz3z8jr3W7_VbWmEu4Q8TVGSTHxs' }
+      let(:refresh_token)  { 'refresh' }
+      let(:instance_url)   { 'https://na1.salesforce.com' }
+      let(:username)       { 'foo'            }
+      let(:password)       { 'bar'            }
+      let(:security_token) { 'security_token' }
+      let(:client_id)      { 'client_id'      }
+      let(:client_secret)  { 'client_secret'  }
+      let(:cache)          { nil }
+
+      let(:base_options) do
+        {
+          :oauth_token    => oauth_token,
+          :refresh_token  => refresh_token,
+          :instance_url   => instance_url,
+          :username       => username,
+          :password       => password,
+          :security_token => security_token,
+          :client_id      => client_id,
+          :client_secret  => client_secret,
+          :cache          => cache
+        }
+      end
+
+      let(:client_options) { base_options }
+
+      subject(:client) { described_class.new client_options }
+    end
+  end
+
+  RSpec.configure do |config|
+    config.include self,
+      :example_group => {
+        :describes => lambda { |described| described <= Force::AbstractClient },
+        :file_path => %r{spec/integration}
+      }
+
+    config.before :mashify => false do
+      client.middleware.delete(Force::Middleware::Mashify)
+    end
+  end
+end

data/spec/support/concerns.rb

@@ -0,0 +1,18 @@
+module ConcernsExampleGroup
+  def self.included(base)
+    base.class_eval do
+      let(:klass) do
+        context = self
+        Class.new { include context.described_class }
+      end
+
+      let(:client) { klass.new }
+
+      subject { client }
+    end
+  end
+
+  RSpec.configure do |config|
+    config.include self, :example_group => { :file_path => %r{spec/unit/concerns} }
+  end
+end

data/spec/support/event_machine.rb

@@ -0,0 +1,14 @@
+RSpec.configure do |config|
+  config.before do
+    EventMachine.stub(:connect) if defined?(EventMachine)
+  end
+
+  config.filter_run_excluding :event_machine => true if RUBY_PLATFORM == 'java'
+
+  config.around :event_machine => true do |example|
+    EM.run {
+      example.run
+      EM.stop
+    }
+  end
+end

data/spec/support/fixture_helpers.rb

@@ -0,0 +1,45 @@
+module FixtureHelpers
+  module InstanceMethods
+
+    def stub_api_request(endpoint, options={})
+      options = {
+        :method => :get,
+        :status => 200,
+        :api_version => Force.configuration.api_version
+      }.merge(options)
+
+      stub = stub_request(options[:method], %r{/services/data/v#{options[:api_version]}/#{endpoint}})
+      stub = stub.with(:body => options[:with_body]) if options[:with_body] && !RUBY_VERSION.match(/^1.8/)
+      stub = stub.to_return(:status => options[:status], :body => fixture(options[:fixture]), :headers => { 'Content-Type' => 'application/json'}) if options[:fixture]
+      stub
+    end
+
+    def stub_login_request(options={})
+      stub = stub_request(:post, "https://login.salesforce.com/services/oauth2/token")
+      stub = stub.with(:body => options[:with_body]) if options[:with_body] && !RUBY_VERSION.match(/^1.8/)
+      stub
+    end
+
+    def fixture(f)
+      File.read(File.expand_path("../../fixtures/#{f}.json", __FILE__))
+    end
+
+  end
+
+  module ClassMethods
+    def requests(endpoint, options={})
+      before do
+        (@requests ||= []) << stub_api_request(endpoint, options)
+      end
+
+      after do
+        @requests.each { |request| expect(request).to have_been_requested }
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include FixtureHelpers::InstanceMethods
+  config.extend FixtureHelpers::ClassMethods
+end

data/spec/support/matchers.rb

@@ -0,0 +1,11 @@
+RSpec::Matchers.define :include_picklist_values do |expected|
+  match do |actual|
+    actual.all? { |picklist_value| expected.include? picklist_value['value'] }
+  end
+end
+
+RSpec::Matchers.define :have_client do |expected|
+  match do |actual|
+    actual.instance_variable_get(:@client) == expected
+  end
+end

data/spec/support/middleware.rb

@@ -0,0 +1,76 @@
+module MiddlewareExampleGroup
+  def self.included(base)
+    base.class_eval do
+      let(:app)            { double('@app', :call => nil)            }
+      let(:env)            { { :request_headers => {}, :response_headers => {} } }
+      let(:retries)        { 3 }
+      let(:options)        { { } }
+      let(:client)         { double(Force::AbstractClient) }
+      let(:auth_callback)  { double(Proc) }
+      let(:success_response) { Force::Mash.new(JSON.parse(fixture(:auth_success_response))) }
+      subject(:middleware) { described_class.new app, client, options }
+    end
+  end
+
+  RSpec.configure do |config|
+    config.include self,
+      :example_group => { :file_path => %r{spec/unit/middleware} }
+  end
+end
+
+shared_examples_for 'authentication middleware' do
+  describe '.authenticate!' do
+    after do
+      request.should have_been_requested
+    end
+
+    context 'when successful' do
+      let!(:request) { success_request }
+
+      describe '@options' do
+        subject { options }
+
+        before do
+          middleware.authenticate!
+        end
+
+        its([:instance_url]) { should eq 'https://na1.salesforce.com' }
+        its([:oauth_token])  { should eq '00Dx0000000BV7z!AR8AQAxo9UfVkh8AlV0Gomt9Czx9LjHnSSpwBMmbRcgKFmxOtvxjTrKW19ye6PE3Ds1eQz3z8jr3W7_VbWmEu4Q8TVGSTHxs' }
+      end
+
+      context 'when an authentication_callback is specified' do
+        before(:each) do
+          options.merge!(:authentication_callback => auth_callback)
+        end
+
+        it 'calls the authentication callback with the response body' do
+          auth_callback.should_receive(:call).with(success_response)
+          middleware.authenticate!
+        end
+      end
+    end
+
+    context 'when unsuccessful' do
+      let!(:request) { fail_request }
+
+      it 'raises an exception' do
+        expect {
+          middleware.authenticate!
+        }.to raise_error Force::AuthenticationError, /^invalid_grant: .*/
+      end
+
+      context 'when an authentication_callback is specified' do
+        before(:each) do
+          options.merge!(:authentication_callback => auth_callback)
+        end
+
+        it 'does not call the authentication callback' do
+          auth_callback.should_not_receive(:call)
+          expect do
+            middleware.authenticate!
+          end.to raise_error
+        end
+      end
+    end
+  end
+end

data/spec/support/mock_cache.rb

@@ -0,0 +1,13 @@
+class MockCache
+  def initialize
+    @storage = {}
+  end
+
+  def fetch(key, &block)
+    @storage[key] ||= block.call
+  end
+
+  def delete(key)
+    @storage.delete(key)
+  end
+end

data/spec/unit/abstract_client_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe Force::AbstractClient do
+  subject { described_class }
+
+  it { should < Force::Concerns::Base }
+  it { should < Force::Concerns::Connection }
+  it { should < Force::Concerns::Authentication }
+  it { should < Force::Concerns::Caching }
+  it { should < Force::Concerns::API }
+end

data/spec/unit/attachment_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+describe Force::Attachment do
+  let(:client)   { double(Force::AbstractClient) }
+  let(:body_url) { '/services/data/v26.0/sobjects/Attachment/00PG0000006Hll5MAC/Body' }
+  let(:hash)     { { 'Id' => '1234', 'Body' => body_url } }
+  let(:sobject)  { described_class.new(hash, client) }
+
+  describe '.Body' do
+    it 'requests the body' do
+      client.should_receive(:get).with(body_url).and_return(double('response').as_null_object)
+      sobject.Body
+    end
+  end
+end

data/spec/unit/collection_spec.rb

@@ -0,0 +1,52 @@
+require 'spec_helper'
+
+describe Force::Collection do
+  let(:client) { double(Force::AbstractClient) }
+
+  describe '#new' do
+    context 'without pagination' do
+      subject(:collection) do
+        described_class.new(JSON.parse(fixture('sobject/query_success_response')), client)
+      end
+
+      it                   { should respond_to :each }
+      its(:size)           { should eq 1 }
+      its(:has_next_page?) { should be_false }
+      it                   { should have_client client }
+
+      describe 'each record' do
+        it { should be_all { |record| expect(record).to be_a Force::SObject } }
+      end
+    end
+
+    context 'with pagination' do
+      let(:first_page)     { JSON.parse(fixture('sobject/query_paginated_first_page_response')) }
+      let(:next_page)      { JSON.parse(fixture('sobject/query_paginated_last_page_response')) }
+      subject(:collection) { described_class.new(first_page, client) }
+
+      it { should respond_to :each }
+      it { should have_client client }
+
+      context 'when only values from the first page are being requested' do
+        before { client.should_receive(:get).never }
+
+        its(:size)  { should eq 2 }
+        its(:first) { should be_a Force::SObject }
+        its(:current_page) { should be_a Array }
+        its(:current_page) { should have(1).element }
+      end
+
+      context 'when all of the values are being requested' do
+        before do
+          client.stub(:get).
+            and_return(double(:body => Force::Collection.new(next_page, client)))
+        end
+
+        its(:pages)          { should be_all { |page| expect(page).to be_a Force::Collection } }
+        its(:has_next_page?) { should be_true }
+        it { should be_all   { |record| expect(record).to be_a Force::SObject } }
+        its(:next_page)      { should be_a Force::Collection }
+      end
+    end
+  end
+end

data/spec/unit/concerns/api_spec.rb

@@ -0,0 +1,244 @@
+require 'spec_helper'
+
+describe Force::Concerns::API do
+  let(:response) { double('Faraday::Response', :body => double('Body')) }
+
+  describe '.list_sobjects' do
+    subject { client.list_sobjects }
+
+    before do
+      client.stub :describe => [ { 'name' => 'foo' } ]
+    end
+
+    it { should eq ['foo'] }
+  end
+
+  describe '.describe' do
+    subject(:describe) { client.describe }
+
+    it 'returns the global describe' do
+      sobjects = double('sobjects')
+      response.body.stub(:[]).with('sobjects').and_return(sobjects)
+      client.should_receive(:api_get).
+        with('sobjects').
+        and_return(response)
+      expect(describe).to eq sobjects
+    end
+
+    context 'when given the name of an sobject' do
+      subject(:describe) { client.describe('Whizbang') }
+
+      it 'returns the full describe' do
+        client.should_receive(:api_get).
+          with('sobjects/Whizbang/describe').
+          and_return(response)
+        expect(describe).to eq response.body
+      end
+    end
+  end
+
+  describe '.describe_layouts' do
+    subject(:describe_layouts) { client.describe_layouts('Whizbang') }
+
+    it 'returns the layouts for the sobject' do
+      client.should_receive(:api_get).
+        with('sobjects/Whizbang/describe/layouts').
+        and_return(response)
+      expect(describe_layouts).to eq response.body
+    end
+
+    context 'when given the id of a layout' do
+      subject(:describe_layouts) { client.describe_layouts('Whizbang', '012E0000000RHEp') }
+
+      it 'returns the describe for the specified layout' do
+        client.should_receive(:api_get).
+          with('sobjects/Whizbang/describe/layouts/012E0000000RHEp').
+          and_return(response)
+        expect(describe_layouts).to eq response.body
+      end
+    end
+  end
+
+  describe '.org_id' do
+    subject(:org_id) { client.org_id }
+
+    it 'returns the organization id' do
+      organizations = [ { 'Id' => 'foo' } ]
+      client.should_receive(:query).
+        with('select id from Organization').
+        and_return(organizations)
+      expect(org_id).to eq 'foo'
+    end
+  end
+
+  describe '.query' do
+    let(:soql)        { 'Select Id from Account' }
+    subject(:results) { client.query(soql) }
+
+    context 'with mashify middleware' do
+      before do
+        client.stub :mashify? => true
+      end
+
+      it 'returns the body' do
+        client.should_receive(:api_get).
+          with('query', :q => soql).
+          and_return(response)
+        expect(results).to eq response.body
+      end
+    end
+
+    context 'without mashify middleware' do
+      before do
+        client.stub :mashify? => false
+      end
+
+      it 'returns the records attribute of the body' do
+        records = double('records')
+        response.body.stub(:[]).
+          with('records').
+          and_return(records)
+        client.should_receive(:api_get).
+          with('query', :q => soql).
+          and_return(response)
+        expect(results).to eq records
+      end
+    end
+  end
+
+  describe '.search' do
+    let(:sosl)        { 'FIND {bar}' }
+    subject(:results) { client.search(sosl) }
+
+    it 'performs a sosl search' do
+      client.should_receive(:api_get).
+        with('search', :q => sosl).
+        and_return(response)
+      expect(results).to eq response.body
+    end
+  end
+
+  [:create, :update, :upsert, :destroy].each do |method|
+    describe ".#{method}" do
+      let(:args)       { [] }
+      subject(:result) { client.send(method, *args) }
+
+      it "delegates to :#{method}!" do
+        client.should_receive(:"#{method}!").
+          with(*args).
+          and_return(response)
+        expect(result).to eq response
+      end
+
+      it 'rescues exceptions' do
+        [Faraday::Error::ClientError].each do |exception_klass|
+          client.should_receive(:"#{method}!").
+            with(*args).
+            and_raise(exception_klass.new(nil))
+          expect(result).to eq false
+        end
+      end
+    end
+  end
+
+  describe '.create!' do
+    let(:sobject)    { 'Whizbang' }
+    let(:attrs)      { Hash.new }
+    subject(:result) { client.create!(sobject, attrs) }
+
+    it 'send an HTTP POST, and returns the id of the record' do
+      response.body.stub(:[]).with('id').and_return('1234')
+      client.should_receive(:api_post).
+        with('sobjects/Whizbang', attrs).
+        and_return(response)
+      expect(result).to eq '1234'
+    end
+  end
+
+  describe '.update!' do
+    let(:sobject)    { 'Whizbang' }
+    let(:attrs)      { Hash.new }
+    subject(:result) { client.update!(sobject, attrs) }
+
+    context 'when the id field is present' do
+      let(:attrs) { { :id => '1234' } }
+
+      it 'sends an HTTP PATCH, and returns true' do
+        client.should_receive(:api_patch).
+          with('sobjects/Whizbang/1234', attrs)
+        expect(result).to be_true
+      end
+    end
+
+    context 'when the id field is missing from the attrs' do
+      subject { lambda { result }}
+      it { should raise_error ArgumentError, 'Id field missing from attrs.' }
+    end
+  end
+
+  describe '.upsert!' do
+    let(:sobject)    { 'Whizbang' }
+    let(:field)      { :External_ID__c }
+    let(:attrs)      { { 'External_ID__c' => '1234' } }
+    subject(:result) { client.upsert!(sobject, field, attrs) }
+
+    context 'when the record is found and updated' do
+      it 'returns true' do
+        response.body.stub :[]
+        client.should_receive(:api_patch).
+          with('sobjects/Whizbang/External_ID__c/1234', {}).
+          and_return(response)
+        expect(result).to be_true
+      end
+    end
+
+    context 'when the record is found and created' do
+      it 'returns the id of the record' do
+        response.body.stub(:[]).with('id').and_return('4321')
+        client.should_receive(:api_patch).
+          with('sobjects/Whizbang/External_ID__c/1234', {}).
+          and_return(response)
+        expect(result).to eq '4321'
+      end
+    end
+  end
+
+  describe '.destroy!' do
+    let(:id)         { '1234' }
+    let(:sobject)    { 'Whizbang' }
+    subject(:result) { client.destroy!(sobject, id) }
+
+    it 'sends and HTTP delete, and returns true' do
+      client.should_receive(:api_delete).
+        with('sobjects/Whizbang/1234')
+      expect(result).to be_true
+    end
+  end
+
+  describe '.find' do
+    let(:sobject)    { 'Whizbang' }
+    let(:id)         { '1234' }
+    let(:field)      { nil }
+    subject(:result) { client.find(sobject, id, field) }
+
+    context 'when no external id is specified' do
+      it 'returns the full representation of the object' do
+        client.should_receive(:api_get).
+          with('sobjects/Whizbang/1234').
+          and_return(response)
+        expect(result).to eq response.body
+      end
+    end
+
+    context 'when an external id is specified' do
+      let(:field) { :External_ID__c }
+
+      it 'returns the full representation of the object' do
+        client.should_receive(:api_get).
+          with('sobjects/Whizbang/External_ID__c/1234').
+          and_return(response)
+        expect(result).to eq response.body
+      end
+    end
+  end
+end