Skip to content

AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary

37.1 KB
Raw Blame
"""Tests for the Meta Ad Library source.

Nothing here spawns a subprocess or touches the network. Fixture shapes mirror
live ScrapeCreators payloads captured 2026-09-14 (envelope keys, snapshot
fields, the searchResults/results asymmetry, null collation ids); brand names
are invented.
"""

import datetime
from unittest import mock

import pytest

from lib import meta_ads
from lib.meta_ads import (
    NO_CANDIDATES,
    RESOLVED,
    UNRESOLVED,
    build_item,
    dedupe_key,
    extract_promo_code,
    has_video,
    launch_date,
    names_match,
    resolve_page,
    search_meta_ads,
)

FROM_DATE = "2026-08-15"
TO_DATE = "2026-09-14"
TOKEN = "fake-sc-key"


def ad_row(**over):
    """One ad row in the live shape (trimmed of media blobs)."""
    base = {
        "ad_archive_id": "1000000000000001",
        "collation_id": "col-1",
        "collation_count": 3,
        "page_id": "300000000000001",
        "page_name": "Brightpan",
        "is_active": True,
        "start_date_string": "2026-09-01T07:00:00.000Z",
        "end_date_string": "2026-09-14T07:00:00.000Z",
        "publisher_platform": ["FACEBOOK", "INSTAGRAM", "THREADS"],
        "url": "https://www.facebook.com/ads/library/?id=1000000000000001",
        "reach_estimate": None,
        "spend": None,
        "snapshot": {
            "body": {"text": "Better mornings start here. Shop the Brightpan kettle."},
            "title": "",
            "cta_text": "Shop now",
            "display_format": "DCO",
            "link_url": "https://brightpan.example/collections/kettles",
            "cards": [],
            "videos": [],
        },
    }
    base.update(over)
    return base


def envelope(rows, key="searchResults", total=None, cursor=""):
    return {
        "success": True,
        "credits_remaining": 999,
        "credits_charged": 1,
        key: rows,
        "searchResultsCount": len(rows) if total is None else total,
        "cursor": cursor,
    }


def company_row(page_id, name, likes=100):
    return {
        "page_id": page_id,
        "name": name,
        "likes": likes,
        "category": "Appliances",
        "verification": "NOT_VERIFIED",
        "ig_username": "",
    }


class TestNameMatching:
    def test_exact_brand_matches(self):
        assert names_match("Brightpan", "Brightpan")

    def test_product_page_matches_umbrella_topic_by_shared_token(self):
        # The umbrella brand advertises under product-line pages; containment
        # in either direction is what resolves them.
        assert names_match("BrightpanCo", "Brightpan Kitchen")

    def test_short_token_never_matches(self):
        # "ai" is below the four-character floor, so an unrelated advertiser
        # that shares only that word must not match.
        assert not names_match("Vantage AI", "Jasper AI")

    def test_no_synonym_expansion(self):
        # The shared scoring tokenizer expands "ai" to artificial/intelligence.
        # Matching must not, or this pair would resolve as the same brand.
        assert not names_match("Vantage AI", "Artificial Intelligence Labs")

    def test_unrelated_names_do_not_match(self):
        assert not names_match("Brightpan", "Coastal Realty Group")

    def test_case_and_spacing_are_normalized(self):
        assert names_match("Bright iQ", "brightiq")


class TestResolvePage:
    def test_umbrella_brand_resolves_dominant_product_page(self):
        rows = (
            [ad_row(page_id="1", page_name="Brightpan Kitchen") for _ in range(14)]
            + [ad_row(page_id="2", page_name="Brightpan Beauty") for _ in range(5)]
            + [ad_row(page_id="3", page_name="Brightpan Home") for _ in range(4)]
            + [ad_row(page_id="9", page_name="Unrelated Deals Co") for _ in range(20)]
        )
        page, runner_ups, top, _strength = resolve_page("BrightpanCo", rows)
        assert page["name"] == "Brightpan Kitchen"
        assert page["id"] == "1"
        assert runner_ups == ["Brightpan Beauty", "Brightpan Home"]
        assert top == ""

    def test_exact_name_beats_busier_partial_match(self):
        # A reseller running more ads than the brand must not claim the topic.
        rows = [ad_row(page_id="1", page_name="Brightpan") for _ in range(11)] + [
            ad_row(page_id="2", page_name="Brightpan Outlet") for _ in range(18)
        ]
        page, _runner_ups, _top, strength = resolve_page("Brightpan", rows)
        assert page["name"] == "Brightpan"
        assert page["id"] == "1"
        assert strength == meta_ads.MATCH_EXACT

    def test_no_match_returns_top_unmatched_candidate(self):
        rows = [ad_row(page_id="9", page_name="Jasper AI") for _ in range(30)]
        page, runner_ups, top, _strength = resolve_page("Vantage AI", rows)
        assert page is None
        assert runner_ups == []
        assert top == "Jasper AI"

    def test_no_rows_returns_no_candidate_name(self):
        page, runner_ups, top, _strength = resolve_page("Brightpan", [])
        assert page is None
        assert runner_ups == []
        assert top == ""

    def test_rows_without_page_id_are_ignored(self):
        page, _runner_ups, top, _strength = resolve_page(
            "Brightpan", [ad_row(page_id="", page_name="Brightpan")]
        )
        assert page is None
        assert top == ""


