"""Tests for the FreshRSS client, against an in-process FreshRSS stand-in. These assert on the wire format as much as on the parsed result: the query parameters the client sends (``r=d``, ``n=``, ``xt=``, ``ck=``) and the form body it posts for ``edit-tag`` are the parts that silently break against a real server, so they are checked explicitly. """ from __future__ import annotations import unittest from datetime import UTC, datetime from app.config import FreshRSSConfig from app.freshrss import ( READ_TAG, READING_LIST, STARRED, AuthenticationError, FreshRSSClient, FreshRSSError, NotFoundError, TransientError, label_stream, ) from tests.stub_freshrss import build_demo_catalog TECH_FEED = "feed/https://example.com/tech/atom.xml" NEWS_FEED = "feed/https://news.example.org/rss?source=daily" SOLO_FEED = "feed/https://solo.example.net/feed.xml" def make_config(stub, **overrides) -> FreshRSSConfig: """A client config aimed at the stub, with fast, non-retrying defaults.""" values = { "api_base": stub.api_url, "username": stub.username, "api_password": stub.password, "timeout_seconds": 5.0, "retries": 0, } values.update(overrides) return FreshRSSConfig(**values) class ClientTestCase(unittest.TestCase): """Starts a fresh stub per test.""" def setUp(self): self.stub = build_demo_catalog().start() self.addCleanup(self.stub.stop) def client(self, **overrides) -> FreshRSSClient: client = FreshRSSClient( make_config(self.stub, **overrides), # Retry timing is not what these tests are about, and sleeping would # only make the suite slow. sleep=lambda _seconds: None, ) self.addCleanup(client.close) return client class AuthenticationTests(ClientTestCase): def test_login_posts_credentials_and_reads_the_auth_line(self): self.client().list_subscriptions() logins = self.stub.find_requests("/accounts/ClientLogin") self.assertEqual(len(logins), 1) self.assertEqual(logins[0]["method"], "POST") self.assertIn("Email=tyler", logins[0]["body"]) self.assertIn("Passwd=api-password", logins[0]["body"]) def test_subsequent_calls_use_the_googlelogin_header(self): client = self.client() client.list_subscriptions() client.list_subscriptions() requests = self.stub.find_requests("/subscription/list") self.assertEqual(len(requests), 2) for entry in requests: self.assertEqual(entry["authorization"], "GoogleLogin auth=stub-auth-token") # The token is cached, so only one login happened. self.assertEqual(len(self.stub.find_requests("/accounts/ClientLogin")), 1) def test_bad_password_raises_authentication_error(self): client = self.client(api_password="wrong") with self.assertRaises(AuthenticationError): client.list_subscriptions() def test_credentials_are_form_encoded(self): # A password with & or = must not corrupt the form body. self.stub.password = "p&ss=word+plus" client = self.client(api_password="p&ss=word+plus") client.list_subscriptions() body = self.stub.find_requests("/accounts/ClientLogin")[0]["body"] self.assertIn("Passwd=p%26ss%3Dword%2Bplus", body) class SubscriptionTests(ClientTestCase): def test_subscriptions_are_parsed_with_categories(self): feeds = {feed.id: feed for feed in self.client().list_subscriptions()} self.assertEqual(len(feeds), 3) self.assertEqual(feeds[TECH_FEED].title, "Example Tech") self.assertEqual(feeds[TECH_FEED].categories, ["Tech"]) self.assertEqual(feeds[NEWS_FEED].categories, ["News"]) def test_feed_without_a_category_is_recognised(self): feeds = {feed.id: feed for feed in self.client().list_subscriptions()} self.assertEqual(feeds[SOLO_FEED].categories, []) self.assertEqual(feeds[SOLO_FEED].primary_category, "Uncategorised") def test_subscriptions_are_sorted_by_title(self): titles = [feed.title for feed in self.client().list_subscriptions()] self.assertEqual(titles, sorted(titles, key=str.casefold)) def test_query_asks_for_json(self): self.client().list_subscriptions() query = self.stub.find_requests("/subscription/list")[0]["query"] self.assertEqual(query["output"], ["json"]) def test_non_json_response_is_reported_clearly(self): self.stub.corrupt_json = True with self.assertRaises(FreshRSSError) as caught: self.client().list_subscriptions() self.assertIn("not JSON", str(caught.exception)) def test_probe_reports_success_and_feed_count(self): ok, detail = self.client().probe() self.assertTrue(ok) self.assertEqual(detail, "3 feeds") def test_probe_reports_failure_without_raising(self): ok, detail = self.client(api_password="wrong").probe() self.assertFalse(ok) self.assertTrue(detail) class StreamTests(ClientTestCase): def test_stream_query_parameters(self): self.client().stream_items(TECH_FEED, count=7, exclude_read=True) request = self.stub.find_requests("/stream/contents/")[0] self.assertEqual(request["query"]["output"], ["json"]) self.assertEqual(request["query"]["r"], ["d"]) self.assertEqual(request["query"]["n"], ["7"]) self.assertEqual(request["query"]["xt"], [READ_TAG]) self.assertTrue(request["query"]["ck"][0].isdigit()) def test_stream_id_is_path_encoded(self): self.client().stream_items(NEWS_FEED, count=1) raw_path = self.stub.find_requests("/stream/contents/")[0]["raw_path"] # The feed URL contains "?" and "/" which must not leak into the path. self.assertNotIn("?", raw_path.split("?")[0].split("/api/greader.php")[1]) self.assertIn("%3F", raw_path) def test_unread_filter_is_applied_upstream(self): client = self.client() everything = client.stream_items(TECH_FEED, count=50) unread = client.stream_items(TECH_FEED, count=50, exclude_read=True) self.assertEqual(len(everything), 3) self.assertEqual(len(unread), 2) self.assertNotIn("Already Read Post", [item.title for item in unread]) def test_count_bounds_the_result(self): items = self.client().stream_items(TECH_FEED, count=2) self.assertEqual(len(items), 2) def test_newest_first(self): items = self.client().stream_items(TECH_FEED, count=10) published = [item.published for item in items] self.assertEqual(published, sorted(published, reverse=True)) def test_older_than_is_passed_through(self): self.client().stream_items(TECH_FEED, count=5, older_than=1_699_500_000) self.assertEqual( self.stub.find_requests("/stream/contents/")[0]["query"]["ot"], ["1699500000"], ) def test_label_stream_selects_label_articles(self): items = self.client().stream_items(label_stream("News"), count=10) self.assertEqual({item.feed_id for item in items}, {NEWS_FEED}) def test_reading_list_covers_every_feed(self): items = self.client().stream_items(READING_LIST, count=50) self.assertEqual({item.feed_id for item in items}, {TECH_FEED, NEWS_FEED, SOLO_FEED}) def test_starred_stream_returns_only_starred(self): items = self.client().stream_items(STARRED, count=10) self.assertEqual([item.title for item in items], ["Starred Investigation"]) self.assertTrue(items[0].is_starred) def test_missing_stream_is_treated_as_empty(self): # A feed unsubscribed upstream must not break the catalog. self.stub.fail_next(404, path="/stream/contents/") self.assertEqual(self.client().stream_items(TECH_FEED, count=5), []) self.stub.fail_next(400, path="/stream/contents/") self.assertEqual(self.client().stream_items(TECH_FEED, count=5), []) class ItemParsingTests(ClientTestCase): def items_by_title(self, stream=TECH_FEED) -> dict: return {item.title: item for item in self.client().stream_items(stream, count=50)} def test_full_content_is_preferred_over_the_summary(self): self.stub.add_item( TECH_FEED, 99, "Full versus summary", content="

FULL BODY

", summary="

teaser

", ) item = self.items_by_title()["Full versus summary"] self.assertIn("FULL BODY", item.content_html) def test_summary_is_used_when_there_is_no_content(self): self.stub.add_item( TECH_FEED, 98, "Summary only", summary="

only teaser

", ) self.stub.items[TECH_FEED][-1].pop("content") item = self.items_by_title()["Summary only"] self.assertIn("only teaser", item.content_html) def test_item_fields_are_parsed(self): item = self.items_by_title()["A Tech Post & Its Friends"] self.assertEqual(item.feed_id, TECH_FEED) self.assertEqual(item.feed_title, "Example Tech") self.assertEqual(item.author, "A. Writer") self.assertEqual(item.url, "https://example.com/articles/1") self.assertEqual(item.published, 1_700_000_100) self.assertTrue(item.title.startswith("A Tech Post")) def test_missing_author_is_allowed(self): item = self.items_by_title(NEWS_FEED)["Markets Dip Slightly"] self.assertIsNone(item.author) def test_read_state_is_parsed(self): items = self.items_by_title() self.assertTrue(items["Already Read Post"].is_read) self.assertFalse(items["A Tech Post & Its Friends"].is_read) def test_kept_unread_overrides_the_read_tag(self): # FreshRSS keeps both tags when a read item is explicitly marked unread. item = self.items_by_title()["Already Read Post"] item.categories.append("user/-/state/com.google/kept-unread") self.assertFalse(item.is_read) def test_malformed_entries_are_skipped(self): self.stub.inject_raw_item(TECH_FEED, {"title": "no id"}) self.stub.inject_raw_item(TECH_FEED, "not even an object") titles = [item.title for item in self.client().stream_items(TECH_FEED, count=50)] self.assertNotIn("no id", titles) self.assertEqual(len(titles), 3) def test_untitled_item_gets_a_placeholder(self): self.stub.add_item(TECH_FEED, 97, "", content="

x

") titles = [item.title for item in self.client().stream_items(TECH_FEED, count=50)] self.assertIn("(untitled)", titles) def test_timestamps_are_utc_datetimes(self): item = self.items_by_title()["A Tech Post & Its Friends"] self.assertEqual(item.published_at, datetime(2023, 11, 14, 22, 15, 0, tzinfo=UTC)) self.assertEqual(item.published_at.tzinfo, UTC) def test_broken_timestamp_falls_back_to_the_epoch(self): # Every date field has to be unusable for the epoch fallback to apply; # while `updated` survives, using it is the correct behaviour. self.stub.add_item(TECH_FEED, 96, "Broken date", content="

x

") entry = self.stub.items[TECH_FEED][-1] for field in ("published", "updated", "timestampUsec"): entry.pop(field, None) item = self.items_by_title()["Broken date"] self.assertEqual(item.published, 0) self.assertEqual(item.published_at, datetime(1970, 1, 1, tzinfo=UTC)) def test_unusable_publication_date_falls_back_to_updated(self): self.stub.add_item(TECH_FEED, 94, "Only updated", content="

x

") entry = self.stub.items[TECH_FEED][-1] entry["published"] = "not-a-number" entry.pop("timestampUsec", None) entry["updated"] = 1_600_000_000 item = self.items_by_title()["Only updated"] self.assertEqual(item.published_at, datetime(2020, 9, 13, 12, 26, 40, tzinfo=UTC)) def test_timestamp_usec_is_used_when_published_is_absent(self): self.stub.add_item(TECH_FEED, 95, "Usec only", content="

x

") entry = self.stub.items[TECH_FEED][-1] entry.pop("published") entry["timestampUsec"] = "1699999999000000" item = self.items_by_title()["Usec only"] self.assertEqual(item.published, 1_699_999_999) class UnreadCountTests(ClientTestCase): def test_unread_counts_are_parsed(self): counts = self.client().unread_counts() self.assertEqual(counts[TECH_FEED], 2) self.assertEqual(counts[NEWS_FEED], 2) def test_unsupported_counts_raise_not_found(self): # The caller latches this and carries on without counts. self.stub.supports_unread_counts = False with self.assertRaises(NotFoundError): self.client().unread_counts() class MarkReadTests(ClientTestCase): def test_mark_read_fetches_the_write_token_and_posts_ids(self): client = self.client() identifier = self.stub.items[TECH_FEED][0]["id"] self.assertEqual(client.mark_read([identifier]), 1) token_requests = self.stub.find_requests("/reader/api/0/token") self.assertEqual(len(token_requests), 1) edits = self.stub.find_requests("/reader/api/0/edit-tag") self.assertEqual(len(edits), 1) self.assertEqual(edits[0]["method"], "POST") body = edits[0]["body"] self.assertIn("T=stub-write-token", body) self.assertIn("a=user%2F-%2Fstate%2Fcom.google%2Fread", body) self.assertIn("i=tag%3Agoogle.com%2C2005%3Areader%2Fitem", body) self.assertIn(identifier, self.stub.read) def test_mark_read_sends_one_i_parameter_per_id(self): ids = [entry["id"] for entry in self.stub.items[TECH_FEED]] self.assertEqual(self.client().mark_read(ids), 3) body = self.stub.find_requests("/reader/api/0/edit-tag")[0]["body"] self.assertEqual(body.count("&i="), 3) def test_item_id_survives_form_encoding(self): identifier = "tag:google.com,2005:reader/item/00000000000000ff" self.client().mark_read([identifier]) from urllib.parse import parse_qs body = self.stub.find_requests("/reader/api/0/edit-tag")[0]["body"] self.assertEqual(parse_qs(body)["i"], [identifier]) def test_mark_read_is_idempotent(self): client = self.client() identifier = self.stub.items[TECH_FEED][0]["id"] client.mark_read([identifier]) client.mark_read([identifier]) self.assertIn(identifier, self.stub.read) self.assertEqual(len(self.stub.find_requests("/reader/api/0/edit-tag")), 2) def test_mark_read_with_no_ids_makes_no_requests(self): self.assertEqual(self.client().mark_read([]), 0) self.assertEqual(self.stub.requests, []) def test_stale_write_token_is_refreshed_and_retried(self): client = self.client() identifier = self.stub.items[TECH_FEED][0]["id"] # Warm the token cache, then rotate the token upstream so the cached one # is rejected. The client must re-authenticate and retry rather than lose # the mark-read. client.mark_read([identifier]) self.stub.write_token = "rotated-token" self.stub.clear_read() client.mark_read([identifier]) self.assertIn(identifier, self.stub.read) self.assertEqual(len(self.stub.find_requests("/reader/api/0/edit-tag")), 3) def test_marking_read_removes_the_item_from_the_unread_stream(self): client = self.client() identifier = self.stub.items[TECH_FEED][0]["id"] client.mark_read([identifier]) unread = client.stream_items(TECH_FEED, count=50, exclude_read=True) self.assertNotIn(identifier, [item.id for item in unread]) class FailureHandlingTests(ClientTestCase): def test_transient_status_is_retried(self): client = self.client(retries=2) self.stub.fail_next(503, path="/subscription/list") feeds = client.list_subscriptions() self.assertEqual(len(feeds), 3) self.assertEqual(len(self.stub.find_requests("/subscription/list")), 2) def test_retries_are_bounded(self): client = self.client(retries=1) self.stub.fail_next(503, count=5, path="/subscription/list") with self.assertRaises(TransientError): client.list_subscriptions() self.assertEqual(len(self.stub.find_requests("/subscription/list")), 2) def test_server_error_is_not_swallowed(self): self.stub.fail_next(500, path="/subscription/list") with self.assertRaises(FreshRSSError) as caught: self.client(retries=0).list_subscriptions() self.assertEqual(caught.exception.status, 500) def test_unreachable_upstream_raises_transient_error(self): # Bind a port, then close it, so nothing is listening. import socket probe = socket.socket() probe.bind(("127.0.0.1", 0)) port = probe.getsockname()[1] probe.close() config = make_config(self.stub, api_base=f"http://127.0.0.1:{port}/api/greader.php") with self.assertRaises(TransientError): FreshRSSClient(config).list_subscriptions() def test_error_body_is_included_in_the_message(self): self.stub.fail_next(500, path="/subscription/list") with self.assertRaises(FreshRSSError) as caught: self.client(retries=0).list_subscriptions() self.assertIn("injected failure", str(caught.exception)) if __name__ == "__main__": unittest.main()