yt-andrewroth 0.25.5.1

data/spec/requests/as_content_owner/claim_history_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+require 'yt/models/claim'
+require 'yt/models/claim_history'
+
+describe Yt::ClaimHistory, :partner do
+  subject(:claim) { Yt::Claim.new id: asset_id, auth: $content_owner }
+
+  context 'given a claim previously administered by the authenticated Content Owner' do
+    let(:asset_id) { ENV['YT_TEST_CLAIM_ID'] }
+
+    describe 'the claim history can be obtained' do
+      it { expect(claim.claim_history.events.size > 0).to eq true }
+    end
+
+    describe 'the claim_create event' do
+      let(:claim_create_event) { claim.claim_history.events.find {|e| e.type == 'claim_create'} }
+      it { expect(claim_create_event.time).to be_a Time }
+    end
+  end
+end

data/spec/requests/as_content_owner/content_owner_spec.rb

@@ -0,0 +1,241 @@
+require 'spec_helper'
+require 'yt/models/content_owner'
+
+describe Yt::ContentOwner, :partner do
+  describe '.partnered_channels' do
+    let(:partnered_channels) { $content_owner.partnered_channels }
+
+    specify '.first' do
+      expect(partnered_channels.first).to be_a Yt::Channel
+    end
+
+    specify '.size', :ruby2 do
+      expect(partnered_channels.size).to be > 0
+    end
+  end
+
+  describe 'claims' do
+    let(:asset_id) { ENV['YT_TEST_PARTNER_ASSET_ID'] }
+    let(:video_id) { ENV['YT_TEST_PARTNER_CLAIMABLE_VIDEO_ID'] }
+    let(:options) { {asset_id: asset_id, video_id: video_id, content_type: 'audiovisual'} }
+
+    context 'given an existing policy ID' do
+      let(:policy_id) { ENV['YT_TEST_PARTNER_POLICY_ID'] }
+      let(:params) { options.merge policy_id: policy_id }
+
+      specify 'can be added' do
+        begin
+          expect($content_owner.create_claim params).to be_a Yt::Claim
+        rescue Yt::Errors::RequestError => e
+          # @note: Every time this test runs, a claim is inserted for the same
+          #   video and asset, but YouTube does not allow this, and responds with
+          #   an error message like "Video is already claimed. Existing claims
+          #   on this video: AbCdEFg1234".
+          #   For the sake of testing, we delete the duplicate and try again.
+          raise unless e.reasons.include? 'alreadyClaimed'
+          id = e.kind['message'].match(/this video: (.*?)$/) {|re| re[1]}
+          Yt::Claim.new(id: id, auth: $content_owner).delete
+          expect($content_owner.create_claim params).to be_a Yt::Claim
+        end
+      end
+    end
+
+    context 'given a new policy' do
+      let(:params) { options.merge policy: {rules: [action: :block]} }
+
+      specify 'can be added' do
+        begin
+          expect($content_owner.create_claim params).to be_a Yt::Claim
+        rescue Yt::Errors::RequestError => e
+          # @note: Every time this test runs, a claim is inserted for the same
+          #   video and asset, but YouTube does not allow this, and responds with
+          #   an error message like "Video is already claimed. Existing claims
+          #   on this video: AbCdEFg1234".
+          #   For the sake of testing, we delete the duplicate and try again.
+          raise unless e.reasons.include? 'alreadyClaimed'
+          id = e.kind['message'].match(/this video: (.*?)$/) {|re| re[1]}
+          Yt::Claim.new(id: id, auth: $content_owner).delete
+          expect($content_owner.create_claim params).to be_a Yt::Claim
+        end
+      end
+    end
+  end
+
+  describe '.claims' do
+    describe 'given the content owner has claims' do
+      let(:claim) { $content_owner.claims.first }
+
+      it 'returns valid metadata' do
+        expect(claim.id).to be_a String
+        expect(claim.asset_id).to be_a String
+        expect(claim.video_id).to be_a String
+        expect(claim.status).to be_a String
+        expect(claim.content_type).to be_a String
+        expect(claim.created_at).to be_a Time
+        expect(claim).not_to be_third_party
+      end
+    end
+
+    describe '.where(id: claim_id)' do
+      let(:count) { $content_owner.claims.where(id: claim_id).count }
+
+      context 'given the ID of a claim administered by the content owner' do
+        let(:claim_id) { ENV['YT_TEST_PARTNER_CLAIM_ID'] }
+        it { expect(count).to be > 0 }
+      end
+
+      context 'given an unknown claim ID' do
+        let(:claim_id) { '--not-a-matching-claim-id--' }
+        it { expect(count).to be_zero }
+      end
+    end
+
+    describe '.where(asset_id: asset_id)' do
+      let(:count) { $content_owner.claims.where(asset_id: asset_id).count }
+
+      context 'given the asset ID of a claim administered by the content owner' do
+        let(:asset_id) { ENV['YT_TEST_PARTNER_ASSET_WITH_CLAIM_ID'] }
+        it { expect(count).to be > 0 }
+      end
+
+      context 'given an unknown asset ID' do
+        let(:asset_id) { 'A123456789012345' }
+        it { expect(count).to be_zero }
+      end
+    end
+
+    describe '.where(video_id: video_id)' do
+      let(:count) { $content_owner.claims.where(video_id: video_id).count }
+
+      context 'given the video ID of a claim administered by the content owner' do
+        let(:video_id) { ENV['YT_TEST_PARTNER_VIDEO_ID'] }
+        it { expect(count).to be > 0 }
+      end
+    end
+
+    describe '.where(q: query)' do
+      let(:first) { $content_owner.claims.where(params).first }
+
+      context 'given a query matching the title of a video of a claim administered by the content owner' do
+        let(:query) { ENV['YT_TEST_PARTNER_Q'] }
+
+        context 'given no optional filters' do
+          let(:params) { {q: query} }
+          it { expect(first).to be }
+        end
+
+        context 'given an optional filter that does not include that video' do
+          let(:remote_date) { '2008-01-01T00:00:00.000Z' }
+
+          describe 'applies the filter if the filter name is under_scored' do
+            let(:params) { {q: query, created_before: remote_date} }
+            it { expect(first).not_to be }
+          end
+
+          describe 'applies the filter if the filter name is camelCased' do
+            let(:params) { {q: query, createdBefore: remote_date} }
+            it { expect(first).not_to be }
+          end
+        end
+      end
+
+      context 'given an unknown video ID' do
+        let(:params) { {q: '--not-a-matching-query--'} }
+        it { expect(first).not_to be }
+      end
+    end
+  end
+
+  describe 'references' do
+    let(:claim_id) { ENV['YT_TEST_PARTNER_REFERENCE_CLAIM_ID'] }
+    let(:content_type) { ENV['YT_TEST_PARTNER_REFERENCE_CONTENT_TYPE'] }
+    let(:params) { {claim_id: claim_id, content_type: content_type} }
+
+    specify 'can be added' do
+      begin
+        expect($content_owner.create_reference params).to be_a Yt::Reference
+      rescue Yt::Errors::RequestError => e
+        # @note: Every time this test runs, a reference is inserted for the
+        #   same claim, but YouTube does not allow this, and responds with an
+        #   error message like "You attempted to create a reference using the
+        #   content of a previously claimed video, but such a reference already
+        #   exists. The ID of the duplicate reference is xhpACYclOdc."
+        #   For the sake of testing, we delete the duplicate and try again.
+        # @note: Deleting a reference does not work if the reference status is
+        #   "checking" or "pending" and it can take up to 4 minutes for a new
+        #   reference to be checked. The +sleep+ statement takes care of this
+        #   case in the only way allowed by YouTube: sadly waiting.
+        raise unless e.reasons.include? 'referenceAlreadyExists'
+        id = e.kind['message'].match(/reference is (.*?)\.$/) {|re| re[1]}
+        sleep 15 until Yt::Reference.new(id: id, auth: $content_owner).delete
+        expect($content_owner.create_reference params).to be_a Yt::Reference
+      end
+    end
+  end
+
+  describe '.references' do
+    describe '.where(id: reference_id)' do
+      let(:reference) { $content_owner.references.where(id: reference_id).first }
+
+      context 'given the ID of a reference administered by the content owner' do
+        let(:reference_id) { ENV['YT_TEST_PARTNER_REFERENCE_ID'] }
+
+        it 'returns valid metadata' do
+          expect(reference.id).to be_a String
+          expect(reference.asset_id).to be_a String
+          expect(reference.length).to be_a Float
+          expect(reference.video_id).to be_a String
+          expect(reference.claim_id).to be_a String
+          expect(reference.audioswap_enabled?).to be_in [true, false]
+          expect(reference.ignore_fp_match?).to be_in [true, false]
+          expect(reference.urgent?).to be_in [true, false]
+          expect(reference.status).to be_a String
+          expect(reference.content_type).to be_a String
+        end
+      end
+
+      context 'given an unknown reference ID' do
+        let(:reference_id) { '--not-a-matching-reference-id--' }
+        it { expect(reference).not_to be }
+      end
+    end
+  end
+
+  describe '.policies' do
+    describe 'given the content owner has policies' do
+      let(:policy) { $content_owner.policies.first }
+      let(:rule) { policy.rules.first }
+
+      it 'returns valid metadata' do
+        expect(policy.id).to be_a String
+        expect(policy.name).to be_a String
+        expect(policy.updated_at).to be_a Time
+        expect(rule.action).to  be_a String
+        expect(rule.included_territories).to be_an Array
+        expect(rule.excluded_territories).to be_an Array
+        expect(rule.match_duration).to be_an Array
+        expect(rule.match_percent).to be_an Array
+        expect(rule.reference_duration).to be_an Array
+        expect(rule.reference_percent).to be_an Array
+      end
+    end
+
+    describe '.where(id: policy_id) given an unknown policy ID' do
+      let(:policy) { $content_owner.policies.where(id: policy_id).first }
+      let(:policy_id) { '--not-a-matching-reference-id--' }
+      it { expect(policy).not_to be }
+    end
+  end
+
+  # @note: The following test works, but YouTube API endpoint to mark
+  #   an asset as 'invalid' (soft-delete) does not work, and apparently
+  #   there is no way to update the status of a asset.
+  #   Therefore, the test is commented out, otherwise a new asset would
+  #   be created every time the test is run.
+  # describe 'assets can be added' do
+  #   let(:params) { {type: 'web', metadata_mine: {title: "Test Asset Title"}} }
+  #   before { @asset = $content_owner.create_asset params }
+  #   after { @asset.delete } # This does not seem to work
+  #   it { expect(@asset).to be_a Yt::Asset }
+  # end
+end