class TestRowFields:
    def test_launch_date_from_iso_string(self):
        assert launch_date(ad_row()) == "2026-09-01"

    def test_launch_date_falls_back_to_epoch(self):
        epoch = int(
            datetime.datetime(2026, 9, 1, tzinfo=datetime.timezone.utc).timestamp()
        )
        row = ad_row(start_date_string="", start_date=epoch)
        assert launch_date(row) == "2026-09-01"

    def test_launch_date_missing_is_none(self):
        assert launch_date(ad_row(start_date_string="", start_date=None)) is None

    def test_dedupe_key_prefers_collation(self):
        assert dedupe_key(ad_row(collation_id="col-9")) == "collation:col-9"

    def test_dedupe_key_falls_back_to_archive_id(self):
        row = ad_row(collation_id=None, ad_archive_id="777")
        assert dedupe_key(row) == "ad:777"

    def test_has_video_detects_snapshot_videos(self):
        row = ad_row()
        row["snapshot"]["videos"] = [{"video_hd_url": "https://cdn.example/v.mp4"}]
        assert has_video(row)

    def test_has_video_detects_card_video(self):
        row = ad_row()
        row["snapshot"]["cards"] = [{"video_sd_url": "https://cdn.example/v.mp4"}]
        assert has_video(row)

    def test_has_video_false_for_image_ad(self):
        assert not has_video(ad_row())

    def test_promo_code_found_after_code_keyword(self):
        assert extract_promo_code("Take 30% off sitewide. Use code SUMMER30.") == "SUMMER30"

    def test_promo_code_ignores_model_numbers(self):
        assert extract_promo_code("The Brightpan E-325 is here.") is None

    def test_promo_code_ignores_lowercase_words_after_code(self):
        assert extract_promo_code("Our code of conduct is published.") is None

    def test_build_item_carries_every_rendered_field(self):
        item = build_item(ad_row(), {"id": "300000000000001", "name": "Brightpan"})
        assert item["title"].startswith("Better mornings")
        assert item["date"] == "2026-09-01"
        assert item["cta"] == "Shop now"
        assert item["display_format"] == "DCO"
        assert item["landing_url"] == "https://brightpan.example/collections/kettles"
        assert item["placements"] == ["FACEBOOK", "INSTAGRAM", "THREADS"]
        assert item["variants"] == 3
        assert item["advertiser"] == "Brightpan"
        assert item["url"].endswith("id=1000000000000001")

    def test_build_item_uses_card_link_when_snapshot_link_absent(self):
        row = ad_row()
        row["snapshot"]["link_url"] = ""
        row["snapshot"]["cards"] = [{"link_url": "https://brightpan.example/p/1"}]
        item = build_item(row, {"id": "1", "name": "Brightpan"})
        assert item["landing_url"] == "https://brightpan.example/p/1"

    def test_build_item_synthesizes_permalink_when_url_missing(self):
        item = build_item(ad_row(url=""), {"id": "1", "name": "Brightpan"})
        assert item["url"] == "https://www.facebook.com/ads/library/?id=1000000000000001"


