youtube-transcript-rb 0.1.0

data/spec/errors_spec.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "youtube/transcript/rb"
+
+RSpec.describe Youtube::Transcript::Rb do
+  describe "Error hierarchy" do
+    it "has Error as the base class" do
+      expect(Youtube::Transcript::Rb::Error).to be < StandardError
+    end
+
+    it "has CouldNotRetrieveTranscript inheriting from Error" do
+      expect(Youtube::Transcript::Rb::CouldNotRetrieveTranscript).to be < Youtube::Transcript::Rb::Error
+    end
+
+    describe "error classes inherit from CouldNotRetrieveTranscript" do
+      [
+        Youtube::Transcript::Rb::YouTubeDataUnparsable,
+        Youtube::Transcript::Rb::YouTubeRequestFailed,
+        Youtube::Transcript::Rb::VideoUnplayable,
+        Youtube::Transcript::Rb::VideoUnavailable,
+        Youtube::Transcript::Rb::InvalidVideoId,
+        Youtube::Transcript::Rb::RequestBlocked,
+        Youtube::Transcript::Rb::IpBlocked,
+        Youtube::Transcript::Rb::TooManyRequests,
+        Youtube::Transcript::Rb::TranscriptsDisabled,
+        Youtube::Transcript::Rb::AgeRestricted,
+        Youtube::Transcript::Rb::NotTranslatable,
+        Youtube::Transcript::Rb::TranslationLanguageNotAvailable,
+        Youtube::Transcript::Rb::FailedToCreateConsentCookie,
+        Youtube::Transcript::Rb::NoTranscriptFound,
+        Youtube::Transcript::Rb::NoTranscriptAvailable,
+        Youtube::Transcript::Rb::PoTokenRequired
+      ].each do |error_class|
+        it "#{error_class} inherits from CouldNotRetrieveTranscript" do
+          expect(error_class).to be < Youtube::Transcript::Rb::CouldNotRetrieveTranscript
+        end
+      end
+    end
+  end
+
+  describe Youtube::Transcript::Rb::CouldNotRetrieveTranscript do
+    let(:video_id) { "test_video_123" }
+
+    it "stores the video_id" do
+      # Using a subclass since CouldNotRetrieveTranscript needs CAUSE_MESSAGE
+      error = Youtube::Transcript::Rb::VideoUnavailable.new(video_id)
+      expect(error.video_id).to eq(video_id)
+    end
+
+    it "includes video URL in error message" do
+      error = Youtube::Transcript::Rb::VideoUnavailable.new(video_id)
+      expect(error.message).to include("https://www.youtube.com/watch?v=#{video_id}")
+    end
+
+    it "includes cause message in error message" do
+      error = Youtube::Transcript::Rb::VideoUnavailable.new(video_id)
+      expect(error.message).to include("The video is no longer available")
+    end
+  end
+
+  describe Youtube::Transcript::Rb::VideoUnavailable do
+    let(:video_id) { "unavailable_video" }
+    let(:error) { described_class.new(video_id) }
+
+    it "has the correct cause message" do
+      expect(error.cause_message).to eq("The video is no longer available")
+    end
+  end
+
+  describe Youtube::Transcript::Rb::TranscriptsDisabled do
+    let(:video_id) { "disabled_video" }
+    let(:error) { described_class.new(video_id) }
+
+    it "has the correct cause message" do
+      expect(error.cause_message).to eq("Subtitles are disabled for this video")
+    end
+  end
+
+  describe Youtube::Transcript::Rb::TooManyRequests do
+    let(:video_id) { "rate_limited" }
+    let(:error) { described_class.new(video_id) }
+
+    it "has the correct cause message" do
+      expect(error.cause_message).to include("rate limiting")
+    end
+  end
+
+  describe Youtube::Transcript::Rb::PoTokenRequired do
+    let(:video_id) { "po_token_video" }
+    let(:error) { described_class.new(video_id) }
+
+    it "has the correct cause message" do
+      expect(error.cause_message).to include("PO Token")
+    end
+  end
+
+  describe Youtube::Transcript::Rb::InvalidVideoId do
+    let(:video_id) { "https://www.youtube.com/watch?v=1234" }
+    let(:error) { described_class.new(video_id) }
+
+    it "includes usage instructions in cause message" do
+      expect(error.cause_message).to include("Do NOT run")
+      expect(error.cause_message).to include("Instead run")
+    end
+  end
+
+  describe Youtube::Transcript::Rb::YouTubeRequestFailed do
+    let(:video_id) { "failed_request" }
+    let(:http_error) { StandardError.new("Connection refused") }
+    let(:error) { described_class.new(video_id, http_error) }
+
+    it "stores the reason" do
+      expect(error.reason).to eq("Connection refused")
+    end
+
+    it "includes the reason in cause message" do
+      expect(error.cause_message).to include("Connection refused")
+    end
+  end
+
+  describe Youtube::Transcript::Rb::VideoUnplayable do
+    let(:video_id) { "unplayable_video" }
+
+    context "with reason only" do
+      let(:error) { described_class.new(video_id, "Video is private") }
+
+      it "stores the reason" do
+        expect(error.reason).to eq("Video is private")
+      end
+
+      it "includes reason in cause message" do
+        expect(error.cause_message).to include("Video is private")
+      end
+    end
+
+    context "with no reason" do
+      let(:error) { described_class.new(video_id) }
+
+      it "uses default reason text" do
+        expect(error.cause_message).to include("No reason specified!")
+      end
+    end
+
+    context "with sub_reasons" do
+      let(:error) { described_class.new(video_id, "Video is restricted", ["Region blocked", "Age restricted"]) }
+
+      it "stores sub_reasons" do
+        expect(error.sub_reasons).to eq(["Region blocked", "Age restricted"])
+      end
+
+      it "includes sub_reasons in cause message" do
+        expect(error.cause_message).to include("Region blocked")
+        expect(error.cause_message).to include("Age restricted")
+        expect(error.cause_message).to include("Additional Details")
+      end
+    end
+  end
+
+  describe Youtube::Transcript::Rb::NoTranscriptFound do
+    let(:video_id) { "no_transcript" }
+    let(:requested_languages) { ["ko", "ja"] }
+    let(:transcript_data) { double("TranscriptList", to_s: "Available: en, es") }
+    let(:error) { described_class.new(video_id, requested_languages, transcript_data) }
+
+    it "stores requested_language_codes" do
+      expect(error.requested_language_codes).to eq(["ko", "ja"])
+    end
+
+    it "stores transcript_data" do
+      expect(error.transcript_data).to eq(transcript_data)
+    end
+
+    it "includes requested languages in cause message" do
+      expect(error.cause_message).to include("ko")
+      expect(error.cause_message).to include("ja")
+    end
+
+    it "includes transcript data in cause message" do
+      expect(error.cause_message).to include("Available: en, es")
+    end
+  end
+
+  describe Youtube::Transcript::Rb::RequestBlocked do
+    let(:video_id) { "blocked_video" }
+    let(:error) { described_class.new(video_id) }
+
+    it "mentions IP blocking" do
+      expect(error.cause_message).to include("YouTube is blocking requests from your IP")
+    end
+
+    it "mentions cloud providers" do
+      expect(error.cause_message).to include("cloud provider")
+    end
+  end
+
+  describe Youtube::Transcript::Rb::IpBlocked do
+    let(:video_id) { "ip_blocked" }
+    let(:error) { described_class.new(video_id) }
+
+    it "inherits from RequestBlocked" do
+      expect(described_class).to be < Youtube::Transcript::Rb::RequestBlocked
+    end
+
+    it "mentions IP or proxies as workaround" do
+      expect(error.cause_message).to include("IP").or include("proxy")
+    end
+  end
+
+  describe Youtube::Transcript::Rb::AgeRestricted do
+    let(:video_id) { "age_restricted" }
+    let(:error) { described_class.new(video_id) }
+
+    it "mentions age restriction" do
+      expect(error.cause_message).to include("age-restricted")
+    end
+
+    it "mentions authentication limitation" do
+      expect(error.cause_message).to include("Cookie Authentication is temporarily unsupported")
+    end
+  end
+
+  describe Youtube::Transcript::Rb::NotTranslatable do
+    let(:video_id) { "not_translatable" }
+    let(:error) { described_class.new(video_id) }
+
+    it "has the correct cause message" do
+      expect(error.cause_message).to include("not translatable")
+    end
+  end
+
+  describe Youtube::Transcript::Rb::TranslationLanguageNotAvailable do
+    let(:video_id) { "translation_unavailable" }
+    let(:error) { described_class.new(video_id) }
+
+    it "has the correct cause message" do
+      expect(error.cause_message).to include("translation language is not available")
+    end
+  end
+end

