Skip to content

armgit / fli

Public Imported from GitHub
0

Google Flights MCP, CLI and Python Library

9.5 KB
Raw Blame
"""Tests for the ``top_n`` parameter on :meth:`SearchFlights.search` (issue #142).

Round-trip results "all come from a single airline" because the outbound
options are fetched once, sorted, and only the first ``top_n`` of them are
expanded into return-flight combinations (``_expand_multi_leg`` in
``fli/search/flights.py``). With the default sort that's usually five
outbounds from the same cheap carrier. ``top_n`` was already a library
parameter; these tests pin its contract now that it is also exposed on the
CLI and MCP tools:

* bounds (``1..10`` inclusive) are enforced with a clear ``ValueError``,
  raised before any network call;
* a round trip costs exactly ``1 + top_n`` page fetches — one outbound
  ``GetShoppingResults`` call plus one per expanded candidate;
* one-way searches never expand, regardless of ``top_n``.

Follows the existing mocking convention from ``tests/search/test_expand_multi_leg.py``:
``SearchFlights._fetch_flights`` is patched so no real HTTP call is made.
"""

from __future__ import annotations

import threading
from datetime import datetime, timedelta
from unittest.mock import patch

import pytest

from fli.models import (
    Airline,
    Airport,
    FlightLeg,
    FlightResult,
    FlightSearchFilters,
    FlightSegment,
    PassengerInfo,
    TripType,
)
from fli.search.flights import SearchFlights


def _future(days: int) -> str:
    """Return a YYYY-MM-DD date ``days`` from now — never a literal calendar date."""
    return (datetime.now() + timedelta(days=days)).strftime("%Y-%m-%d")


def _result(dep: Airport, arr: Airport, hour: int = 9) -> FlightResult:
    # hour stays well under 24 for every caller below (max 6 + 9 = 15), so a
    # plain ``hour + 3`` arrival never needs to roll over into the next day.
    # Relative to "now" — this is leg metadata for a
    # fabricated FlightResult, not a search filter's travel_date, but the
    # file's own rule (never a literal calendar date) still applies to it.
    departure = (datetime.now() + timedelta(days=35)).replace(
        hour=hour, minute=0, second=0, microsecond=0
    )
    return FlightResult(
        legs=[
            FlightLeg(
                airline=Airline.AA,
                flight_number="100",
                departure_airport=dep,
                arrival_airport=arr,
                departure_datetime=departure,
                arrival_datetime=departure + timedelta(hours=3),
                duration=180,
            )
        ],
        price=300,
        currency="USD",
        duration=180,
        stops=0,
    )


def _round_trip_filters() -> FlightSearchFilters:
    return FlightSearchFilters(
        trip_type=TripType.ROUND_TRIP,
        passenger_info=PassengerInfo(adults=1),
        flight_segments=[
            FlightSegment(
                departure_airport=[[Airport.JFK, 0]],
                arrival_airport=[[Airport.LHR, 0]],
                travel_date=_future(35),
            ),
            FlightSegment(
                departure_airport=[[Airport.LHR, 0]],
                arrival_airport=[[Airport.JFK, 0]],
                travel_date=_future(42),
            ),
        ],
    )


def _one_way_filters() -> FlightSearchFilters:
    return FlightSearchFilters(
        trip_type=TripType.ONE_WAY,
        passenger_info=PassengerInfo(adults=1),
        flight_segments=[
            FlightSegment(
                departure_airport=[[Airport.JFK, 0]],
                arrival_airport=[[Airport.LHR, 0]],
                travel_date=_future(35),
            ),
        ],
    )


class TestTopNBoundsValidation:
    """1 <= top_n <= 10 — a clear ValueError, raised before any network call."""

    @pytest.mark.parametrize("bad_top_n", [0, -1, 11, 100])
    def test_out_of_range_raises_value_error(self, bad_top_n):
        client = SearchFlights()
        with pytest.raises(ValueError, match="top_n"):
            client.search(_round_trip_filters(), top_n=bad_top_n)

    @pytest.mark.parametrize("good_top_n", [1, 5, 10])
    def test_boundary_values_do_not_raise_for_the_bound_check(self, good_top_n, monkeypatch):
        """1 and 10 are valid boundaries — the bound check itself must let them through."""
        client = SearchFlights()
        monkeypatch.setattr(SearchFlights, "_fetch_flights", lambda self, *a, **k: None)
        # None outbound flights short-circuits to None *after* the bound check —
        # reaching that path (instead of the ValueError) proves 1 and 10 passed.
        assert client.search(_round_trip_filters(), top_n=good_top_n) is None

    @pytest.mark.parametrize("bad_top_n", [0, 11])
    def test_out_of_range_never_reaches_the_network(self, bad_top_n, monkeypatch):
        """The bound check must short-circuit before _fetch_flights is ever called."""
        client = SearchFlights()

        def _unexpected_call(*_args, **_kwargs):
            raise AssertionError("_fetch_flights should not be called for an out-of-range top_n")

        monkeypatch.setattr(SearchFlights, "_fetch_flights", _unexpected_call)
        with pytest.raises(ValueError):
            client.search(_round_trip_filters(), top_n=bad_top_n)