class TestSearchMetaAds:
    def _run(self, responses, **kwargs):
        """Drive the lane with a scripted sequence of http.get returns."""
        calls = []

        def fake_get(url, **call_kwargs):
            calls.append((url, call_kwargs.get("params") or {}))
            nxt = responses.pop(0)
            if isinstance(nxt, Exception):
                raise nxt
            return nxt

        with mock.patch("lib.meta_ads.http.get", side_effect=fake_get):
            result = search_meta_ads(
                kwargs.pop("topic", "Brightpan"),
                FROM_DATE,
                TO_DATE,
                token=kwargs.pop("token", TOKEN),
                **kwargs,
            )
        return result, calls

    def test_missing_token_makes_no_calls(self):
        with mock.patch("lib.meta_ads.http.get") as get:
            result = search_meta_ads("Brightpan", FROM_DATE, TO_DATE, token="")
        get.assert_not_called()
        assert result["ads"] == []
        assert result["page"] is None

    def test_happy_path_resolves_and_classifies(self):
        discovery = envelope([ad_row() for _ in range(11)])
        window = envelope(
            [
                ad_row(ad_archive_id="1", collation_id="a", start_date_string="2026-09-01"),
                ad_row(ad_archive_id="2", collation_id="b", start_date_string="2026-08-20"),
                ad_row(ad_archive_id="3", collation_id="c", start_date_string="2026-04-03"),
            ],
            key="results",
        )
        result, calls = self._run([discovery, window])
        assert result["page"]["name"] == "Brightpan"
        assert [item["date"] for item in result["ads"]] == ["2026-09-01", "2026-08-20"]
        tally = result["tally"]
        assert tally["resolution"] == RESOLVED
        assert tally["launched_in_window"] == 2
        assert tally["still_running"] == 1
        assert tally["promo_codes"] == []
        assert tally["placements"] == ["FACEBOOK", "INSTAGRAM", "THREADS"]
        assert calls[0][0] == meta_ads.SEARCH_ADS_URL
        assert calls[1][0] == meta_ads.COMPANY_ADS_URL

    def test_window_fetch_requests_all_statuses(self):
        # Without this the endpoint's ACTIVE default hides creatives that
        # launched inside the window and already ended.
        result, calls = self._run(
            [envelope([ad_row()]), envelope([ad_row()], key="results")]
        )
        assert calls[1][1]["status"] == meta_ads.ENRICHMENT_STATUS
        assert calls[1][1]["start_date"] == FROM_DATE
        assert calls[1][1]["end_date"] == TO_DATE
        assert result["tally"]["launched_in_window"] == 1

    def test_ended_in_window_creative_is_kept_and_flagged(self):
        window = envelope(
            [ad_row(is_active=False, end_date_string="2026-09-05T07:00:00.000Z")],
            key="results",
        )
        result, _calls = self._run([envelope([ad_row()]), window])
        assert len(result["ads"]) == 1
        assert result["ads"][0]["is_active"] is False
        assert result["ads"][0]["ended_on"] == "2026-09-05"

    def test_company_search_fallback_resolves(self):
        discovery = envelope([ad_row(page_id="9", page_name="Unrelated Deals Co")])
        companies = envelope(
            [company_row("55", "Brightpan"), company_row("56", "Other Co")],
            key="results",
        )
        window = envelope([ad_row()], key="results")
        result, calls = self._run([discovery, companies, window])
        assert result["page"]["id"] == "55"
        assert calls[1][0] == meta_ads.SEARCH_COMPANIES_URL
        assert calls[2][1]["pageId"] == "55"

    def test_unresolved_names_top_candidate_and_skips_enrichment(self):
        discovery = envelope(
            [ad_row(page_id="9", page_name="Jasper AI") for _ in range(30)]
        )
        companies = envelope([company_row("7", "Jasper AI")], key="results")
        result, calls = self._run([discovery, companies], topic="Vantage AI")
        assert result["ads"] == []
        assert result["page"] is None
        assert result["tally"]["resolution"] == UNRESOLVED
        assert result["tally"]["top_candidate"] == "Jasper AI"
        assert all(call[0] != meta_ads.COMPANY_ADS_URL for call in calls)

    def test_zero_candidates_is_its_own_state(self):
        result, calls = self._run(
            [envelope([]), envelope([], key="results")], topic="Nonexistent Brand"
        )
        assert result["tally"]["resolution"] == NO_CANDIDATES
        assert result["tally"]["top_candidate"] == ""
        assert len(calls) == 2

    def test_page_override_skips_resolution(self):
        window = envelope([ad_row()], key="results")
        result, calls = self._run([window], page_override="300000000000001")
        assert len(calls) == 1
        assert calls[0][0] == meta_ads.COMPANY_ADS_URL
        assert result["page"]["id"] == "300000000000001"

    def test_variants_of_one_creative_collapse(self):
        window = envelope(
            [
                ad_row(ad_archive_id="1", collation_id="same", collation_count=4),
                ad_row(ad_archive_id="2", collation_id="same", collation_count=4),
            ],
            key="results",
        )
        result, _calls = self._run([envelope([ad_row()]), window])
        assert len(result["ads"]) == 1
        assert result["ads"][0]["variants"] == 4

    def test_null_collation_ids_stay_distinct(self):
        window = envelope(
            [
                ad_row(ad_archive_id="1", collation_id=None),
                ad_row(ad_archive_id="2", collation_id=None),
            ],
            key="results",
        )
        result, _calls = self._run([envelope([ad_row()]), window])
        assert len(result["ads"]) == 2

    def test_pagination_stops_at_depth_cap_and_flags_more(self):
        discovery = envelope([ad_row()])
        pages = [
            envelope([ad_row(ad_archive_id=str(i), collation_id=f"c{i}")],
                     key="results", total=222, cursor=f"cur{i}")
            for i in range(5)
        ]
        result, calls = self._run([discovery] + pages, depth="default")
        window_calls = [c for c in calls if c[0] == meta_ads.COMPANY_ADS_URL]
        assert len(window_calls) == 2  # default depth cap
        assert result["tally"]["cursor_remaining"] is True
        assert result["tally"]["endpoint_total"] == 222

    def test_pagination_stops_when_cursor_repeats(self):
        discovery = envelope([ad_row()])
        repeated = envelope(
            [ad_row(ad_archive_id="1", collation_id="c1")], key="results", cursor="same"
        )
        result, calls = self._run([discovery, repeated, repeated, repeated], depth="deep")
        window_calls = [c for c in calls if c[0] == meta_ads.COMPANY_ADS_URL]
        assert len(window_calls) == 2
        assert result["tally"]["cursor_remaining"] is False

    def test_pagination_stops_on_empty_cursor(self):
        discovery = envelope([ad_row()])
        window = envelope([ad_row()], key="results", cursor="")
        _result, calls = self._run([discovery, window], depth="deep")
        assert len([c for c in calls if c[0] == meta_ads.COMPANY_ADS_URL]) == 1

    @pytest.mark.parametrize("status", [401, 402, 403, 429])
    def test_fatal_status_stops_the_lane(self, status):
        err = meta_ads.http.HTTPError(f"boom {status}", status_code=status)
        result, calls = self._run([err])
        assert len(calls) == 1
        assert result["ads"] == []
        assert str(status) in result["error"]

    def test_fatal_status_during_enrichment_reports_error(self):
        err = meta_ads.http.HTTPError("rate limited", status_code=429)
        result, calls = self._run([envelope([ad_row()]), err])
        assert len(calls) == 2
        assert "429" in result["error"]
        assert result["ads"] == []

    def test_empty_success_response_is_not_an_error(self):
        result, _calls = self._run([envelope([]), envelope([], key="results")])
        assert "error" not in result
        assert result["tally"]["resolution"] == NO_CANDIDATES

    def test_transcripts_cover_newest_videos_across_pages(self):
        discovery = envelope([ad_row()])
        older_video = ad_row(
            ad_archive_id="old", collation_id="old", start_date_string="2026-08-20"
        )
        older_video["snapshot"]["videos"] = [{"video_hd_url": "https://cdn.example/a.mp4"}]
        newer_video = ad_row(
            ad_archive_id="new", collation_id="new", start_date_string="2026-09-10"
        )
        newer_video["snapshot"]["videos"] = [{"video_hd_url": "https://cdn.example/b.mp4"}]
        page_one = envelope([older_video], key="results", cursor="c1")
        page_two = envelope([newer_video], key="results", cursor="")
        transcript = {"transcript_available": True, "transcript": "Say what you need to say."}
        result, calls = self._run(
            [discovery, page_one, page_two, transcript, transcript], depth="default"
        )
        transcript_calls = [c for c in calls if c[0] == meta_ads.AD_TRANSCRIPT_URL]
        # Newest first: the page-two creative is transcribed before the older one.
        assert transcript_calls[0][1]["id"] == "new"
        assert result["tally"]["transcribed"] == 2
        assert result["ads"][0]["transcript"].startswith("Say what")

    def test_unavailable_transcript_is_not_an_error(self):
        discovery = envelope([ad_row()])
        video = ad_row()
        video["snapshot"]["videos"] = [{"video_hd_url": "https://cdn.example/a.mp4"}]
        window = envelope([video], key="results")
        result, _calls = self._run(
            [discovery, window, {"transcript_available": False, "transcript": None}]
        )
        assert "error" not in result
        assert result["tally"]["transcribed"] == 0
        assert result["ads"][0]["transcript"] == ""

    def test_quick_depth_pulls_no_transcripts(self):
        discovery = envelope([ad_row()])
        video = ad_row()
        video["snapshot"]["videos"] = [{"video_hd_url": "https://cdn.example/a.mp4"}]
        _result, calls = self._run(
            [discovery, envelope([video], key="results")], depth="quick"
        )
        assert all(c[0] != meta_ads.AD_TRANSCRIPT_URL for c in calls)

    def test_rate_limit_retries_are_disabled_on_every_call(self):
        # The shared client retries a 429 twice by default, which would both
        # contradict the no-further-calls contract and burn the lane budget.
        video = ad_row()
        video["snapshot"]["videos"] = [{"video_hd_url": "https://cdn.example/a.mp4"}]
        responses = [
            envelope([]),
            envelope([company_row("300000000000001", "Brightpan")], key="results"),
            envelope([video], key="results", cursor="next"),
            envelope([ad_row(ad_archive_id="second", collation_id="second")], key="results"),
            {"transcript_available": True, "transcript": "The kettle makes better mornings."},
        ]
        with mock.patch("lib.meta_ads.http.get", side_effect=responses) as get:
            result = search_meta_ads("Brightpan", FROM_DATE, TO_DATE, token=TOKEN)
        assert [call.args[0] for call in get.call_args_list] == [
            meta_ads.SEARCH_ADS_URL,
            meta_ads.SEARCH_COMPANIES_URL,
            meta_ads.COMPANY_ADS_URL,
            meta_ads.COMPANY_ADS_URL,
            meta_ads.AD_TRANSCRIPT_URL,
        ]
        assert {ad["id"] for ad in result["ads"]} == {"1000000000000001", "second"}
        assert result["tally"]["transcribed"] == 1
        deadline = get.call_args_list[0].kwargs["deadline_monotonic"]
        assert deadline is not None
        for call in get.call_args_list:
            assert call.kwargs["max_429_retries"] == 0, call.args[0]
            assert call.kwargs["deadline_monotonic"] == deadline, call.args[0]

    def test_exhausted_budget_keeps_what_was_fetched_and_reports_partial(self):
        # Running out of time must not discard creatives already in hand: thin
        # coverage caused by our own clock would otherwise read as a finding
        # about how little the advertiser is running.
        discovery = envelope([ad_row()])
        window = envelope([ad_row()], key="results", cursor="more")
        ticks = {"n": 0}
        real_monotonic = meta_ads.time.monotonic

        def creeping_clock():
            ticks["n"] += 1
            # Jump past the lane budget once the first window page is in.
            return real_monotonic() + (0 if ticks["n"] < 6 else 10_000)

        with mock.patch("lib.meta_ads.time.monotonic", side_effect=creeping_clock):
            with mock.patch("lib.meta_ads.http.get", side_effect=[discovery, window]):
                result = search_meta_ads(
                    "Brightpan", FROM_DATE, TO_DATE, token=TOKEN, depth="deep"
                )
        assert result.get("partial") is True
        assert "budget" in result["error"]
        assert len(result["ads"]) == 1
        assert result["page"]["name"] == "Brightpan"
        assert result["tally"]["cursor_remaining"] is True

    def test_country_override_is_passed_through(self):
        _result, calls = self._run(
            [envelope([ad_row()]), envelope([ad_row()], key="results")], country="GB"
        )
        assert calls[0][1]["country"] == "GB"
        assert calls[1][1]["country"] == "GB"