data/spec/requests/as_content_owner/match_policy_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+require 'yt/models/match_policy'
+
+describe Yt::MatchPolicy, :partner do
+  subject(:match_policy) { Yt::MatchPolicy.new asset_id: asset_id, auth: $content_owner }
+
+  context 'given an asset managed by the authenticated Content Owner' do
+    before { Yt::Ownership.new(asset_id: asset_id, auth: $content_owner).obtain! }
+    let(:asset_id) { ENV['YT_TEST_PARTNER_ASSET_ID'] }
+
+    describe 'the asset match policy can be updated' do
+      let(:policy_id) { ENV['YT_TEST_PARTNER_POLICY_ID'] }
+
+      it { expect(match_policy.update policy_id: policy_id).to be true }
+    end
+  end
+end

data/spec/requests/as_content_owner/ownership_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+require 'yt/models/ownership'
+
+describe Yt::Ownership, :partner do
+  subject(:ownership) { Yt::Ownership.new asset_id: asset_id, auth: $content_owner }
+
+  context 'given an asset managed by the authenticated Content Owner' do
+    let(:asset_id) { ENV['YT_TEST_PARTNER_ASSET_ID'] }
+
+    describe 'the ownership can be updated' do
+      let(:general_owner) { {ratio: 100, owner: 'FullScreen', type: 'include', territories: ['US', 'CA']} }
+      it { expect(ownership.update general: [general_owner]).to be true }
+    end
+
+    describe 'the complete ownership can be obtained' do
+      before { ownership.release! }
+      it { expect(ownership.obtain!).to be true }
+    end
+
+    describe 'the complete ownership can be released' do
+      after { ownership.obtain! }
+      it { expect(ownership.release!).to be true }
+    end
+  end
+end