data/spec/formatters_spec.rb

@@ -0,0 +1,436 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Youtube::Transcript::Rb::Formatters do
+  # Helper to create a FetchedTranscript with snippets
+  def create_transcript(video_id: "test123", language: "English", language_code: "en", is_generated: false, snippets: nil)
+    snippets ||= [
+      Youtube::Transcript::Rb::TranscriptSnippet.new(text: "Hello world", start: 0.0, duration: 2.5),
+      Youtube::Transcript::Rb::TranscriptSnippet.new(text: "This is a test", start: 2.5, duration: 3.0),
+      Youtube::Transcript::Rb::TranscriptSnippet.new(text: "Thank you", start: 5.5, duration: 2.0)
+    ]
+
+    Youtube::Transcript::Rb::FetchedTranscript.new(
+      video_id: video_id,
+      language: language,
+      language_code: language_code,
+      is_generated: is_generated,
+      snippets: snippets
+    )
+  end
+
+  let(:transcript) { create_transcript }
+  let(:transcript2) { create_transcript(video_id: "video2", language_code: "es", language: "Spanish") }
+  let(:transcripts) { [transcript, transcript2] }
+
+  describe Youtube::Transcript::Rb::Formatters::Formatter do
+    let(:formatter) { described_class.new }
+
+    describe "#format_transcript" do
+      it "raises NotImplementedError" do
+        expect { formatter.format_transcript(transcript) }.to raise_error(NotImplementedError)
+      end
+    end
+
+    describe "#format_transcripts" do
+      it "raises NotImplementedError" do
+        expect { formatter.format_transcripts(transcripts) }.to raise_error(NotImplementedError)
+      end
+    end
+  end
+
+  describe Youtube::Transcript::Rb::Formatters::JSONFormatter do
+    let(:formatter) { described_class.new }
+
+    describe "#format_transcript" do
+      it "returns valid JSON" do
+        result = formatter.format_transcript(transcript)
+        expect { JSON.parse(result) }.not_to raise_error
+      end
+
+      it "contains all snippets" do
+        result = formatter.format_transcript(transcript)
+        parsed = JSON.parse(result)
+        expect(parsed.length).to eq(3)
+      end
+
+      it "includes text, start, and duration for each snippet" do
+        result = formatter.format_transcript(transcript)
+        parsed = JSON.parse(result)
+
+        expect(parsed[0]["text"]).to eq("Hello world")
+        expect(parsed[0]["start"]).to eq(0.0)
+        expect(parsed[0]["duration"]).to eq(2.5)
+      end
+
+      it "supports JSON options" do
+        # JSON.generate with indent requires array_nl and object_nl for newlines
+        result = formatter.format_transcript(transcript, indent: "  ", array_nl: "\n", object_nl: "\n")
+        expect(result).to include("\n")
+      end
+    end
+
+    describe "#format_transcripts" do
+      it "returns valid JSON array" do
+        result = formatter.format_transcripts(transcripts)
+        parsed = JSON.parse(result)
+        expect(parsed).to be_an(Array)
+        expect(parsed.length).to eq(2)
+      end
+
+      it "contains all transcripts" do
+        result = formatter.format_transcripts(transcripts)
+        parsed = JSON.parse(result)
+        expect(parsed[0].length).to eq(3)
+        expect(parsed[1].length).to eq(3)
+      end
+    end
+  end
+
+  describe Youtube::Transcript::Rb::Formatters::TextFormatter do
+    let(:formatter) { described_class.new }
+
+    describe "#format_transcript" do
+      it "returns plain text with newlines" do
+        result = formatter.format_transcript(transcript)
+        expect(result).to eq("Hello world\nThis is a test\nThank you")
+      end
+
+      it "contains only text, no timestamps" do
+        result = formatter.format_transcript(transcript)
+        expect(result).not_to include("0.0")
+        expect(result).not_to include("-->")
+      end
+    end
+
+    describe "#format_transcripts" do
+      it "separates transcripts with triple newlines" do
+        result = formatter.format_transcripts(transcripts)
+        expect(result).to include("\n\n\n")
+      end
+
+      it "contains all transcript texts" do
+        result = formatter.format_transcripts(transcripts)
+        expect(result).to include("Hello world")
+        expect(result).to include("Thank you")
+      end
+    end
+  end
+
+  describe Youtube::Transcript::Rb::Formatters::PrettyPrintFormatter do
+    let(:formatter) { described_class.new }
+
+    describe "#format_transcript" do
+      it "returns a string" do
+        result = formatter.format_transcript(transcript)
+        expect(result).to be_a(String)
+      end
+
+      it "contains transcript data" do
+        result = formatter.format_transcript(transcript)
+        expect(result).to include("Hello world")
+        expect(result).to include("text")
+        expect(result).to include("start")
+        expect(result).to include("duration")
+      end
+
+      it "is formatted with indentation" do
+        result = formatter.format_transcript(transcript)
+        # PP output typically has newlines for arrays
+        expect(result).to include("\n") if transcript.length > 1
+      end
+
+      it "accepts width option" do
+        result = formatter.format_transcript(transcript, width: 40)
+        expect(result).to be_a(String)
+      end
+    end
+
+    describe "#format_transcripts" do
+      it "returns a string containing all transcripts" do
+        result = formatter.format_transcripts(transcripts)
+        expect(result).to be_a(String)
+        expect(result).to include("Hello world")
+      end
+    end
+  end
+
+  describe Youtube::Transcript::Rb::Formatters::SRTFormatter do
+    let(:formatter) { described_class.new }
+
+    describe "#format_transcript" do
+      let(:result) { formatter.format_transcript(transcript) }
+
+      it "includes sequence numbers starting from 1" do
+        expect(result).to include("1\n")
+        expect(result).to include("2\n")
+        expect(result).to include("3\n")
+      end
+
+      it "uses comma as millisecond separator" do
+        expect(result).to include(",")
+        expect(result).not_to match(/\d{2}:\d{2}:\d{2}\.\d{3}/)
+      end
+
+      it "formats timestamps correctly" do
+        expect(result).to include("00:00:00,000 --> 00:00:02,500")
+        expect(result).to include("00:00:02,500 --> 00:00:05,500")
+      end
+
+      it "includes the text content" do
+        expect(result).to include("Hello world")
+        expect(result).to include("This is a test")
+        expect(result).to include("Thank you")
+      end
+
+      it "separates entries with blank lines" do
+        expect(result).to include("\n\n")
+      end
+
+      it "ends with a newline" do
+        expect(result).to end_with("\n")
+      end
+
+      it "follows SRT format structure" do
+        lines = result.split("\n\n")
+        first_entry = lines[0].split("\n")
+
+        expect(first_entry[0]).to eq("1")
+        expect(first_entry[1]).to match(/\d{2}:\d{2}:\d{2},\d{3} --> \d{2}:\d{2}:\d{2},\d{3}/)
+        expect(first_entry[2]).to eq("Hello world")
+      end
+    end
+
+    describe "timestamp edge cases" do
+      it "handles hours correctly" do
+        snippets = [
+          Youtube::Transcript::Rb::TranscriptSnippet.new(text: "Long video", start: 3661.5, duration: 2.0)
+        ]
+        transcript = create_transcript(snippets: snippets)
+        result = formatter.format_transcript(transcript)
+
+        expect(result).to include("01:01:01,500")
+      end
+
+      it "handles overlapping timestamps" do
+        snippets = [
+          Youtube::Transcript::Rb::TranscriptSnippet.new(text: "First", start: 0.0, duration: 5.0),
+          Youtube::Transcript::Rb::TranscriptSnippet.new(text: "Second", start: 2.0, duration: 3.0)
+        ]
+        transcript = create_transcript(snippets: snippets)
+        result = formatter.format_transcript(transcript)
+
+        # First snippet should end at second snippet's start
+        expect(result).to include("00:00:00,000 --> 00:00:02,000")
+      end
+    end
+  end
+
+  describe Youtube::Transcript::Rb::Formatters::WebVTTFormatter do
+    let(:formatter) { described_class.new }
+
+    describe "#format_transcript" do
+      let(:result) { formatter.format_transcript(transcript) }
+
+      it "starts with WEBVTT header" do
+        expect(result).to start_with("WEBVTT\n\n")
+      end
+
+      it "uses period as millisecond separator" do
+        expect(result).to match(/\d{2}:\d{2}:\d{2}\.\d{3}/)
+        expect(result).not_to match(/\d{2}:\d{2}:\d{2},\d{3}/)
+      end
+
+      it "formats timestamps correctly" do
+        expect(result).to include("00:00:00.000 --> 00:00:02.500")
+        expect(result).to include("00:00:02.500 --> 00:00:05.500")
+      end
+
+      it "does not include sequence numbers" do
+        lines = result.split("\n")
+        # Skip WEBVTT header
+        timestamp_lines = lines.select { |l| l.include?("-->") }
+        timestamp_lines.each_with_index do |line, i|
+          prev_line = lines[lines.index(line) - 1]
+          # Previous line should be empty or WEBVTT, not a number
+          expect(prev_line).not_to match(/^\d+$/)
+        end
+      end
+
+      it "includes the text content" do
+        expect(result).to include("Hello world")
+        expect(result).to include("This is a test")
+        expect(result).to include("Thank you")
+      end
+
+      it "ends with a newline" do
+        expect(result).to end_with("\n")
+      end
+    end
+
+    describe "timestamp edge cases" do
+      it "handles hours correctly" do
+        snippets = [
+          Youtube::Transcript::Rb::TranscriptSnippet.new(text: "Long video", start: 3661.5, duration: 2.0)
+        ]
+        transcript = create_transcript(snippets: snippets)
+        result = formatter.format_transcript(transcript)
+
+        expect(result).to include("01:01:01.500")
+      end
+    end
+  end
+
+  describe Youtube::Transcript::Rb::Formatters::FormatterLoader do
+    let(:loader) { described_class.new }
+
+    describe "#load" do
+      it "loads JSONFormatter for 'json'" do
+        formatter = loader.load("json")
+        expect(formatter).to be_a(Youtube::Transcript::Rb::Formatters::JSONFormatter)
+      end
+
+      it "loads TextFormatter for 'text'" do
+        formatter = loader.load("text")
+        expect(formatter).to be_a(Youtube::Transcript::Rb::Formatters::TextFormatter)
+      end
+
+      it "loads PrettyPrintFormatter for 'pretty'" do
+        formatter = loader.load("pretty")
+        expect(formatter).to be_a(Youtube::Transcript::Rb::Formatters::PrettyPrintFormatter)
+      end
+
+      it "loads SRTFormatter for 'srt'" do
+        formatter = loader.load("srt")
+        expect(formatter).to be_a(Youtube::Transcript::Rb::Formatters::SRTFormatter)
+      end
+
+      it "loads WebVTTFormatter for 'webvtt'" do
+        formatter = loader.load("webvtt")
+        expect(formatter).to be_a(Youtube::Transcript::Rb::Formatters::WebVTTFormatter)
+      end
+
+      it "defaults to PrettyPrintFormatter" do
+        formatter = loader.load
+        expect(formatter).to be_a(Youtube::Transcript::Rb::Formatters::PrettyPrintFormatter)
+      end
+
+      it "accepts symbol as formatter type" do
+        formatter = loader.load(:json)
+        expect(formatter).to be_a(Youtube::Transcript::Rb::Formatters::JSONFormatter)
+      end
+
+      it "raises UnknownFormatterType for invalid type" do
+        expect { loader.load("invalid") }.to raise_error(
+          Youtube::Transcript::Rb::Formatters::FormatterLoader::UnknownFormatterType
+        )
+      end
+
+      it "includes available formats in error message" do
+        begin
+          loader.load("invalid")
+        rescue Youtube::Transcript::Rb::Formatters::FormatterLoader::UnknownFormatterType => e
+          expect(e.message).to include("json")
+          expect(e.message).to include("text")
+          expect(e.message).to include("srt")
+          expect(e.message).to include("webvtt")
+          expect(e.message).to include("pretty")
+        end
+      end
+    end
+
+    describe "TYPES constant" do
+      it "contains all expected formatter types" do
+        expect(described_class::TYPES.keys).to contain_exactly("json", "pretty", "text", "webvtt", "srt")
+      end
+
+      it "is frozen" do
+        expect(described_class::TYPES).to be_frozen
+      end
+    end
+  end
+
+  describe "integration tests" do
+    let(:loader) { Youtube::Transcript::Rb::Formatters::FormatterLoader.new }
+
+    it "can format transcript with each formatter type" do
+      %w[json text pretty srt webvtt].each do |type|
+        formatter = loader.load(type)
+        result = formatter.format_transcript(transcript)
+        expect(result).to be_a(String)
+        expect(result.length).to be > 0
+      end
+    end
+
+    it "can format multiple transcripts with each formatter type" do
+      %w[json text pretty].each do |type|
+        formatter = loader.load(type)
+        result = formatter.format_transcripts(transcripts)
+        expect(result).to be_a(String)
+        expect(result.length).to be > 0
+      end
+    end
+  end
+
+  describe "empty transcript handling" do
+    let(:empty_snippets) { [] }
+    let(:empty_transcript) { create_transcript(snippets: empty_snippets) }
+
+    it "JSONFormatter handles empty transcript" do
+      formatter = Youtube::Transcript::Rb::Formatters::JSONFormatter.new
+      result = formatter.format_transcript(empty_transcript)
+      expect(JSON.parse(result)).to eq([])
+    end
+
+    it "TextFormatter handles empty transcript" do
+      formatter = Youtube::Transcript::Rb::Formatters::TextFormatter.new
+      result = formatter.format_transcript(empty_transcript)
+      expect(result).to eq("")
+    end
+
+    it "SRTFormatter handles empty transcript" do
+      formatter = Youtube::Transcript::Rb::Formatters::SRTFormatter.new
+      result = formatter.format_transcript(empty_transcript)
+      expect(result).to eq("\n")
+    end
+
+    it "WebVTTFormatter handles empty transcript" do
+      formatter = Youtube::Transcript::Rb::Formatters::WebVTTFormatter.new
+      result = formatter.format_transcript(empty_transcript)
+      expect(result).to eq("WEBVTT\n\n\n")
+    end
+  end
+
+  describe "special character handling" do
+    let(:special_snippets) do
+      [
+        Youtube::Transcript::Rb::TranscriptSnippet.new(text: "Hello <b>world</b>", start: 0.0, duration: 2.0),
+        Youtube::Transcript::Rb::TranscriptSnippet.new(text: 'Quote: "test"', start: 2.0, duration: 2.0),
+        Youtube::Transcript::Rb::TranscriptSnippet.new(text: "Line1\nLine2", start: 4.0, duration: 2.0)
+      ]
+    end
+    let(:special_transcript) { create_transcript(snippets: special_snippets) }
+
+    it "JSONFormatter escapes special characters" do
+      formatter = Youtube::Transcript::Rb::Formatters::JSONFormatter.new
+      result = formatter.format_transcript(special_transcript)
+      parsed = JSON.parse(result)
+      expect(parsed[0]["text"]).to eq("Hello <b>world</b>")
+      expect(parsed[1]["text"]).to eq('Quote: "test"')
+    end
+
+    it "TextFormatter preserves special characters" do
+      formatter = Youtube::Transcript::Rb::Formatters::TextFormatter.new
+      result = formatter.format_transcript(special_transcript)
+      expect(result).to include("<b>world</b>")
+      expect(result).to include('"test"')
+    end
+
+    it "SRTFormatter preserves HTML tags in text" do
+      formatter = Youtube::Transcript::Rb::Formatters::SRTFormatter.new
+      result = formatter.format_transcript(special_transcript)
+      expect(result).to include("<b>world</b>")
+    end
+  end
+end