class TestWindowBoundaries:
    def test_creative_launched_on_window_edges_is_included(self):
        window = envelope(
            [
                ad_row(ad_archive_id="1", collation_id="a", start_date_string=FROM_DATE),
                ad_row(ad_archive_id="2", collation_id="b", start_date_string=TO_DATE),
            ],
            key="results",
        )
        with mock.patch(
            "lib.meta_ads.http.get", side_effect=[envelope([ad_row()]), window]
        ):
            result = search_meta_ads("Brightpan", FROM_DATE, TO_DATE, token=TOKEN)
        assert result["tally"]["launched_in_window"] == 2

    def test_undated_creative_counts_as_still_running(self):
        window = envelope(
            [ad_row(start_date_string="", start_date=None)], key="results"
        )
        with mock.patch(
            "lib.meta_ads.http.get", side_effect=[envelope([ad_row()]), window]
        ):
            result = search_meta_ads("Brightpan", FROM_DATE, TO_DATE, token=TOKEN)
        assert result["ads"] == []
        assert result["tally"]["still_running"] == 1


class TestTransientVersusFatal:
    """R11: only credential/account statuses discard the lane's work."""

    def _drive(self, responses, depth="default"):
        def fake_get(url, **kwargs):
            nxt = responses.pop(0)
            if isinstance(nxt, Exception):
                raise nxt
            return nxt

        with mock.patch("lib.meta_ads.http.get", side_effect=fake_get):
            return search_meta_ads(
                "Brightpan", FROM_DATE, TO_DATE, token=TOKEN, depth=depth
            )

    def test_transient_error_mid_pagination_keeps_fetched_creatives(self):
        # A 500 on page two must not throw away page one: those creatives were
        # already paid for and are real evidence.
        page_one = envelope([ad_row()], key="results", cursor="more")
        boom = meta_ads.http.HTTPError("upstream hiccup", status_code=500)
        result = self._drive([envelope([ad_row()]), page_one, boom], depth="deep")
        assert len(result["ads"]) == 1
        assert result["page"]["name"] == "Brightpan"
        assert result.get("partial") is True
        assert "500" in result["error"]

    def test_transient_error_during_transcripts_keeps_creatives(self):
        video = ad_row()
        video["snapshot"]["videos"] = [{"video_hd_url": "https://cdn.example/a.mp4"}]
        boom = meta_ads.http.HTTPError("transcoder down", status_code=503)
        result = self._drive(
            [envelope([ad_row()]), envelope([video], key="results"), boom]
        )
        assert len(result["ads"]) == 1
        assert result.get("partial") is True

    def test_fatal_status_mid_enrichment_keeps_paid_creatives(self):
        # A rate limit or expired credential means "stop calling", not "the
        # pages that already returned 200 were wrong". Discarding them throws
        # away evidence the user already paid for.
        page_one = envelope([ad_row()], key="results", cursor="more")
        boom = meta_ads.http.HTTPError("rate limited", status_code=429)
        result = self._drive([envelope([ad_row()]), page_one, boom], depth="deep")
        assert len(result["ads"]) == 1
        assert result["page"]["name"] == "Brightpan"
        assert result.get("partial") is True
        assert "429" in result["error"]

    def test_fatal_status_during_discovery_has_nothing_to_keep(self):
        boom = meta_ads.http.HTTPError("rate limited", status_code=429)
        result = self._drive([boom])
        assert result["ads"] == []
        assert result["page"] is None
        assert "429" in result["error"]