data/spec/requests/as_content_owner/playlist_spec.rb

@@ -0,0 +1,782 @@
+# encoding: UTF-8
+require 'spec_helper'
+require 'yt/models/channel'
+require 'yt/models/playlist'
+
+describe Yt::Playlist, :partner do
+  subject(:playlist) { Yt::Playlist.new id: id, auth: $content_owner }
+
+  context 'given a playlist of a partnered channel', :partner do
+    context 'managed by the authenticated Content Owner' do
+      let(:id) { ENV['YT_TEST_PARTNER_PLAYLIST_ID'] }
+
+      describe 'multiple reports can be retrieved at once' do
+        metrics = {views: Integer, estimated_minutes_watched: Integer,
+         average_view_duration: Integer, playlist_starts: Integer,
+         average_time_in_playlist: Float, views_per_playlist_start: Float}
+
+        specify 'by day' do
+          range = {since: 5.days.ago.to_date, until: 3.days.ago.to_date}
+          result = playlist.reports range.merge(only: metrics, by: :day)
+          metrics.each do |metric, type|
+            expect(result[metric].keys).to all(be_a Date)
+            expect(result[metric].values).to all(be_a type)
+          end
+        end
+
+        specify 'by month' do
+          result = playlist.reports only: metrics, by: :month, since: 1.month.ago
+          metrics.each do |metric, type|
+            expect(result[metric].keys).to all(be_a Range)
+            expect(result[metric].keys.map &:first).to all(be_a Date)
+            expect(result[metric].keys.map &:first).to eq result[metric].keys.map(&:first).map(&:beginning_of_month)
+            expect(result[metric].keys.map &:last).to all(be_a Date)
+            expect(result[metric].keys.map &:last).to eq result[metric].keys.map(&:last).map(&:end_of_month)
+            expect(result[metric].values).to all(be_a type)
+          end
+        end
+
+        specify 'by week' do
+          range = {since: ENV['YT_TEST_PARTNER_VIDEO_DATE'], until: Date.parse(ENV['YT_TEST_PARTNER_VIDEO_DATE']) + 9}
+          result = playlist.reports range.merge(only: metrics, by: :week)
+          metrics.each do |metric, type|
+            expect(result[metric].size).to be <= 2
+            expect(result[metric].keys).to all(be_a Range)
+            expect(result[metric].keys.map{|range| range.first.wday}.uniq).to be_one
+            expect(result[metric].keys.map{|range| range.last.wday}.uniq).to be_one
+            expect(result[metric].values).to all(be_a type)
+          end
+        end
+      end
+
+      {views: Integer, estimated_minutes_watched: Integer,
+       average_view_duration: Integer, playlist_starts: Integer,
+       average_time_in_playlist: Float,
+       views_per_playlist_start: Float}.each do |metric, type|
+        describe "#{metric} can be retrieved for a range of days" do
+          let(:date_in) { ENV['YT_TEST_PARTNER_VIDEO_DATE'] }
+          let(:date_out) { Date.parse(ENV['YT_TEST_PARTNER_VIDEO_DATE']) + 5 }
+          let(:metric) { metric }
+          let(:result) { playlist.public_send metric, options }
+
+          context 'with a given start and end (:since/:until option)' do
+            let(:options) { {by: :day, since: date_in, until: date_out} }
+            specify do
+              expect(result.keys.min).to eq date_in.to_date
+              expect(result.keys.max).to eq date_out.to_date
+            end
+          end
+
+          context 'with a given start and end (:from/:to option)' do
+            let(:options) { {by: :day, from: date_in, to: date_out} }
+            specify do
+              expect(result.keys.min).to eq date_in.to_date
+              expect(result.keys.max).to eq date_out.to_date
+            end
+          end
+        end
+
+        describe "#{metric} can be grouped by month" do
+          let(:metric) { metric }
+          let(:result) { playlist.public_send metric, by: :month, since: 1.month.ago }
+          specify do
+            expect(result.keys).to all(be_a Range)
+            expect(result.keys.map &:first).to all(be_a Date)
+            expect(result.keys.map &:first).to eq result.keys.map(&:first).map(&:beginning_of_month)
+            expect(result.keys.map &:last).to all(be_a Date)
+            expect(result.keys.map &:last).to eq result.keys.map(&:last).map(&:end_of_month)
+          end
+        end
+
+        describe "#{metric} can be grouped by week and returns non-overlapping periods" do
+          let(:metric) { metric }
+          let(:range) { {since: ENV['YT_TEST_PARTNER_VIDEO_DATE'], until: Date.parse(ENV['YT_TEST_PARTNER_VIDEO_DATE']) + 9} }
+          let(:result) { playlist.public_send metric, range.merge(by: :week)}
+          specify do
+            expect(result.size).to be <= 2
+            expect(result.keys).to all(be_a Range)
+            expect(result.keys.map{|range| range.first.wday}.uniq).to be_one
+            expect(result.keys.map{|range| range.last.wday}.uniq).to be_one
+          end
+        end
+
+        describe "#{metric} can be retrieved for a specific day" do
+          let(:metric) { metric }
+          let(:result) { playlist.public_send "#{metric}_on", date }
+
+          context 'in which the playlist had data' do
+            let(:date) { ENV['YT_TEST_PARTNER_VIDEO_DATE'] }
+            it { expect(result).to be_a type }
+          end
+
+          context 'in the future' do
+            let(:date) { 5.days.from_now }
+            it { expect(result).to be_nil }
+          end
+        end
+
+        describe "#{metric} can be grouped by range" do
+          let(:metric) { metric }
+
+          context 'without a :by option (default)' do
+            let(:result) { playlist.public_send metric }
+            specify do
+              expect(result.size).to be 1
+              expect(result[:total]).to be_a type
+            end
+          end
+
+          context 'with the :by option set to :range' do
+            let(:result) { playlist.public_send metric, by: :range }
+            specify do
+              expect(result.size).to be 1
+              expect(result[:total]).to be_a type
+            end
+          end
+        end
+
+        describe "#{metric} can be retrieved for a single country" do
+          let(:result) { playlist.public_send metric, options }
+
+          context 'and grouped by day' do
+            let(:date_in) { 5.days.ago }
+            let(:options) { {by: :day, since: date_in, in: location} }
+
+            context 'with the :in option set to the country code' do
+              let(:location) { 'US' }
+              it { expect(result.keys.min).to eq date_in.to_date }
+            end
+
+            context 'with the :in option set to {country: country code}' do
+              let(:location) { {country: 'US'} }
+              it { expect(result.keys.min).to eq date_in.to_date }
+            end
+          end
+
+          context 'and grouped by country' do
+            let(:options) { {by: :country, in: location} }
+
+            context 'with the :in option set to the country code' do
+              let(:location) { 'US' }
+              it { expect(result.keys).to eq ['US'] }
+            end
+
+            context 'with the :in option set to {country: country code}' do
+              let(:location) { {country: 'US'} }
+              it { expect(result.keys).to eq ['US'] }
+            end
+          end
+        end
+      end
+
+      describe 'views can be retrieved for a single US state' do
+        let(:state_code) { 'CA' }
+        let(:result) { playlist.views since: date, by: by, in: location }
+        let(:date) { ENV['YT_TEST_PARTNER_VIDEO_DATE'] }
+
+        context 'and grouped by day' do
+          let(:by) { :day }
+
+          context 'with the :in option set to {state: state code}' do
+            let(:location) { {state: state_code} }
+            it { expect(result.keys.min).to eq date.to_date }
+          end
+
+          context 'with the :in option set to {country: "US", state: state code}' do
+            let(:location) { {country: 'US', state: state_code} }
+            it { expect(result.keys.min).to eq date.to_date }
+          end
+        end
+
+        context 'and grouped by US state' do
+          let(:by) { :state }
+
+          context 'with the :in option set to {state: state code}' do
+            let(:location) { {state: state_code} }
+            it { expect(result.keys).to eq [state_code] }
+          end
+
+          context 'with the :in option set to {country: "US", state: state code}' do
+            let(:location) { {country: 'US', state: state_code} }
+            it { expect(result.keys).to eq [state_code] }
+          end
+        end
+      end
+
+      describe 'views can be grouped by day' do
+        let(:range) { {since: 4.days.ago.to_date, until: 3.days.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'with the :by option set to :day' do
+          views = playlist.views range.merge by: :day
+          expect(views.keys).to eq range.values
+        end
+      end
+
+      describe 'views can be grouped by traffic source' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+        let(:keys) { Yt::Collections::Reports::TRAFFIC_SOURCES.keys }
+
+        specify 'with the :by option set to :traffic_source' do
+          views = playlist.views range.merge by: :traffic_source
+          expect(views.keys - keys).to be_empty
+        end
+      end
+
+      describe 'views can be grouped by playback location' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+        let(:keys) { Yt::Collections::Reports::PLAYBACK_LOCATIONS.keys }
+
+        specify 'with the :by option set to :playback_location' do
+          views = playlist.views range.merge by: :playback_location
+          expect(views.keys - keys).to be_empty
+        end
+      end
+
+      describe 'views can be grouped by related video' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+
+        specify 'with the :by option set to :related_video' do
+          views = playlist.views range.merge by: :related_video
+          expect(views.keys).to all(be_instance_of Yt::Video)
+        end
+      end
+
+      describe 'views can be grouped by search term' do
+        let(:range) { {since: ENV['YT_TEST_PARTNER_PLAYLIST_DATE']} }
+
+        specify 'with the :by option set to :search_term' do
+          views = playlist.views range.merge by: :search_term
+          expect(views.keys).to all(be_a String)
+        end
+      end
+
+      describe 'views can be grouped by referrer' do
+        let(:range) { {since: ENV['YT_TEST_PARTNER_PLAYLIST_DATE']} }
+
+        specify 'with the :by option set to :referrer' do
+          views = playlist.views range.merge by: :referrer
+          expect(views.keys).to all(be_a String)
+        end
+      end
+
+      describe 'views can be grouped by video' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+
+        specify 'with the :by option set to :video' do
+          views = playlist.views range.merge by: :video
+          expect(views.keys).to all(be_instance_of Yt::Video)
+        end
+      end
+
+      describe 'views can be grouped by playlist' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+
+        specify 'with the :by option set to :playlist' do
+          views = playlist.views range.merge by: :playlist
+          expect(views.keys).to all(be_instance_of Yt::Playlist)
+        end
+      end
+
+      describe 'views can be grouped by device type' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+
+        specify 'with the :by option set to :device_type' do
+          views = playlist.views range.merge by: :device_type
+          expect(views.keys).to all(be_instance_of Symbol)
+          expect(views.values).to all(be_an Integer)
+        end
+      end
+
+      describe 'views can be grouped by country' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+
+        specify 'with the :by option set to :country' do
+          views = playlist.views range.merge by: :country
+          expect(views.keys).to all(be_a String)
+          expect(views.keys.map(&:length).uniq).to eq [2]
+          expect(views.values).to all(be_an Integer)
+        end
+      end
+
+      describe 'views can be grouped by state' do
+        let(:range) { {since: ENV['YT_TEST_PARTNER_PLAYLIST_DATE']} }
+
+        specify 'with the :by option set to :state' do
+          views = playlist.views range.merge by: :state
+          expect(views.keys).to all(be_a String)
+          expect(views.keys.map(&:length).uniq).to eq [2]
+          expect(views.values).to all(be_an Integer)
+        end
+      end
+
+      describe 'estimated minutes watched can be retrieved for a single US state' do
+        let(:state_code) { 'CA' }
+        let(:result) { playlist.estimated_minutes_watched since: date, by: by, in: location }
+        let(:date) { ENV['YT_TEST_PARTNER_VIDEO_DATE'] }
+
+        context 'and grouped by day' do
+          let(:by) { :day }
+
+          context 'with the :in option set to {state: state code}' do
+            let(:location) { {state: state_code} }
+            it { expect(result.keys.min).to eq date.to_date }
+          end
+
+          context 'with the :in option set to {country: "US", state: state code}' do
+            let(:location) { {country: 'US', state: state_code} }
+            it { expect(result.keys.min).to eq date.to_date }
+          end
+        end
+
+        context 'and grouped by US state' do
+          let(:by) { :state }
+
+          context 'with the :in option set to {state: state code}' do
+            let(:location) { {state: state_code} }
+            it { expect(result.keys).to eq [state_code] }
+          end
+
+          context 'with the :in option set to {country: "US", state: state code}' do
+            let(:location) { {country: 'US', state: state_code} }
+            it { expect(result.keys).to eq [state_code] }
+          end
+        end
+      end
+
+      describe 'estimated minutes watched can be grouped by day' do
+        let(:range) { {since: 4.days.ago.to_date, until: 3.days.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'with the :by option set to :day' do
+          minutes = playlist.estimated_minutes_watched range.merge by: :day
+          expect(minutes.keys).to eq range.values
+        end
+      end
+
+      describe 'estimated minutes watched can be grouped by traffic source' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+        let(:keys) { Yt::Collections::Reports::TRAFFIC_SOURCES.keys }
+
+        specify 'with the :by option set to :traffic_source' do
+          minutes = playlist.estimated_minutes_watched range.merge by: :traffic_source
+          expect(minutes.keys - keys).to be_empty
+        end
+      end
+
+      describe 'estimated minutes watched can be grouped by playback location' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+        let(:keys) { Yt::Collections::Reports::PLAYBACK_LOCATIONS.keys }
+
+        specify 'with the :by option set to :playback_location' do
+          minutes = playlist.estimated_minutes_watched range.merge by: :playback_location
+          expect(minutes.keys - keys).to be_empty
+        end
+      end
+
+      describe 'estimated minutes watched can be grouped by related video' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+
+        specify 'with the :by option set to :related_video' do
+          minutes = playlist.estimated_minutes_watched range.merge by: :related_video
+          expect(minutes.keys).to all(be_instance_of Yt::Video)
+        end
+      end
+
+      describe 'estimated minutes watched can be grouped by search term' do
+        let(:range) { {since: ENV['YT_TEST_PARTNER_PLAYLIST_DATE']} }
+
+        specify 'with the :by option set to :search_term' do
+          minutes = playlist.estimated_minutes_watched range.merge by: :search_term
+          expect(minutes.keys).to all(be_a String)
+        end
+      end
+
+      describe 'estimated minutes watched can be grouped by referrer' do
+        let(:range) { {since: ENV['YT_TEST_PARTNER_PLAYLIST_DATE']} }
+
+        specify 'with the :by option set to :referrer' do
+          minutes = playlist.estimated_minutes_watched range.merge by: :referrer
+          expect(minutes.keys).to all(be_a String)
+        end
+      end
+
+      describe 'estimated minutes watched can be grouped by video' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+
+        specify 'with the :by option set to :video' do
+          minutes = playlist.estimated_minutes_watched range.merge by: :video
+          expect(minutes.keys).to all(be_instance_of Yt::Video)
+        end
+      end
+
+      describe 'estimated minutes watched can be grouped by playlist' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+
+        specify 'with the :by option set to :playlist' do
+          minutes = playlist.estimated_minutes_watched range.merge by: :playlist
+          expect(minutes.keys).to all(be_instance_of Yt::Playlist)
+        end
+      end
+
+      describe 'estimated minutes watched can be grouped by device type' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+
+        specify 'with the :by option set to :device_type' do
+          minutes = playlist.estimated_minutes_watched range.merge by: :device_type
+          expect(minutes.keys).to all(be_instance_of Symbol)
+          expect(minutes.values).to all(be_an Integer)
+        end
+      end
+
+      describe 'estimated minutes watched can be grouped by country' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+
+        specify 'with the :by option set to :country' do
+          minutes = playlist.estimated_minutes_watched range.merge by: :country
+          expect(minutes.keys).to all(be_a String)
+          expect(minutes.keys.map(&:length).uniq).to eq [2]
+          expect(minutes.values).to all(be_an Integer)
+        end
+      end
+
+      describe 'estimated minutes watched can be grouped by state' do
+        let(:range) { {since: ENV['YT_TEST_PARTNER_PLAYLIST_DATE']} }
+
+        specify 'with the :by option set to :state' do
+          minutes = playlist.estimated_minutes_watched range.merge by: :state
+          expect(minutes.keys).to all(be_a String)
+          expect(minutes.keys.map(&:length).uniq).to eq [2]
+          expect(minutes.values).to all(be_an Integer)
+        end
+      end
+
+      describe 'viewer percentage can be retrieved for a range of days' do
+        let(:viewer_percentage) { playlist.viewer_percentage since: 1.year.ago, until: 10.days.ago}
+        it { expect(viewer_percentage).to be_a Hash }
+      end
+
+      describe 'viewer_percentage can be grouped by gender and age group' do
+        let(:range) { {since: 1.year.ago.to_date, until: 1.week.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'without a :by option (default)' do
+          viewer_percentage = playlist.viewer_percentage range
+          expect(viewer_percentage.keys).to match_array [:female, :male]
+          expect(viewer_percentage[:female].keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage[:female].values).to all(be_instance_of Float)
+          expect(viewer_percentage[:male].keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage[:male].values).to all(be_instance_of Float)
+        end
+
+        specify 'with the :by option set to :gender_age_group' do
+          viewer_percentage = playlist.viewer_percentage range.merge by: :gender_age_group
+          expect(viewer_percentage.keys).to match_array [:female, :male]
+          expect(viewer_percentage[:female].keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage[:female].values).to all(be_instance_of Float)
+          expect(viewer_percentage[:male].keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage[:male].values).to all(be_instance_of Float)
+        end
+      end
+
+      describe 'viewer_percentage can be grouped by gender' do
+        let(:range) { {since: 1.year.ago.to_date, until: 1.week.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'with the :by option set to :gender' do
+          viewer_percentage = playlist.viewer_percentage range.merge by: :gender
+          expect(viewer_percentage.keys).to match_array [:female, :male]
+          expect(viewer_percentage[:female]).to be_a Float
+          expect(viewer_percentage[:male]).to be_a Float
+        end
+      end
+
+      describe 'viewer_percentage can be grouped by age group' do
+        let(:range) { {since: 1.year.ago.to_date, until: 1.week.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'with the :by option set to :age_group' do
+          viewer_percentage = playlist.viewer_percentage range.merge by: :age_group
+          expect(viewer_percentage.keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage.values).to all(be_instance_of Float)
+        end
+      end
+
+
+      describe 'average view duration can be retrieved for a single US state' do
+        let(:state_code) { 'CA' }
+        let(:result) { playlist.average_view_duration since: date, by: by, in: location }
+        let(:date) { ENV['YT_TEST_PARTNER_VIDEO_DATE'] }
+
+        context 'and grouped by day' do
+          let(:by) { :day }
+
+          context 'with the :in option set to {state: state code}' do
+            let(:location) { {state: state_code} }
+            it { expect(result.keys.min).to eq date.to_date }
+          end
+
+          context 'with the :in option set to {country: "US", state: state code}' do
+            let(:location) { {country: 'US', state: state_code} }
+            it { expect(result.keys.min).to eq date.to_date }
+          end
+        end
+
+        context 'and grouped by US state' do
+          let(:by) { :state }
+
+          context 'with the :in option set to {state: state code}' do
+            let(:location) { {state: state_code} }
+            it { expect(result.keys).to eq [state_code] }
+          end
+
+          context 'with the :in option set to {country: "US", state: state code}' do
+            let(:location) { {country: 'US', state: state_code} }
+            it { expect(result.keys).to eq [state_code] }
+          end
+        end
+      end
+
+      describe 'average view duration can be grouped by day' do
+        let(:range) { {since: 4.days.ago.to_date, until: 3.days.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'with the :by option set to :day' do
+          average_view_duration = playlist.average_view_duration range.merge by: :day
+          expect(average_view_duration.keys).to eq range.values
+        end
+      end
+
+      describe 'average view duration can be grouped by country' do
+        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+
+        specify 'with the :by option set to :country' do
+          duration = playlist.average_view_duration range.merge by: :country
+          expect(duration.keys).to all(be_a String)
+          expect(duration.keys.map(&:length).uniq).to eq [2]
+          expect(duration.values).to all(be_an Integer)
+        end
+      end
+
+      describe 'average view duration can be grouped by state' do
+        let(:range) { {since: ENV['YT_TEST_PARTNER_PLAYLIST_DATE']} }
+
+        specify 'with the :by option set to :state' do
+          duration = playlist.average_view_duration range.merge by: :state
+          expect(duration.keys).to all(be_a String)
+          expect(duration.keys.map(&:length).uniq).to eq [2]
+          expect(duration.values).to all(be_an Integer)
+        end
+      end
+
+      describe 'playlist starts can be retrieved for a single US state' do
+        let(:state_code) { 'CA' }
+        let(:result) { playlist.playlist_starts since: date, by: by, in: location }
+        let(:date) { ENV['YT_TEST_PARTNER_VIDEO_DATE'] }
+
+        context 'and grouped by day' do
+          let(:by) { :day }
+
+          context 'with the :in option set to {state: state code}' do
+            let(:location) { {state: state_code} }
+            it { expect(result.keys.min).to eq date.to_date }
+          end
+
+          context 'with the :in option set to {country: "US", state: state code}' do
+            let(:location) { {country: 'US', state: state_code} }
+            it { expect(result.keys.min).to eq date.to_date }
+          end
+        end
+
+        context 'and grouped by US state' do
+          let(:by) { :state }
+
+          context 'with the :in option set to {state: state code}' do
+            let(:location) { {state: state_code} }
+            it { expect(result.keys).to eq [state_code] }
+          end
+
+          context 'with the :in option set to {country: "US", state: state code}' do
+            let(:location) { {country: 'US', state: state_code} }
+            it { expect(result.keys).to eq [state_code] }
+          end
+        end
+      end
+
+      describe 'playlist starts can be grouped by day' do
+        let(:range) { {since: 4.days.ago.to_date, until: 3.days.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'with the :by option set to :day' do
+          playlist_starts = playlist.playlist_starts range.merge by: :day
+          expect(playlist_starts.keys).to eq range.values
+        end
+      end
+
+      describe 'playlist starts can be grouped by country' do
+        let(:range) { {since: ENV['YT_TEST_PARTNER_PLAYLIST_DATE']} }
+
+        specify 'with the :by option set to :country' do
+          starts = playlist.playlist_starts range.merge by: :country
+          expect(starts.keys).to all(be_a String)
+          expect(starts.keys.map(&:length).uniq).to eq [2]
+          expect(starts.values).to all(be_an Integer)
+        end
+      end
+
+      describe 'playlist starts can be grouped by state' do
+        let(:range) { {since: ENV['YT_TEST_PARTNER_PLAYLIST_DATE']} }
+
+        specify 'with the :by option set to :state' do
+          starts = playlist.playlist_starts range.merge by: :state
+          expect(starts.keys).to all(be_a String)
+          expect(starts.keys.map(&:length).uniq).to eq [2]
+          expect(starts.values).to all(be_an Integer)
+        end
+      end
+
+      describe 'average time in playlist can be retrieved for a single US state' do
+        let(:state_code) { 'CA' }
+        let(:result) { playlist.average_time_in_playlist since: date, by: by, in: location }
+        let(:date) { ENV['YT_TEST_PARTNER_VIDEO_DATE'] }
+
+        context 'and grouped by day' do
+          let(:by) { :day }
+
+          context 'with the :in option set to {state: state code}' do
+            let(:location) { {state: state_code} }
+            it { expect(result.keys.min).to eq date.to_date }
+          end
+
+          context 'with the :in option set to {country: "US", state: state code}' do
+            let(:location) { {country: 'US', state: state_code} }
+            it { expect(result.keys.min).to eq date.to_date }
+          end
+        end
+
+        context 'and grouped by US state' do
+          let(:by) { :state }
+
+          context 'with the :in option set to {state: state code}' do
+            let(:location) { {state: state_code} }
+            it { expect(result.keys).to eq [state_code] }
+          end
+
+          context 'with the :in option set to {country: "US", state: state code}' do
+            let(:location) { {country: 'US', state: state_code} }
+            it { expect(result.keys).to eq [state_code] }
+          end
+        end
+      end
+
+      describe 'average time in playlist can be grouped by day' do
+        let(:range) { {since: 4.days.ago.to_date, until: 3.days.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'with the :by option set to :day' do
+          average_time_in_playlist = playlist.average_time_in_playlist range.merge by: :day
+          expect(average_time_in_playlist.keys).to eq range.values
+        end
+      end
+
+      describe 'average time in playlist can be grouped by country' do
+        let(:range) { {since: ENV['YT_TEST_PARTNER_PLAYLIST_DATE']} }
+
+        specify 'with the :by option set to :country' do
+          time = playlist.average_time_in_playlist range.merge by: :country
+          expect(time.keys).to all(be_a String)
+          expect(time.keys.map(&:length).uniq).to eq [2]
+          expect(time.values).to all(be_a Float)
+        end
+      end
+
+      describe 'average time in playlist can be grouped by state' do
+        let(:range) { {since: ENV['YT_TEST_PARTNER_PLAYLIST_DATE']} }
+
+        specify 'with the :by option set to :state' do
+          time = playlist.average_time_in_playlist range.merge by: :state
+          expect(time.keys).to all(be_a String)
+          expect(time.keys.map(&:length).uniq).to eq [2]
+          expect(time.values).to all(be_a Float)
+        end
+      end
+
+      describe 'views per playlists start can be retrieved for a single US state' do
+        let(:state_code) { 'CA' }
+        let(:result) { playlist.views_per_playlist_start since: date, by: by, in: location }
+        let(:date) { ENV['YT_TEST_PARTNER_VIDEO_DATE'] }
+
+        context 'and grouped by day' do
+          let(:by) { :day }
+
+          context 'with the :in option set to {state: state code}' do
+            let(:location) { {state: state_code} }
+            it { expect(result.keys.min).to eq date.to_date }
+          end
+
+          context 'with the :in option set to {country: "US", state: state code}' do
+            let(:location) { {country: 'US', state: state_code} }
+            it { expect(result.keys.min).to eq date.to_date }
+          end
+        end
+
+        context 'and grouped by US state' do
+          let(:by) { :state }
+
+          context 'with the :in option set to {state: state code}' do
+            let(:location) { {state: state_code} }
+            it { expect(result.keys).to eq [state_code] }
+          end
+
+          context 'with the :in option set to {country: "US", state: state code}' do
+            let(:location) { {country: 'US', state: state_code} }
+            it { expect(result.keys).to eq [state_code] }
+          end
+        end
+      end
+
+      describe 'views per playlist start can be grouped by day' do
+        let(:range) { {since: 4.days.ago.to_date, until: 3.days.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'with the :by option set to :day' do
+          views_per_playlist_start = playlist.views_per_playlist_start range.merge by: :day
+          expect(views_per_playlist_start.keys).to eq range.values
+        end
+      end
+
+      describe 'views per playlist start can be grouped by country' do
+        let(:range) { {since: ENV['YT_TEST_PARTNER_PLAYLIST_DATE']} }
+
+        specify 'with the :by option set to :country' do
+          views = playlist.views_per_playlist_start range.merge by: :country
+          expect(views.keys).to all(be_a String)
+          expect(views.keys.map(&:length).uniq).to eq [2]
+          expect(views.values).to all(be_a Float)
+        end
+      end
+
+      describe 'views per playlist start can be grouped by state' do
+        let(:range) { {since: ENV['YT_TEST_PARTNER_PLAYLIST_DATE']} }
+
+        specify 'with the :by option set to :state' do
+          views = playlist.views_per_playlist_start range.merge by: :state
+          expect(views.keys).to all(be_a String)
+          expect(views.keys.map(&:length).uniq).to eq [2]
+          expect(views.values).to all(be_a Float)
+        end
+      end
+    end
+
+    context 'not managed by the authenticated Content Owner' do
+      let(:id) { 'PLbpi6ZahtOH6J5oPGySZcmbRfT7Hyq1sZ' }
+
+      specify 'playlist starts cannot be retrieved' do
+        expect{playlist.views}.to raise_error Yt::Errors::Forbidden
+        expect{playlist.playlist_starts}.to raise_error Yt::Errors::Forbidden
+        expect{playlist.average_time_in_playlist}.to raise_error Yt::Errors::Forbidden
+        expect{playlist.views_per_playlist_start}.to raise_error Yt::Errors::Forbidden
+      end
+    end
+  end
+end