class TestTopNTypeValidation:
    """Non-int top_n (and bool) must raise ValueError, not TypeError.

    A bare ``if not 1 <= top_n <= 10:`` comparison against a non-comparable
    type (``"5"``, ``None``) raises ``TypeError`` from Python itself, which
    ``classify_error()`` does NOT map to ``validation_error`` (it only
    matches ``ValidationError | ValueError``) — so it would have surfaced as
    ``unexpected_error`` instead. ``bool`` is an ``int`` subclass in Python
    (``True == 1``), so it silently passed the old bound check too; this
    rejects it explicitly rather than accepting it as 1.
    """

    @pytest.mark.parametrize("bad_top_n", ["5", 5.0, None, True, False])
    def test_non_int_or_bool_raises_value_error_not_type_error(self, bad_top_n):
        client = SearchFlights()
        with pytest.raises(ValueError, match="top_n"):
            client.search(_round_trip_filters(), top_n=bad_top_n)

    @pytest.mark.parametrize("bad_top_n", ["5", 5.0, None, True, False])
    def test_non_int_or_bool_never_reaches_the_network(self, bad_top_n, monkeypatch):
        client = SearchFlights()

        def _unexpected_call(*_args, **_kwargs):
            raise AssertionError("_fetch_flights should not be called for a non-int/bool top_n")

        monkeypatch.setattr(SearchFlights, "_fetch_flights", _unexpected_call)
        with pytest.raises(ValueError):
            client.search(_round_trip_filters(), top_n=bad_top_n)

    @pytest.mark.parametrize("good_top_n", [1, 10])
    def test_valid_edge_ints_still_pass(self, good_top_n, monkeypatch):
        """1 and 10 are valid int boundaries — must not be caught by the new type check."""
        client = SearchFlights()
        monkeypatch.setattr(SearchFlights, "_fetch_flights", lambda self, *a, **k: None)
        assert client.search(_round_trip_filters(), top_n=good_top_n) is None


class TestTopNFetchCount:
    """A round trip costs exactly 1 + top_n page fetches."""

    @pytest.mark.parametrize("top_n", [1, 5, 10])
    def test_fetch_count_is_one_plus_top_n(self, top_n):
        client = SearchFlights()
        # Exactly top_n outbound candidates so every one of them gets expanded
        # (top_n candidates fed into a top_n cap == top_n expansions, never fewer).
        outbound_candidates = [_result(Airport.JFK, Airport.LHR, hour=6 + i) for i in range(top_n)]

        lock = threading.Lock()
        state = {"n": 0}

        def _fake_fetch(filters, **kwargs):
            with lock:
                state["n"] += 1
                call_index = state["n"]
            if call_index == 1:
                return outbound_candidates
            return [_result(Airport.LHR, Airport.JFK, hour=6)]

        with patch.object(SearchFlights, "_fetch_flights", side_effect=_fake_fetch):
            results = client.search(_round_trip_filters(), top_n=top_n)

        assert state["n"] == 1 + top_n
        assert results is not None
        assert len(results) == top_n

    def test_more_outbound_candidates_than_top_n_still_costs_one_plus_top_n(self):
        """Cost model holds even when Google returns more outbounds than top_n."""
        top_n = 3
        client = SearchFlights()
        outbound_candidates = [_result(Airport.JFK, Airport.LHR, hour=6 + i) for i in range(10)]

        lock = threading.Lock()
        state = {"n": 0}

        def _fake_fetch(filters, **kwargs):
            with lock:
                state["n"] += 1
                call_index = state["n"]
            if call_index == 1:
                return outbound_candidates
            return [_result(Airport.LHR, Airport.JFK, hour=6)]

        with patch.object(SearchFlights, "_fetch_flights", side_effect=_fake_fetch):
            client.search(_round_trip_filters(), top_n=top_n)

        assert state["n"] == 1 + top_n


class TestTopNOneWayIgnored:
    """top_n only matters once there is a return leg to expand into."""

    def test_one_way_never_expands_regardless_of_top_n(self):
        client = SearchFlights()
        outbound = [_result(Airport.JFK, Airport.LHR)]

        with patch.object(SearchFlights, "_fetch_flights", return_value=outbound) as mocked_fetch:
            results = client.search(_one_way_filters(), top_n=9)

        # Only the single outbound fetch — no expansion calls at all.
        mocked_fetch.assert_called_once()
        assert results == outbound

    def test_one_way_default_top_n_produces_no_error(self):
        client = SearchFlights()
        with patch.object(SearchFlights, "_fetch_flights", return_value=None):
            assert client.search(_one_way_filters()) is None