class TestShortBrandNames:
    """A brand whose every word is under the token floor must still resolve.

    The floor exists to stop a shared short word ("AI") from matching every
    advertiser that carries it. Applied without an exact-identity escape it
    also makes an initialism brand unresolvable against its own page, which
    fails the feature silently for a whole class of well-known names.
    """

    def test_initialism_brand_matches_its_own_page_exactly(self):
        assert names_match("KLM", "KLM")
        assert names_match("BMW", "bmw")

    def test_initialism_brand_still_rejects_an_unrelated_page(self):
        assert not names_match("KLM", "Kitchen Lighting Market")

    def test_initialism_resolves_through_the_exact_tier(self):
        rows = [ad_row(page_id="1", page_name="KLM") for _ in range(2)] + [
            ad_row(page_id="2", page_name="Unrelated Deals Co") for _ in range(30)
        ]
        page, _runner_ups, _top, strength = resolve_page("KLM", rows)
        assert page["name"] == "KLM"
        assert strength == meta_ads.MATCH_EXACT


class TestResolutionStrength:
    def test_shared_whole_token_outranks_mere_containment(self):
        # "Brightpan Kitchen" shares the whole token; the containment-only
        # page must not win on ad volume alone.
        rows = [ad_row(page_id="1", page_name="Brightpan Kitchen") for _ in range(2)] + [
            ad_row(page_id="2", page_name="Superbrightpanel Co") for _ in range(40)
        ]
        page, _runner_ups, _top, strength = resolve_page("Brightpan", rows)
        assert page["name"] == "Brightpan Kitchen"
        assert strength == meta_ads.MATCH_TOKEN

    def test_containment_tier_is_reported_as_such(self):
        rows = [ad_row(page_id="1", page_name="Brightpan Kitchen") for _ in range(3)]
        _page, _runner_ups, _top, strength = resolve_page("BrightpanCo", rows)
        assert strength == meta_ads.MATCH_CONTAINED

    def test_transcript_cap_bounds_paid_requests_not_successes(self):
        # Every transcript call costs a credit whether or not one comes back,
        # so an upstream with no transcripts must not keep the lane calling.
        videos = []
        for i in range(10):
            row = ad_row(ad_archive_id=str(i), collation_id=f"c{i}")
            row["snapshot"]["videos"] = [{"video_hd_url": "https://cdn.example/v.mp4"}]
            videos.append(row)
        unavailable = {"transcript_available": False, "transcript": None}
        responses = [envelope([ad_row()]), envelope(videos, key="results")] + [
            unavailable
        ] * 10
        calls = []

        def fake_get(url, **kwargs):
            calls.append(url)
            return responses.pop(0)

        with mock.patch("lib.meta_ads.http.get", side_effect=fake_get):
            result = search_meta_ads(
                "Brightpan", FROM_DATE, TO_DATE, token=TOKEN, depth="default"
            )
        transcript_calls = [c for c in calls if c == meta_ads.AD_TRANSCRIPT_URL]
        assert len(transcript_calls) == 3  # the default-depth cap, not 10
        assert result["tally"]["transcribed"] == 0

    def test_default_depth_run_stays_inside_its_documented_credit_ceiling(self):
        videos = []
        for i in range(10):
            row = ad_row(ad_archive_id=str(i), collation_id=f"c{i}")
            row["snapshot"]["videos"] = [{"video_hd_url": "https://cdn.example/v.mp4"}]
            videos.append(row)
        responses = [
            envelope([ad_row(page_id="9", page_name="Unrelated Deals Co")]),
            envelope([company_row("55", "Brightpan")], key="results"),
            envelope(videos, key="results", cursor="more"),
            envelope(videos, key="results", cursor="more"),
        ] + [{"transcript_available": True, "transcript": "hello"}] * 5
        calls = []

        def fake_get(url, **kwargs):
            calls.append(url)
            return responses.pop(0)

        with mock.patch("lib.meta_ads.http.get", side_effect=fake_get):
            search_meta_ads("Brightpan", FROM_DATE, TO_DATE, token=TOKEN, depth="default")
        # 1 discovery + 1 company fallback + 2 pages + 3 transcripts = 7
        assert len(calls) <= 7


class TestGenericTokens:
    """A word several advertisers share is a category, not an identity."""

    def test_category_word_does_not_resolve_an_unrelated_advertiser(self):
        rows = (
            [ad_row(page_id="1", page_name="Acme Kitchen") for _ in range(3)]
            + [ad_row(page_id="2", page_name="Kitchen World") for _ in range(40)]
            + [ad_row(page_id="3", page_name="Kitchen Depot") for _ in range(20)]
        )
        page, _runner_ups, _top, _strength = resolve_page("Acme Kitchen", rows)
        assert page["name"] == "Acme Kitchen"

    def test_a_word_only_one_advertiser_uses_still_identifies(self):
        rows = [ad_row(page_id="1", page_name="Brightpan Supply") for _ in range(2)] + [
            ad_row(page_id="2", page_name="Unrelated Deals Co") for _ in range(40)
        ]
        page, _runner_ups, _top, strength = resolve_page("Brightpan Supply news", rows)
        assert page["name"] == "Brightpan Supply"
        assert strength == meta_ads.MATCH_TOKEN

    def test_shared_category_alone_resolves_nothing(self):
        rows = [ad_row(page_id="1", page_name="Kitchen World") for _ in range(30)] + [
            ad_row(page_id="2", page_name="Kitchen Depot") for _ in range(20)
        ]
        page, _runner_ups, top, _strength = resolve_page("Acme Kitchen", rows)
        assert page is None
        assert top == "Kitchen World"


class TestHeadTokenIdentity:
    """A multi-word topic carries its identity in the leading word.

    Counting how many advertisers share a word cannot carry this: a result set
    holding one lookalike makes its category word look perfectly distinctive.
    """

    def test_lone_category_lookalike_resolves_nothing(self):
        rows = [ad_row(page_id="9", page_name="Kitchen World") for _ in range(30)]
        page, _runner_ups, top, _strength = resolve_page("Acme Kitchen", rows)
        assert page is None
        assert top == "Kitchen World"

    def test_brand_page_wins_over_a_busier_category_lookalike(self):
        rows = [ad_row(page_id="1", page_name="Acme Kitchen") for _ in range(3)] + [
            ad_row(page_id="9", page_name="Kitchen World") for _ in range(40)
        ]
        page, _runner_ups, _top, _strength = resolve_page("Acme Kitchen", rows)
        assert page["name"] == "Acme Kitchen"

    def test_a_page_sharing_only_the_brand_word_fails_closed(self):
        # "Acme Supply" may or may not belong to the brand behind "Acme
        # Kitchen"; the name alone cannot say. Resolving it would risk
        # attributing another firm's ads, so the lane declines and names the
        # candidate instead, which the page override recovers in one flag.
        rows = [ad_row(page_id="1", page_name="Acme Supply") for _ in range(3)]
        page, _runner_ups, top, _strength = resolve_page("Acme Kitchen", rows)
        assert page is None
        assert top == "Acme Supply"

    def test_single_word_topic_keeps_its_umbrella_reach(self):
        # Nothing to strip, so the whole name is the head and product-line
        # pages still resolve.
        rows = [ad_row(page_id="1", page_name="Brightpan Kitchen") for _ in range(14)]
        page, _runner_ups, _top, _strength = resolve_page("BrightpanCo", rows)
        assert page["name"] == "Brightpan Kitchen"


class TestDescriptorLeadingTopics:
    """A research topic does not always open with the brand."""

    def test_intent_modifier_before_the_brand_still_resolves_it(self):
        rows = [ad_row(page_id="1", page_name="Acme Grills") for _ in range(5)]
        page, _runner_ups, _top, _strength = resolve_page("best Acme grills", rows)
        assert page["name"] == "Acme Grills"

    @pytest.mark.parametrize(
        "topic,page_name",
        [
            ("best Acme grills", "Acme Grills"),
            ("latest Acme cookware", "Acme Cookware"),
            ("top Acme deals", "Acme Deals"),
        ],
    )
    def test_common_descriptors_do_not_become_the_identity(self, topic, page_name):
        rows = [ad_row(page_id="1", page_name=page_name) for _ in range(5)]
        page, _runner_ups, _top, _strength = resolve_page(topic, rows)
        assert page["name"] == page_name

    def test_a_category_lookalike_is_still_rejected_under_a_descriptor(self):
        # "grill" appears inside "grills", but it is the category word, not
        # the brand, so it must not carry the whole topic with it.
        rows = [ad_row(page_id="9", page_name="Grill World") for _ in range(50)]
        page, _runner_ups, _top, _strength = resolve_page("best Acme grills", rows)
        assert page is None


class TestBrandPositionIndependence:
    """The brand does not always lead the topic."""

    @pytest.mark.parametrize(
        "topic,page",
        [
            ("Kitchen by Crate and Barrel", "Crate and Barrel"),
            ("smart home Acme", "Acme Home"),
            ("cookware from Acme Supply", "Acme Supply"),
        ],
    )
    def test_a_topic_that_spells_out_the_name_resolves_it(self, topic, page):
        # The topic names the company outright, so where in the phrase that
        # name sits cannot decide the match.
        rows = [ad_row(page_id="1", page_name=page) for _ in range(6)]
        resolved, _runner_ups, _top, _strength = resolve_page(topic, rows)
        assert resolved["name"] == page

    def test_a_lookalike_is_still_rejected_because_the_topic_omits_a_word(self):
        # "Kitchen World" carries "world", which a topic about "Acme Kitchen"
        # never mentions, so the topic is not naming this company.
        rows = [ad_row(page_id="9", page_name="Kitchen World") for _ in range(30)]
        page, _runner_ups, _top, _strength = resolve_page("Acme Kitchen", rows)
        assert page is None


class TestPartialNamesCannotClaimATopic:
    """A fragment of the topic is not an advertiser's whole name."""

    def test_a_page_named_only_the_category_word_is_rejected(self):
        # Trivially "covered" by the topic, but it accounts for one word of it
        # and none of the brand.
        rows = [ad_row(page_id="9", page_name="Kitchen") for _ in range(30)]
        page, _runner_ups, _top, _strength = resolve_page("Acme Kitchen", rows)
        assert page is None

    def test_a_page_named_the_whole_single_word_topic_still_resolves(self):
        rows = [ad_row(page_id="1", page_name="Acme Co") for _ in range(4)]
        page, _runner_ups, _top, _strength = resolve_page("Acme", rows)
        assert page["name"] == "Acme Co"

    def test_coverage_needs_more_than_one_topic_word(self):
        rows = [ad_row(page_id="9", page_name="Grills") for _ in range(30)]
        page, _runner_ups, _top, _strength = resolve_page("best Acme grills", rows)
        assert page is None


class TestCoverageBeatsVolume:
    def test_the_page_matching_more_of_the_topic_wins(self):
        # Two pages share the brand word; the one that also matches the rest
        # of the topic is the better answer however much the other spends.
        rows = [ad_row(page_id="1", page_name="Acme Kitchen Co") for _ in range(2)] + [
            ad_row(page_id="9", page_name="Acme AI") for _ in range(80)
        ]
        page, _runner_ups, _top, _strength = resolve_page("Acme Kitchen", rows)
        assert page["name"] == "Acme Kitchen Co"


class TestWholeNameRequired:
    """Greptile round 7: a partial name must not stand in for a whole one."""

    def test_a_page_with_a_word_the_topic_never_mentions_is_rejected(self):
        # "Acme AI" and the brand behind "Acme Kitchen" share one word and
        # nothing else; "ai" appears nowhere in the topic.
        rows = [ad_row(page_id="9", page_name="Acme AI") for _ in range(80)]
        page, _runner_ups, _top, _strength = resolve_page("Acme Kitchen", rows)
        assert page is None

    def test_short_words_of_the_page_name_are_counted(self):
        # The page name's short word is part of its identity, so ignoring it
        # would let the name look fully covered when it is not.
        rows = [ad_row(page_id="9", page_name="Acme AI") for _ in range(5)]
        page, _runner_ups, _top, _strength = resolve_page("Acme AI", rows)
        assert page["name"] == "Acme AI"

    def test_word_boundaries_are_respected_in_coverage(self):
        # "Cart Wheel" is not named by "Acme Cartwheel" merely because its
        # letters appear inside a longer word.
        rows = [ad_row(page_id="9", page_name="Cart Wheel") for _ in range(30)]
        page, _runner_ups, _top, _strength = resolve_page("Acme Cartwheel", rows)
        assert page is None