From 1472c86e68fce735cf1463ec0bc5076ee0a7c7d7 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Wed, 11 Nov 2026 12:25:47 -0600 Subject: [PATCH 1/3] feat: add /achievement to look up a WoW: Forever achievement's points, description and category --- pyrefly-baseline.json | 7 + src/sidequest_bot/api_client.py | 32 ++ src/sidequest_bot/plugins/achievements.py | 215 +++++++++++++ tests/test_achievements.py | 375 ++++++++++++++++++++++ 4 files changed, 629 insertions(+) create mode 100644 src/sidequest_bot/plugins/achievements.py create mode 100644 tests/test_achievements.py diff --git a/pyrefly-baseline.json b/pyrefly-baseline.json index 3c21323..c920261 100644 --- a/pyrefly-baseline.json +++ b/pyrefly-baseline.json @@ -1,5 +1,12 @@ { "errors": [ + { + "column": 15, + "path": "src/sidequest_bot/plugins/achievements.py", + "name": "bad-override", + "concise_description": "Class member `_AchievementMatchSelect.callback` overrides parent class `Select` in an inconsistent manner", + "severity": "error" + }, { "column": 15, "path": "src/sidequest_bot/plugins/event_sync.py", diff --git a/src/sidequest_bot/api_client.py b/src/sidequest_bot/api_client.py index 554798c..4b7559d 100644 --- a/src/sidequest_bot/api_client.py +++ b/src/sidequest_bot/api_client.py @@ -11,6 +11,9 @@ from tenacity import AsyncRetrying, before_sleep_log, retry_if_exception, stop_after_attempt, wait_exponential from sidequest_common.schemas import ( + AchievementCategorySchema, + AchievementCategoryTree, + AchievementSchema, ActivityAck, AddonSchema, AnnouncementPosted, @@ -96,6 +99,7 @@ _GROUP_SESSIONS = TypeAdapter(list[GroupSessionSchema]) _XP_GRANTS = TypeAdapter(list[XPGrantResult]) _ADDONS = TypeAdapter(list[AddonSchema]) +_ACHIEVEMENT_CATEGORIES = TypeAdapter(list[AchievementCategoryTree]) class ItemSummary(BaseModel): @@ -981,6 +985,34 @@ async def get_item(self, item_id: int) -> Item: data = await self._request("GET", f"/api/items/{item_id}") return _parse(Item.model_validate, data) + # --- Achievements + + async def list_achievement_categories(self) -> list[AchievementCategoryTree]: + """Every root achievement category with its subcategories (the public ``/api/achievements/categories`` GET). + + 503 if Battle.net isn't configured or didn't answer. + """ + data = await self._request("GET", "/api/achievements/categories") + return _parse(_ACHIEVEMENT_CATEGORIES.validate_python, data) + + async def get_achievement_category(self, category_id: int) -> AchievementCategorySchema: + """One achievement category and its achievements (the public ``/api/achievements/categories/{id}`` GET). + + Raises ``NotFoundError`` for an unknown category, or ``APIError`` (status 503) if Battle.net isn't + configured or didn't answer. + """ + data = await self._request("GET", f"/api/achievements/categories/{category_id}") + return _parse(AchievementCategorySchema.model_validate, data) + + async def get_achievement(self, achievement_id: int) -> AchievementSchema: + """One achievement by its game ID (the public ``/api/achievements/{id}`` GET). + + Raises ``NotFoundError`` for an unknown achievement, or ``APIError`` (status 503) if Battle.net isn't + configured or didn't answer. + """ + data = await self._request("GET", f"/api/achievements/{achievement_id}") + return _parse(AchievementSchema.model_validate, data) + # --- Auctions async def get_item_price(self, item_id: int) -> ItemAuctionPrice: diff --git a/src/sidequest_bot/plugins/achievements.py b/src/sidequest_bot/plugins/achievements.py new file mode 100644 index 0000000..34b0ce7 --- /dev/null +++ b/src/sidequest_bot/plugins/achievements.py @@ -0,0 +1,215 @@ +"""Achievement lookup: ``/achievement `` shows a WoW: Forever achievement's points, description and category. + +Battle.net's achievement API has no name search, so this cog flattens the category tree (``GET +/api/achievements/categories`` then ``GET /api/achievements/categories/{id}`` for each category) into one list, +cached at module scope for :data:`CACHE_TTL` — the same hour the site itself caches this Battle.net-backed reference +data at the edge (``EDGE_REFERENCE_CACHE`` in the website's ``reference/controllers.py``). +""" + +import asyncio +import logging +from datetime import datetime, timedelta +from http import HTTPStatus +from typing import TYPE_CHECKING + +import discord +from discord import app_commands +from discord.ext import commands + +from sidequest_bot.api_client import APIError, NotFoundError +from sidequest_bot.bot import SideQuestBot # noqa: TC001 # discord.py evaluates app-command annotations at runtime +from sidequest_bot.lib.embeds import Colors, make_embed, truncate + +if TYPE_CHECKING: + from collections.abc import Sequence + + from sidequest_bot.api_client import SideQuestAPI + from sidequest_common.schemas import AchievementSchema, AchievementSummary + +logger = logging.getLogger(__name__) + +ACHIEVEMENT_PAGE_URL = "https://sidequest-guild.com/achievements/detail/?id={achievement_id}" +DESCRIPTION_LIMIT = 4096 +MAX_AUTOCOMPLETE_RESULTS = 25 +MAX_OTHER_MATCHES = 5 +CACHE_TTL = timedelta(hours=1) +"""How long the flattened achievement catalog is cached; matches the site's own edge cache for this data.""" +NOT_FOUND_HINT = "Try a shorter word, or pick a suggestion as you type." +UNAVAILABLE_MESSAGE = "Achievement lookup isn't available right now; try again shortly." + + +def build_achievement_embed(achievement: AchievementSchema) -> discord.Embed: + """The achievement's name, points, description, category and icon, linking to its site page.""" + embed = make_embed( + title=achievement.name, + description=truncate(achievement.description, DESCRIPTION_LIMIT), + color=Colors.SITE_GOLD, + timestamp=False, + ) + embed.url = ACHIEVEMENT_PAGE_URL.format(achievement_id=achievement.id) + if achievement.icon_url: + embed.set_thumbnail(url=achievement.icon_url) + embed.add_field(name="Points", value=str(achievement.points)) + if achievement.category: + embed.add_field(name="Category", value=achievement.category) + if achievement.reward_description: + embed.add_field(name="Reward", value=truncate(achievement.reward_description), inline=False) + embed.add_field( + name="Site", + value=f"[View on site]({ACHIEVEMENT_PAGE_URL.format(achievement_id=achievement.id)})", + inline=False, + ) + return embed + + +def match_option(match: AchievementSummary) -> discord.SelectOption: + """One search result as a select option, with its points as the description.""" + return discord.SelectOption(label=truncate(match.name, 100), value=str(match.id), description=f"{match.points} pts") + + +class _AchievementCache: + """The flattened achievement catalog, rebuilt at most once per :data:`CACHE_TTL`.""" + + def __init__(self) -> None: + self._achievements: list[AchievementSummary] = [] + self._built_at: datetime | None = None + self._lock = asyncio.Lock() + + async def get(self, api: SideQuestAPI) -> list[AchievementSummary]: + """The cached catalog, rebuilding it first if stale or never built.""" + async with self._lock: + now = discord.utils.utcnow() + if self._built_at is None or now - self._built_at > CACHE_TTL: + self._achievements = await self._build(api) + self._built_at = now + return self._achievements + + @staticmethod + async def _build(api: SideQuestAPI) -> list[AchievementSummary]: + """Every achievement in every category, fetched concurrently; a category Battle.net can't answer is skipped.""" + roots = await api.list_achievement_categories() + category_ids = [root.id for root in roots] + [child.id for root in roots for child in root.children] + pages = await asyncio.gather( + *(api.get_achievement_category(category_id) for category_id in category_ids), return_exceptions=True + ) + achievements: list[AchievementSummary] = [] + for page in pages: + if isinstance(page, APIError): + continue + if isinstance(page, BaseException): + raise page + achievements.extend(page.achievements) + return achievements + + +_cache = _AchievementCache() + + +async def _autocomplete_achievement( + interaction: discord.Interaction[SideQuestBot], current: str +) -> list[app_commands.Choice[str]]: + """Up to 25 achievements matching ``current``, from the cached catalog; empty if Battle.net can't be reached.""" + try: + achievements = await _cache.get(interaction.client.api) + except APIError: + return [] + current_fold = current.strip().casefold() + if current_fold: + achievements = [a for a in achievements if current_fold in a.name.casefold()] + return [ + app_commands.Choice(name=truncate(f"{a.name} ({a.points} pts)", 100), value=str(a.id)) + for a in achievements[:MAX_AUTOCOMPLETE_RESULTS] + ] + + +async def _fetch_achievement_embed( + interaction: discord.Interaction[SideQuestBot], achievement_id: int +) -> discord.Embed | str: + """The achievement's embed, or a plain-text error if the lookup failed.""" + try: + found = await interaction.client.api.get_achievement(achievement_id) + except NotFoundError: + return "That achievement is gone." + except APIError as exc: + if exc.status_code == HTTPStatus.SERVICE_UNAVAILABLE: + return UNAVAILABLE_MESSAGE + logger.warning("Achievement lookup failed for %s", achievement_id, exc_info=True) + return "Couldn't look up that achievement right now; try again shortly." + return build_achievement_embed(found) + + +class _AchievementMatchSelect(discord.ui.Select["AchievementMatchView"]): + """The select menu itself; its callback swaps the parent view's embed to the chosen achievement.""" + + def __init__(self, matches: Sequence[AchievementSummary]) -> None: + super().__init__(placeholder="Other matches", options=[match_option(match) for match in matches]) + + async def callback(self, interaction: discord.Interaction[SideQuestBot]) -> None: + achievement_id = int(self.values[0]) + result = await _fetch_achievement_embed(interaction, achievement_id) + if isinstance(result, str): + await interaction.response.send_message(result, ephemeral=True) + return + await interaction.response.edit_message(embed=result, view=self.view) + + +class AchievementMatchView(discord.ui.View): + """A select menu of up to :data:`MAX_OTHER_MATCHES` other search matches, swapping the shown embed on pick.""" + + def __init__(self, matches: Sequence[AchievementSummary]) -> None: + super().__init__(timeout=180) + self._select = _AchievementMatchSelect(matches) + self.add_item(self._select) + + +class AchievementsCog(commands.Cog): + """``/achievement`` lookup.""" + + def __init__(self, bot: SideQuestBot) -> None: + self.bot = bot + + @app_commands.command(name="achievement", description="Look up a WoW: Forever achievement.") + @app_commands.describe(name="Achievement name, or pick a suggestion as you type") + @app_commands.autocomplete(name=_autocomplete_achievement) + async def achievement_command(self, interaction: discord.Interaction[SideQuestBot], name: str) -> None: + """Resolve ``name`` to an achievement id (from autocomplete, or a name search) and show its embed.""" + await interaction.response.defer() + if name.isdigit(): + result = await _fetch_achievement_embed(interaction, int(name)) + if isinstance(result, str): + await interaction.followup.send(result, ephemeral=True) + return + await interaction.followup.send(embed=result) + return + try: + achievements = await _cache.get(self.bot.api) + except APIError as exc: + if exc.status_code == HTTPStatus.SERVICE_UNAVAILABLE: + await interaction.followup.send(UNAVAILABLE_MESSAGE, ephemeral=True) + return + logger.warning("Achievement catalog failed to build", exc_info=True) + await interaction.followup.send( + "Couldn't search achievements right now; try again shortly.", ephemeral=True + ) + return + name_fold = name.casefold() + matches = [a for a in achievements if name_fold in a.name.casefold()] + if not matches: + await interaction.followup.send( + f"No achievements found matching **{name}**. {NOT_FOUND_HINT}", ephemeral=True + ) + return + best, others = matches[0], matches[1 : 1 + MAX_OTHER_MATCHES] + result = await _fetch_achievement_embed(interaction, best.id) + if isinstance(result, str): + await interaction.followup.send(result, ephemeral=True) + return + if others: + await interaction.followup.send(embed=result, view=AchievementMatchView(others)) + else: + await interaction.followup.send(embed=result) + + +async def setup(bot: SideQuestBot) -> None: + """Register the cog.""" + await bot.add_cog(AchievementsCog(bot)) diff --git a/tests/test_achievements.py b/tests/test_achievements.py new file mode 100644 index 0000000..1b25650 --- /dev/null +++ b/tests/test_achievements.py @@ -0,0 +1,375 @@ +"""Unit tests for the achievements plugin: embed builders, the catalog cache, autocomplete and ``/achievement``.""" + +from datetime import timedelta +from types import SimpleNamespace +from unittest.mock import AsyncMock, Mock + +import discord +import pytest + +import sidequest_bot.plugins.achievements as achievements_module +from sidequest_bot.api_client import APIError, NotFoundError +from sidequest_bot.plugins.achievements import ( + CACHE_TTL, + NOT_FOUND_HINT, + UNAVAILABLE_MESSAGE, + AchievementMatchView, + AchievementsCog, + _AchievementCache, + _autocomplete_achievement, + build_achievement_embed, + match_option, +) +from sidequest_common.schemas import ( + AchievementCategorySchema, + AchievementCategorySummary, + AchievementCategoryTree, + AchievementCriterion, + AchievementSchema, + AchievementSummary, +) + + +@pytest.fixture(autouse=True) +def _reset_cache() -> None: + achievements_module._cache = achievements_module._AchievementCache() + + +def _summary( + *, achievement_id: int = 1, name: str = "First Steps", points: int = 10, icon_url: str | None = None +) -> AchievementSummary: + return AchievementSummary(id=achievement_id, name=name, points=points, icon_url=icon_url) + + +def _achievement( + *, + achievement_id: int = 1, + name: str = "First Steps", + description: str = "Take your first steps.", + points: int = 10, + icon_url: str | None = "https://render.worldofwarcraft.com/icons/56/ach.jpg", + category: str | None = "General", + reward_description: str | None = None, +) -> AchievementSchema: + return AchievementSchema( + id=achievement_id, + name=name, + description=description, + points=points, + icon_url=icon_url, + category=category, + reward_description=reward_description, + criteria=AchievementCriterion(description=None, amount=1, children=[]), + ) + + +def _make_cog(*, api: object | None = None) -> AchievementsCog: + cog = AchievementsCog.__new__(AchievementsCog) + cog.bot = SimpleNamespace(api=api or AsyncMock()) + return cog + + +def _make_interaction(*, api: object | None = None) -> Mock: + interaction = Mock(spec=discord.Interaction) + interaction.response = Mock() + interaction.response.defer = AsyncMock() + interaction.response.send_message = AsyncMock() + interaction.response.edit_message = AsyncMock() + interaction.followup = Mock() + interaction.followup.send = AsyncMock() + interaction.client = SimpleNamespace(api=api or AsyncMock()) + return interaction + + +class TestBuildAchievementEmbed: + def test_sets_title_color_url_and_thumbnail(self) -> None: + embed = build_achievement_embed(_achievement(achievement_id=42, name="Explorer")) + assert embed.title == "Explorer" + assert embed.color == discord.Colour(0xD8AB5C) + assert embed.url == "https://sidequest-guild.com/achievements/detail/?id=42" + assert embed.thumbnail.url == "https://render.worldofwarcraft.com/icons/56/ach.jpg" + + def test_no_icon_leaves_thumbnail_unset(self) -> None: + embed = build_achievement_embed(_achievement(icon_url=None)) + assert embed.thumbnail.url is None + + def test_includes_points_and_category(self) -> None: + embed = build_achievement_embed(_achievement(points=25, category="Quests")) + field_names = {field.name: field.value for field in embed.fields} + assert field_names["Points"] == "25" + assert field_names["Category"] == "Quests" + + def test_omits_category_when_unset(self) -> None: + embed = build_achievement_embed(_achievement(category=None)) + assert "Category" not in [field.name for field in embed.fields] + + def test_includes_reward_when_present(self) -> None: + embed = build_achievement_embed(_achievement(reward_description="A shiny title.")) + field_names = {field.name: field.value for field in embed.fields} + assert field_names["Reward"] == "A shiny title." + + def test_omits_reward_when_absent(self) -> None: + embed = build_achievement_embed(_achievement(reward_description=None)) + assert "Reward" not in [field.name for field in embed.fields] + + def test_site_field_links_to_detail_page(self) -> None: + embed = build_achievement_embed(_achievement(achievement_id=7)) + field_names = {field.name: field.value for field in embed.fields} + assert "https://sidequest-guild.com/achievements/detail/?id=7" in field_names["Site"] + + +class TestMatchOption: + def test_label_value_and_description(self) -> None: + option = match_option(_summary(achievement_id=3, name="Explorer", points=15)) + assert option.label == "Explorer" + assert option.value == "3" + assert option.description == "15 pts" + + +class TestAchievementCache: + @staticmethod + def _api() -> AsyncMock: + api = AsyncMock() + api.list_achievement_categories.return_value = [ + AchievementCategoryTree(id=1, name="Root", children=[AchievementCategorySummary(id=2, name="Child")]) + ] + api.get_achievement_category.side_effect = lambda category_id: AchievementCategorySchema( + id=category_id, name=f"Category {category_id}", achievements=[_summary(achievement_id=category_id)] + ) + return api + + async def test_builds_from_category_tree(self) -> None: + api = self._api() + cache = _AchievementCache() + + achievements = await cache.get(api) + + api.list_achievement_categories.assert_awaited_once() + assert api.get_achievement_category.await_count == 2 + assert {a.id for a in achievements} == {1, 2} + + async def test_second_call_within_ttl_uses_cache(self) -> None: + api = self._api() + cache = _AchievementCache() + + await cache.get(api) + await cache.get(api) + + api.list_achievement_categories.assert_awaited_once() + + async def test_rebuilds_after_ttl_expires(self) -> None: + api = self._api() + cache = _AchievementCache() + + await cache.get(api) + cache._built_at -= CACHE_TTL + timedelta(seconds=1) + await cache.get(api) + + assert api.list_achievement_categories.await_count == 2 + + async def test_skips_category_battlenet_cannot_answer(self) -> None: + api = self._api() + + def side_effect(category_id: int) -> AchievementCategorySchema: + if category_id == 2: + raise APIError(503, "unavailable") + return AchievementCategorySchema(id=category_id, name="Root", achievements=[_summary(achievement_id=1)]) + + api.get_achievement_category.side_effect = side_effect + cache = _AchievementCache() + + achievements = await cache.get(api) + + assert {a.id for a in achievements} == {1} + + async def test_propagates_failure_listing_categories(self) -> None: + api = self._api() + api.list_achievement_categories.side_effect = APIError(503, "down") + cache = _AchievementCache() + + with pytest.raises(APIError): + await cache.get(api) + + +class TestAutocompleteAchievement: + async def test_filters_by_substring(self) -> None: + api = AsyncMock() + api.list_achievement_categories.return_value = [AchievementCategoryTree(id=1, name="Root", children=[])] + api.get_achievement_category.return_value = AchievementCategorySchema( + id=1, + name="Root", + achievements=[ + _summary(achievement_id=1, name="First Steps"), + _summary(achievement_id=2, name="Second Wind"), + ], + ) + interaction = _make_interaction(api=api) + + choices = await _autocomplete_achievement(interaction, "first") + + assert [choice.value for choice in choices] == ["1"] + + async def test_empty_current_returns_everything(self) -> None: + api = AsyncMock() + api.list_achievement_categories.return_value = [AchievementCategoryTree(id=1, name="Root", children=[])] + api.get_achievement_category.return_value = AchievementCategorySchema( + id=1, name="Root", achievements=[_summary(achievement_id=1)] + ) + interaction = _make_interaction(api=api) + + choices = await _autocomplete_achievement(interaction, "") + + assert len(choices) == 1 + + async def test_api_error_returns_empty(self) -> None: + api = AsyncMock() + api.list_achievement_categories.side_effect = APIError(503, "down") + interaction = _make_interaction(api=api) + + assert await _autocomplete_achievement(interaction, "first") == [] + + +class TestAchievementCommand: + async def test_digit_name_fetches_directly(self) -> None: + api = AsyncMock() + api.get_achievement.return_value = _achievement(achievement_id=42, name="Explorer") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await AchievementsCog.achievement_command.callback(cog, interaction, "42") + + api.get_achievement.assert_awaited_once_with(42) + kwargs = interaction.followup.send.await_args.kwargs + assert kwargs["embed"].title == "Explorer" + assert "ephemeral" not in kwargs + + async def test_digit_name_not_found(self) -> None: + api = AsyncMock() + api.get_achievement.side_effect = NotFoundError(404, "gone") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await AchievementsCog.achievement_command.callback(cog, interaction, "42") + + interaction.followup.send.assert_awaited_once_with("That achievement is gone.", ephemeral=True) + + async def test_digit_name_unavailable(self) -> None: + api = AsyncMock() + api.get_achievement.side_effect = APIError(503, "down") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await AchievementsCog.achievement_command.callback(cog, interaction, "42") + + interaction.followup.send.assert_awaited_once_with(UNAVAILABLE_MESSAGE, ephemeral=True) + + async def test_name_search_unavailable(self) -> None: + api = AsyncMock() + api.list_achievement_categories.side_effect = APIError(503, "down") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await AchievementsCog.achievement_command.callback(cog, interaction, "explorer") + + interaction.followup.send.assert_awaited_once_with(UNAVAILABLE_MESSAGE, ephemeral=True) + + async def test_name_search_generic_error(self) -> None: + api = AsyncMock() + api.list_achievement_categories.side_effect = APIError(500, "boom") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await AchievementsCog.achievement_command.callback(cog, interaction, "explorer") + + message = interaction.followup.send.await_args.args[0] + assert "try again shortly" in message + + async def test_no_matches_sends_hint(self) -> None: + api = AsyncMock() + api.list_achievement_categories.return_value = [] + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await AchievementsCog.achievement_command.callback(cog, interaction, "zzznotfound") + + message = interaction.followup.send.await_args.args[0] + assert NOT_FOUND_HINT in message + + async def test_single_match_sends_embed_without_select(self) -> None: + api = AsyncMock() + api.list_achievement_categories.return_value = [AchievementCategoryTree(id=1, name="Root", children=[])] + api.get_achievement_category.return_value = AchievementCategorySchema( + id=1, name="Root", achievements=[_summary(achievement_id=7, name="Explorer")] + ) + api.get_achievement.return_value = _achievement(achievement_id=7, name="Explorer") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await AchievementsCog.achievement_command.callback(cog, interaction, "explorer") + + kwargs = interaction.followup.send.await_args.kwargs + assert kwargs["embed"].title == "Explorer" + assert "view" not in kwargs + + async def test_multiple_matches_offers_select_of_others(self) -> None: + api = AsyncMock() + api.list_achievement_categories.return_value = [AchievementCategoryTree(id=1, name="Root", children=[])] + matches = [_summary(achievement_id=i, name=f"Explorer {i}") for i in range(1, 8)] + api.get_achievement_category.return_value = AchievementCategorySchema(id=1, name="Root", achievements=matches) + api.get_achievement.return_value = _achievement(achievement_id=1, name="Explorer 1") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await AchievementsCog.achievement_command.callback(cog, interaction, "explorer") + + kwargs = interaction.followup.send.await_args.kwargs + view = kwargs["view"] + assert isinstance(view, AchievementMatchView) + assert [option.value for option in view._select.options] == ["2", "3", "4", "5", "6"] + + async def test_achievement_gone_after_search_reports_gone(self) -> None: + api = AsyncMock() + api.list_achievement_categories.return_value = [AchievementCategoryTree(id=1, name="Root", children=[])] + api.get_achievement_category.return_value = AchievementCategorySchema( + id=1, name="Root", achievements=[_summary(achievement_id=1, name="Explorer")] + ) + api.get_achievement.side_effect = NotFoundError(404, "gone") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await AchievementsCog.achievement_command.callback(cog, interaction, "explorer") + + interaction.followup.send.assert_awaited_once_with("That achievement is gone.", ephemeral=True) + + +class TestAchievementMatchView: + def test_options_use_match_names_and_ids(self) -> None: + view = AchievementMatchView([_summary(achievement_id=1, name="A"), _summary(achievement_id=2, name="B")]) + assert [option.label for option in view._select.options] == ["A", "B"] + assert [option.value for option in view._select.options] == ["1", "2"] + + async def test_select_callback_edits_message_with_chosen_achievement(self) -> None: + api = AsyncMock() + api.get_achievement.return_value = _achievement(achievement_id=2, name="B") + view = AchievementMatchView([_summary(achievement_id=2, name="B")]) + view._select._values = ["2"] + interaction = _make_interaction(api=api) + + await view._select.callback(interaction) + + interaction.response.edit_message.assert_awaited_once() + kwargs = interaction.response.edit_message.await_args.kwargs + assert kwargs["embed"].title == "B" + assert kwargs["view"] is view + + async def test_select_callback_reports_error_ephemerally(self) -> None: + api = AsyncMock() + api.get_achievement.side_effect = NotFoundError(404, "gone") + view = AchievementMatchView([_summary(achievement_id=2)]) + view._select._values = ["2"] + interaction = _make_interaction(api=api) + + await view._select.callback(interaction) + + interaction.response.send_message.assert_awaited_once_with("That achievement is gone.", ephemeral=True) + interaction.response.edit_message.assert_not_awaited() From 9bc7d347888b285d6a4bbd8a7c99630dbeaf63d4 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Wed, 11 Nov 2026 12:26:04 -0600 Subject: [PATCH 2/3] feat: add /recipe to show a recipe's reagents, crafted item and guild crafters who know it --- src/sidequest_bot/api_client.py | 12 ++ src/sidequest_bot/plugins/recipes.py | 169 +++++++++++++++ tests/test_recipes.py | 312 +++++++++++++++++++++++++++ 3 files changed, 493 insertions(+) create mode 100644 src/sidequest_bot/plugins/recipes.py create mode 100644 tests/test_recipes.py diff --git a/src/sidequest_bot/api_client.py b/src/sidequest_bot/api_client.py index 4b7559d..557e098 100644 --- a/src/sidequest_bot/api_client.py +++ b/src/sidequest_bot/api_client.py @@ -60,6 +60,7 @@ PendingAnnouncement, PendingAnnouncementsPage, RankSchema, + RecipeDetail, Recruiting, RoleMenuCreate, RoleMenuOptionUpsert, @@ -1013,6 +1014,17 @@ async def get_achievement(self, achievement_id: int) -> AchievementSchema: data = await self._request("GET", f"/api/achievements/{achievement_id}") return _parse(AchievementSchema.model_validate, data) + # --- Recipes + + async def get_recipe(self, recipe_id: int) -> RecipeDetail: + """One recipe by its Battle.net game ID: what it makes, its reagents, and guild crafters. + + The public ``/api/recipes/{id}`` GET. Raises ``NotFoundError`` for an unknown recipe, or ``APIError`` + (status 503) if Battle.net isn't configured or didn't answer. + """ + data = await self._request("GET", f"/api/recipes/{recipe_id}") + return _parse(RecipeDetail.model_validate, data) + # --- Auctions async def get_item_price(self, item_id: int) -> ItemAuctionPrice: diff --git a/src/sidequest_bot/plugins/recipes.py b/src/sidequest_bot/plugins/recipes.py new file mode 100644 index 0000000..7105b2a --- /dev/null +++ b/src/sidequest_bot/plugins/recipes.py @@ -0,0 +1,169 @@ +"""Recipe lookup: ``/recipe `` shows a recipe's reagents, crafted item and the guild crafters who know it. + +Battle.net's recipe API has no name search, so this reuses the bot-key crafters route (``GET +/api/guilds/{id}/crafters``, same data as ``/crafter``) to find the matching recipe's Battle.net id, then fetches +its full detail. If Battle.net was unreachable when the guild's crafter data last synced, that id isn't known yet; +the command then falls back to the crafters-only view (profession, skill, and who knows it, no reagents or icon). +""" + +import logging +from http import HTTPStatus +from typing import TYPE_CHECKING + +import discord +from discord import app_commands +from discord.ext import commands + +from sidequest_bot.api_client import APIError, GuildCrafters, NotFoundError +from sidequest_bot.bot import SideQuestBot # noqa: TC001 # discord.py evaluates app-command annotations at runtime +from sidequest_bot.lib.embeds import Colors, make_embed, truncate +from sidequest_bot.plugins.crafters import character_label + +if TYPE_CHECKING: + from collections.abc import Sequence + + from sidequest_bot.api_client import SideQuestAPI + from sidequest_common.schemas import GuildCrafterResult, GuildCrafterRow, RecipeCrafter, RecipeDetail, RecipeReagent + +logger = logging.getLogger(__name__) + +MAX_REAGENTS_SHOWN = 10 +MAX_CRAFTERS_SHOWN = 10 +NOT_DEPLOYED_MESSAGE = "Recipe lookup isn't available yet; try again later." +NO_RESULTS_MESSAGE = "No recipes found matching that search." +UNAVAILABLE_MESSAGE = "Couldn't look up that recipe right now; try again shortly." +RECIPE_DETAIL_UNAVAILABLE_NOTE = ( + "Battle.net wasn't reachable when the guild's crafter data last synced, so this recipe's reagents and icon " + "aren't available yet; showing who in the guild knows it." +) + + +def reagent_line(reagent: RecipeReagent) -> str: + """One reagent line: ``Name x N``.""" + return f"{reagent.name} x{reagent.quantity}" + + +def build_reagents_field(reagents: Sequence[RecipeReagent]) -> str: + """Up to :data:`MAX_REAGENTS_SHOWN` reagents, one per line, or a placeholder if the recipe needs none.""" + if not reagents: + return "None" + return truncate("\n".join(reagent_line(reagent) for reagent in reagents[:MAX_REAGENTS_SHOWN])) + + +def crafted_item_value(recipe: RecipeDetail) -> str: + """What the recipe makes, with its crafted quantity text (e.g. "Makes 2-4") when Battle.net reports one.""" + if recipe.crafted_item is None: + return "—" + quantity = f" ({recipe.crafted_quantity})" if recipe.crafted_quantity else "" + return f"{recipe.crafted_item.name}{quantity}" + + +def recipe_crafter_line(row: RecipeCrafter) -> str: + """One crafter line: ``Name — skill N``.""" + return f"{character_label(row.character)} — skill {row.skill}" + + +def build_recipe_crafters_field(crafters: Sequence[RecipeCrafter]) -> str: + """Up to :data:`MAX_CRAFTERS_SHOWN` guild crafters who know the recipe, or a placeholder if none do.""" + if not crafters: + return "No guild crafters know this recipe yet." + return truncate("\n".join(recipe_crafter_line(row) for row in crafters[:MAX_CRAFTERS_SHOWN])) + + +def build_recipe_embed(recipe: RecipeDetail) -> discord.Embed: + """A recipe's full detail: profession, what it crafts, reagents, icon and guild crafters.""" + embed = make_embed( + title=recipe.name, + description=truncate(recipe.description) if recipe.description else None, + color=Colors.SITE_GOLD, + timestamp=False, + ) + if recipe.icon_url: + embed.set_thumbnail(url=recipe.icon_url) + if recipe.profession: + embed.add_field(name="Profession", value=recipe.profession) + embed.add_field(name="Crafts", value=crafted_item_value(recipe)) + embed.add_field(name="Reagents", value=build_reagents_field(recipe.reagents), inline=False) + embed.add_field(name="Guild crafters", value=build_recipe_crafters_field(recipe.crafters), inline=False) + return embed + + +def partial_crafter_line(row: GuildCrafterRow) -> str: + """One crafter line for the crafters-only fallback: ``Name — Profession Skill``.""" + return f"{character_label(row.character)} — {row.profession} {row.skill}" + + +def build_partial_recipe_embed(result: GuildCrafterResult) -> discord.Embed: + """A guild-crafters-only view for when Battle.net couldn't be asked for the recipe's own detail yet.""" + embed = make_embed( + title=result.recipe_name, description=RECIPE_DETAIL_UNAVAILABLE_NOTE, color=Colors.SITE_GOLD, timestamp=False + ) + shown = result.crafters[:MAX_CRAFTERS_SHOWN] + lines = [partial_crafter_line(row) for row in shown] + embed.add_field(name="Guild crafters", value=truncate("\n".join(lines)) if lines else "None", inline=False) + return embed + + +async def _search_recipe(api: SideQuestAPI, guild_id: int, name: str) -> GuildCrafters | str: + """Matching recipes via the crafters route (reusing ``/crafter``'s data), or a plain-text error.""" + try: + return await api.get_crafters(guild_id, q=name) + except NotFoundError: + return NOT_DEPLOYED_MESSAGE + except APIError as exc: + if exc.status_code == HTTPStatus.SERVICE_UNAVAILABLE: + return UNAVAILABLE_MESSAGE + logger.warning("Recipe search failed for %r", name, exc_info=True) + return "Couldn't search recipes right now; try again shortly." + + +async def _fetch_recipe_embed(api: SideQuestAPI, recipe_id: int) -> discord.Embed | str | None: + """The recipe's embed, a plain-text error, or ``None`` to fall back to the crafters-only view.""" + try: + recipe = await api.get_recipe(recipe_id) + except NotFoundError: + return None + except APIError as exc: + if exc.status_code == HTTPStatus.SERVICE_UNAVAILABLE: + return UNAVAILABLE_MESSAGE + logger.warning("Recipe detail fetch failed for %s", recipe_id, exc_info=True) + return UNAVAILABLE_MESSAGE + return build_recipe_embed(recipe) + + +class RecipesCog(commands.Cog): + """``/recipe`` lookup.""" + + def __init__(self, bot: SideQuestBot) -> None: + self.bot = bot + + @app_commands.command(name="recipe", description="Look up a WoW: Forever recipe and who in the guild can craft it.") + @app_commands.describe(name="Recipe or item name to search for") + @app_commands.guild_only() + async def recipe_command(self, interaction: discord.Interaction[SideQuestBot], name: str) -> None: + """Find the recipe matching ``name`` (via the crafters route) and show its reagents and guild crafters.""" + if interaction.guild_id is None: + return + await interaction.response.defer() + crafters = await _search_recipe(self.bot.api, interaction.guild_id, name) + if isinstance(crafters, str): + await interaction.followup.send(crafters, ephemeral=True) + return + if not crafters.results: + await interaction.followup.send(NO_RESULTS_MESSAGE, ephemeral=True) + return + best = crafters.results[0] + if best.battlenet_recipe_id is not None: + result = await _fetch_recipe_embed(self.bot.api, best.battlenet_recipe_id) + if isinstance(result, discord.Embed): + await interaction.followup.send(embed=result) + return + if isinstance(result, str): + await interaction.followup.send(result, ephemeral=True) + return + await interaction.followup.send(embed=build_partial_recipe_embed(best)) + + +async def setup(bot: SideQuestBot) -> None: + """Register the cog.""" + await bot.add_cog(RecipesCog(bot)) diff --git a/tests/test_recipes.py b/tests/test_recipes.py new file mode 100644 index 0000000..d788dfb --- /dev/null +++ b/tests/test_recipes.py @@ -0,0 +1,312 @@ +"""Unit tests for the recipes plugin: formatting helpers, embed builders and ``/recipe``.""" + +from types import SimpleNamespace +from unittest.mock import AsyncMock, Mock + +import discord + +from sidequest_bot.api_client import APIError, GuildCrafters, NotFoundError +from sidequest_bot.plugins.recipes import ( + NO_RESULTS_MESSAGE, + NOT_DEPLOYED_MESSAGE, + UNAVAILABLE_MESSAGE, + RecipesCog, + build_partial_recipe_embed, + build_reagents_field, + build_recipe_crafters_field, + build_recipe_embed, + crafted_item_value, + partial_crafter_line, + reagent_line, + recipe_crafter_line, +) +from sidequest_common.schemas import ( + GuildCrafterProfessionCount, + GuildCrafterResult, + GuildCrafterRow, + RecipeCraftedItem, + RecipeCrafter, + RecipeDetail, + RecipeReagent, +) + +_UNSET = object() + + +def _reagent(*, item_id: int = 100, name: str = "Linen Cloth", quantity: int = 2) -> RecipeReagent: + return RecipeReagent(item_id=item_id, name=name, quantity=quantity, quality=None) + + +def _crafted_item(*, item_id: int = 200, name: str = "Linen Bandage", quality: str | None = None) -> RecipeCraftedItem: + return RecipeCraftedItem(item_id=item_id, name=name, quality=quality) + + +def _recipe_crafter( + *, character: str = "nox-zul", member_id: int | None = 1, member_name: str | None = "Nox", skill: int = 150 +) -> RecipeCrafter: + return RecipeCrafter(character=character, member_id=member_id, member_name=member_name, skill=skill) + + +def _recipe( + *, + recipe_id: int = 1, + name: str = "First Aid: Linen Bandage", + description: str | None = "Binds a wound.", + rank: int | None = 1, + profession: str | None = "First Aid", + icon_url: str | None = "https://render.worldofwarcraft.com/icons/56/inv_misc_bandage.jpg", + crafted_item: object = _UNSET, + crafted_quantity: str | None = None, + reagents: list[RecipeReagent] | None = None, + crafters: list[RecipeCrafter] | None = None, +) -> RecipeDetail: + return RecipeDetail( + recipe_id=recipe_id, + name=name, + description=description, + rank=rank, + profession=profession, + icon_url=icon_url, + crafted_item=_crafted_item() if crafted_item is _UNSET else crafted_item, + crafted_quantity=crafted_quantity, + reagents=reagents if reagents is not None else [_reagent()], + crafters=crafters if crafters is not None else [_recipe_crafter()], + ) + + +def _row( + *, + character: str = "nox-zul", + member_id: int | None = 1, + member_name: str | None = "Nox", + profession: str = "First Aid", + skill: int = 150, +) -> GuildCrafterRow: + return GuildCrafterRow( + character=character, member_id=member_id, member_name=member_name, profession=profession, skill=skill + ) + + +def _result( + *, + recipe_id: int = 1, + recipe_name: str = "First Aid: Linen Bandage", + item_id: int | None = 200, + battlenet_recipe_id: int | None = 55, + crafters: list[GuildCrafterRow] | None = None, +) -> GuildCrafterResult: + return GuildCrafterResult( + recipe_id=recipe_id, + recipe_name=recipe_name, + item_id=item_id, + battlenet_recipe_id=battlenet_recipe_id, + crafters=crafters if crafters is not None else [_row()], + ) + + +def _crafters( + *, results: list[GuildCrafterResult] | None = None, professions: list[GuildCrafterProfessionCount] | None = None +) -> GuildCrafters: + return GuildCrafters( + results=results if results is not None else [_result()], + professions=professions + if professions is not None + else [GuildCrafterProfessionCount(profession="First Aid", crafters=1)], + ) + + +def _make_cog(*, api: object | None = None) -> RecipesCog: + cog = RecipesCog.__new__(RecipesCog) + cog.bot = SimpleNamespace(api=api or AsyncMock()) + return cog + + +def _make_interaction(*, api: object | None = None, guild_id: int | None = 1) -> Mock: + interaction = Mock(spec=discord.Interaction) + interaction.guild_id = guild_id + interaction.response = Mock() + interaction.response.defer = AsyncMock() + interaction.followup = Mock() + interaction.followup.send = AsyncMock() + interaction.client = SimpleNamespace(api=api or AsyncMock()) + return interaction + + +class TestReagentLine: + def test_formats_name_and_quantity(self) -> None: + assert reagent_line(_reagent(name="Linen Cloth", quantity=2)) == "Linen Cloth x2" + + +class TestBuildReagentsField: + def test_none_returns_placeholder(self) -> None: + assert build_reagents_field([]) == "None" + + def test_caps_at_ten(self) -> None: + reagents = [_reagent(item_id=i, name=f"Reagent{i}") for i in range(12)] + field = build_reagents_field(reagents) + assert len(field.splitlines()) == 10 + + +class TestCraftedItemValue: + def test_no_crafted_item_shows_dash(self) -> None: + assert crafted_item_value(_recipe(crafted_item=None)) == "—" + + def test_includes_crafted_quantity_text(self) -> None: + recipe = _recipe(crafted_item=_crafted_item(name="Linen Bandage"), crafted_quantity="Makes 2-4") + assert crafted_item_value(recipe) == "Linen Bandage (Makes 2-4)" + + def test_no_quantity_text(self) -> None: + recipe = _recipe(crafted_item=_crafted_item(name="Linen Bandage"), crafted_quantity=None) + assert crafted_item_value(recipe) == "Linen Bandage" + + +class TestRecipeCrafterLine: + def test_formats_name_and_skill(self) -> None: + assert recipe_crafter_line(_recipe_crafter(character="nox-zul", skill=150)) == "Nox Zul — skill 150" + + +class TestBuildRecipeCraftersField: + def test_no_crafters_shows_placeholder(self) -> None: + assert build_recipe_crafters_field([]) == "No guild crafters know this recipe yet." + + def test_caps_at_ten(self) -> None: + crafters = [_recipe_crafter(character=f"char{i}-name", skill=i) for i in range(12)] + field = build_recipe_crafters_field(crafters) + assert len(field.splitlines()) == 10 + + +class TestBuildRecipeEmbed: + def test_sets_title_and_thumbnail(self) -> None: + embed = build_recipe_embed(_recipe(name="First Aid: Linen Bandage")) + assert embed.title == "First Aid: Linen Bandage" + assert embed.thumbnail.url == "https://render.worldofwarcraft.com/icons/56/inv_misc_bandage.jpg" + + def test_includes_profession_crafts_reagents_and_crafters(self) -> None: + embed = build_recipe_embed(_recipe()) + field_names = {field.name: field.value for field in embed.fields} + assert field_names["Profession"] == "First Aid" + assert "Linen Bandage" in field_names["Crafts"] + assert "Linen Cloth x2" in field_names["Reagents"] + assert "Nox Zul" in field_names["Guild crafters"] + + def test_omits_profession_when_unknown(self) -> None: + embed = build_recipe_embed(_recipe(profession=None)) + assert "Profession" not in [field.name for field in embed.fields] + + +class TestPartialCrafterLine: + def test_formats_name_profession_and_skill(self) -> None: + assert partial_crafter_line(_row()) == "Nox Zul — First Aid 150" + + +class TestBuildPartialRecipeEmbed: + def test_includes_note_and_crafters(self) -> None: + embed = build_partial_recipe_embed(_result(recipe_name="First Aid: Linen Bandage")) + assert embed.title == "First Aid: Linen Bandage" + assert "wasn't reachable" in (embed.description or "") + assert "Nox Zul" in embed.fields[0].value + + def test_no_crafters_shows_none(self) -> None: + embed = build_partial_recipe_embed(_result(crafters=[])) + assert embed.fields[0].value == "None" + + +class TestRecipeCommand: + async def test_no_guild_does_nothing(self) -> None: + cog = _make_cog() + interaction = _make_interaction(guild_id=None) + + await RecipesCog.recipe_command.callback(cog, interaction, "bandage") + + interaction.response.defer.assert_not_awaited() + + async def test_not_deployed_reports_clear_message(self) -> None: + api = AsyncMock() + api.get_crafters.side_effect = NotFoundError(404, "not found") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await RecipesCog.recipe_command.callback(cog, interaction, "bandage") + + interaction.followup.send.assert_awaited_once_with(NOT_DEPLOYED_MESSAGE, ephemeral=True) + + async def test_search_unavailable_reports_clear_message(self) -> None: + api = AsyncMock() + api.get_crafters.side_effect = APIError(503, "Battle.net unavailable") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await RecipesCog.recipe_command.callback(cog, interaction, "bandage") + + interaction.followup.send.assert_awaited_once_with(UNAVAILABLE_MESSAGE, ephemeral=True) + + async def test_search_generic_error_reports_try_again(self) -> None: + api = AsyncMock() + api.get_crafters.side_effect = APIError(500, "boom") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await RecipesCog.recipe_command.callback(cog, interaction, "bandage") + + message = interaction.followup.send.await_args.args[0] + assert "try again shortly" in message + + async def test_no_results_reports_clear_message(self) -> None: + api = AsyncMock() + api.get_crafters.return_value = _crafters(results=[]) + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await RecipesCog.recipe_command.callback(cog, interaction, "nothing") + + interaction.followup.send.assert_awaited_once_with(NO_RESULTS_MESSAGE, ephemeral=True) + + async def test_no_battlenet_id_sends_partial_embed(self) -> None: + api = AsyncMock() + api.get_crafters.return_value = _crafters(results=[_result(battlenet_recipe_id=None)]) + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await RecipesCog.recipe_command.callback(cog, interaction, "bandage") + + api.get_recipe.assert_not_awaited() + kwargs = interaction.followup.send.await_args.kwargs + assert "wasn't reachable" in (kwargs["embed"].description or "") + + async def test_success_sends_full_embed(self) -> None: + api = AsyncMock() + api.get_crafters.return_value = _crafters(results=[_result(battlenet_recipe_id=55)]) + api.get_recipe.return_value = _recipe(name="First Aid: Linen Bandage") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await RecipesCog.recipe_command.callback(cog, interaction, "bandage") + + api.get_recipe.assert_awaited_once_with(55) + kwargs = interaction.followup.send.await_args.kwargs + assert kwargs["embed"].title == "First Aid: Linen Bandage" + assert "ephemeral" not in kwargs + + async def test_recipe_detail_not_found_falls_back_to_partial(self) -> None: + api = AsyncMock() + api.get_crafters.return_value = _crafters(results=[_result(battlenet_recipe_id=55, recipe_name="Bandage")]) + api.get_recipe.side_effect = NotFoundError(404, "gone") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await RecipesCog.recipe_command.callback(cog, interaction, "bandage") + + kwargs = interaction.followup.send.await_args.kwargs + assert kwargs["embed"].title == "Bandage" + assert "wasn't reachable" in (kwargs["embed"].description or "") + + async def test_recipe_detail_unavailable_reports_clear_message(self) -> None: + api = AsyncMock() + api.get_crafters.return_value = _crafters(results=[_result(battlenet_recipe_id=55)]) + api.get_recipe.side_effect = APIError(503, "Battle.net unavailable") + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await RecipesCog.recipe_command.callback(cog, interaction, "bandage") + + interaction.followup.send.assert_awaited_once_with(UNAVAILABLE_MESSAGE, ephemeral=True) From 9fec83333757f746366bd112695b4d2362a6ffb9 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Wed, 11 Nov 2026 12:26:09 -0600 Subject: [PATCH 3/3] feat: add /compare to compare two characters' gear and stats side by side --- README.md | 5 + src/sidequest_bot/plugins/compare.py | 152 ++++++++++++++++++ tests/test_compare.py | 225 +++++++++++++++++++++++++++ 3 files changed, 382 insertions(+) create mode 100644 src/sidequest_bot/plugins/compare.py create mode 100644 tests/test_compare.py diff --git a/README.md b/README.md index 017b44f..437652d 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,11 @@ lives there. - **Crafters.** `/crafter [profession]` finds guild characters who know a recipe matching `query`, with their profession, skill and the matching recipes, including characters synced from Battle.net who never ran the addon; `profession` autocompletes from the guild's known professions. +- **Achievements and recipes.** `/achievement ` looks up a WoW: Forever achievement and shows its points, + description and category, with autocomplete over the full catalog. `/recipe ` looks up a recipe (reusing + `/crafter`'s search) and shows its reagents, crafted item and the guild crafters who know it. `/compare + ` is `/who` for two characters side by side: level, class, item level with the lead + highlighted, PvP stats, and a per-slot gear comparison table; autocompletes the same way `/who` does. - **Auction prices.** `/price ` shows an item's lowest current auction price, where it's cheapest, how many are listed, and its 14-day price range. `/watch ` (e.g. `1g20s`, `35s`, `80c`) DMs you when that item's price drops to or below your target; `/unwatch ` removes a watch and `/watches` lists yours. Watches diff --git a/src/sidequest_bot/plugins/compare.py b/src/sidequest_bot/plugins/compare.py new file mode 100644 index 0000000..f4f0f50 --- /dev/null +++ b/src/sidequest_bot/plugins/compare.py @@ -0,0 +1,152 @@ +"""Character comparison: ``/compare `` is ``/who`` for two characters side by side. + +Reuses ``/who``'s slug parsing, autocomplete and ``get_character`` lookup (run concurrently for both characters), so +the same roster/Battle.net rules and error handling apply to each side. +""" + +import asyncio +import logging +from http import HTTPStatus +from typing import TYPE_CHECKING + +import discord +from discord import app_commands +from discord.ext import commands + +from sidequest_bot.api_client import APIError, CharacterPage, NotFoundError +from sidequest_bot.bot import SideQuestBot # noqa: TC001 # discord.py evaluates app-command annotations at runtime +from sidequest_bot.lib.embeds import Colors, make_embed, truncate +from sidequest_bot.plugins.characters import ( + NAME_HINT, + _autocomplete_character, + build_description, + pvp_value, + resolve_slug, +) + +if TYPE_CHECKING: + from sidequest_bot.api_client import SideQuestAPI + +logger = logging.getLogger(__name__) + +UNAVAILABLE_MESSAGE = "Battle.net did not answer; try again in a minute." +GEAR_SLOT_NAME_WIDTH = 13 +GEAR_COLUMN_WIDTH = 7 + + +async def _fetch_character(api: SideQuestAPI, slug: str) -> CharacterPage | str: + """``slug``'s character page, or a plain-text error if the lookup failed.""" + try: + return await api.get_character(slug) + except NotFoundError as exc: + return exc.detail + except APIError as exc: + if exc.status_code == HTTPStatus.SERVICE_UNAVAILABLE: + return UNAVAILABLE_MESSAGE + logger.warning("Character lookup failed for %r", slug, exc_info=True) + return "Couldn't compare those characters right now; try again shortly." + + +def item_level_value(a: CharacterPage, b: CharacterPage) -> str: + """Both characters' item level, with the higher side's lead highlighted (e.g. "70 vs 65 (Nox +5)").""" + a_text = str(a.item_level) if a.item_level is not None else "—" + b_text = str(b.item_level) if b.item_level is not None else "—" + if a.item_level is None or b.item_level is None: + return f"{a_text} vs {b_text}" + diff = a.item_level - b.item_level + if diff == 0: + return f"{a_text} vs {b_text} (tied)" + leader = a.name if diff > 0 else b.name + return f"{a_text} vs {b_text} ({leader} +{abs(diff)})" + + +def character_field_value(character: CharacterPage) -> str: + """A character's one-line summary plus its PvP line, for its own side of the embed.""" + return f"{build_description(character)}\n{pvp_value(character)}" + + +def gear_by_slot(character: CharacterPage) -> dict[str, int | None]: + """``slot name -> item level`` for every equipped item Battle.net reported, empty if there's no profile yet.""" + if character.sheet is None: + return {} + return {item.slot_name: item.item_level for item in character.sheet.gear} + + +def gear_diff_text(a_ilvl: int | None, b_ilvl: int | None) -> str: + """One slot's item level difference, right-aligned: ``+5``, ``-5``, or ``—`` when either side is unknown.""" + if a_ilvl is None or b_ilvl is None: + return "—" + diff = a_ilvl - b_ilvl + if diff == 0: + return "0" + return f"{diff:+d}" + + +def build_gear_table(a: CharacterPage, b: CharacterPage) -> str: + """A compact ``Slot | A | B | Diff`` table of every slot either character has gear in, as a code block body.""" + a_gear, b_gear = gear_by_slot(a), gear_by_slot(b) + slots = sorted(set(a_gear) | set(b_gear)) + if not slots: + return "No gear data for either character yet." + header = ( + f"{'Slot':<{GEAR_SLOT_NAME_WIDTH}}{truncate(a.name, GEAR_COLUMN_WIDTH - 1):>{GEAR_COLUMN_WIDTH}}" + f"{truncate(b.name, GEAR_COLUMN_WIDTH - 1):>{GEAR_COLUMN_WIDTH}}{'Diff':>{GEAR_COLUMN_WIDTH}}" + ) + rows = [header, "-" * len(header)] + for slot in slots: + a_ilvl, b_ilvl = a_gear.get(slot), b_gear.get(slot) + a_text = str(a_ilvl) if a_ilvl is not None else "—" + b_text = str(b_ilvl) if b_ilvl is not None else "—" + rows.append( + f"{slot:<{GEAR_SLOT_NAME_WIDTH}}{a_text:>{GEAR_COLUMN_WIDTH}}{b_text:>{GEAR_COLUMN_WIDTH}}" + f"{gear_diff_text(a_ilvl, b_ilvl):>{GEAR_COLUMN_WIDTH}}" + ) + return truncate("\n".join(rows), 1000) + + +def build_compare_embed(a: CharacterPage, b: CharacterPage) -> discord.Embed: + """``/compare``'s embed: level/class/PvP side by side, item level with the lead highlighted, and a gear table.""" + embed = make_embed(title=f"{a.name} {a.surname} vs {b.name} {b.surname}", color=Colors.SITE_GOLD) + embed.add_field(name=f"{a.name} {a.surname}", value=character_field_value(a), inline=True) + embed.add_field(name=f"{b.name} {b.surname}", value=character_field_value(b), inline=True) + embed.add_field(name="Item level", value=item_level_value(a, b), inline=False) + embed.add_field(name="Gear by slot", value=f"```\n{build_gear_table(a, b)}\n```", inline=False) + return embed + + +class CompareCog(commands.Cog): + """``/compare`` character comparison.""" + + def __init__(self, bot: SideQuestBot) -> None: + self.bot = bot + + @app_commands.command(name="compare", description="Compare two WoW: Forever characters' gear and stats.") + @app_commands.describe( + character1="First character, name and surname", character2="Second character, name and surname" + ) + @app_commands.autocomplete(character1=_autocomplete_character, character2=_autocomplete_character) + async def compare_command( + self, interaction: discord.Interaction[SideQuestBot], character1: str, character2: str + ) -> None: + """Look up both characters concurrently and show them side by side.""" + slug1 = resolve_slug(character1) + slug2 = resolve_slug(character2) + if slug1 is None or slug2 is None: + await interaction.response.send_message(NAME_HINT, ephemeral=True) + return + await interaction.response.defer() + first, second = await asyncio.gather( + _fetch_character(self.bot.api, slug1), _fetch_character(self.bot.api, slug2) + ) + if isinstance(first, str): + await interaction.followup.send(first, ephemeral=True) + return + if isinstance(second, str): + await interaction.followup.send(second, ephemeral=True) + return + await interaction.followup.send(embed=build_compare_embed(first, second)) + + +async def setup(bot: SideQuestBot) -> None: + """Register the cog.""" + await bot.add_cog(CompareCog(bot)) diff --git a/tests/test_compare.py b/tests/test_compare.py new file mode 100644 index 0000000..99ecc43 --- /dev/null +++ b/tests/test_compare.py @@ -0,0 +1,225 @@ +"""Unit tests for the compare plugin: formatting helpers, the gear table, embed builder and ``/compare``.""" + +from types import SimpleNamespace +from unittest.mock import AsyncMock, Mock + +import discord + +from sidequest_bot.api_client import APIError, CharacterGearItem, CharacterPage, CharacterSheet, NotFoundError +from sidequest_bot.plugins.characters import NAME_HINT +from sidequest_bot.plugins.compare import ( + UNAVAILABLE_MESSAGE, + CompareCog, + build_compare_embed, + build_gear_table, + character_field_value, + gear_by_slot, + gear_diff_text, + item_level_value, +) + + +def _page(**overrides: object) -> CharacterPage: + base: dict[str, object] = { + "slug": "nox-zul", + "name": "Nox", + "surname": "Zul", + "level": 60, + "class": "mage", + "race": "Gnome", + "faction": "Alliance", + "guild_name": "SideQuest", + "guild_slug": "sidequest", + "in_roster": True, + "guild_rank": 0, + "rank_name": "Guild Master", + "item_level": 70, + "spec": "Frost", + "achievement_points": 500, + "honorable_kills": 10, + "pvp_rank": 3, + "last_login_at": None, + "profile_found": True, + "fetched_at": None, + "sheet": None, + } + base.update(overrides) + return CharacterPage.model_validate(base) + + +def _gear(*, slot_name: str = "Head", name: str = "Lionheart Helm", item_level: int | None = 65) -> CharacterGearItem: + return CharacterGearItem(slot_name=slot_name, name=name, item_level=item_level) + + +def _make_cog(*, api: object | None = None) -> CompareCog: + cog = CompareCog.__new__(CompareCog) + cog.bot = SimpleNamespace(api=api or AsyncMock()) + return cog + + +def _make_interaction(*, api: object | None = None) -> Mock: + interaction = Mock(spec=discord.Interaction) + interaction.response = Mock() + interaction.response.defer = AsyncMock() + interaction.response.send_message = AsyncMock() + interaction.followup = Mock() + interaction.followup.send = AsyncMock() + interaction.client = SimpleNamespace(api=api or AsyncMock()) + return interaction + + +class TestItemLevelValue: + def test_both_known_highlights_leader(self) -> None: + a = _page(name="Nox", item_level=70) + b = _page(name="Vex", item_level=65) + assert item_level_value(a, b) == "70 vs 65 (Nox +5)" + + def test_second_leads(self) -> None: + a = _page(name="Nox", item_level=60) + b = _page(name="Vex", item_level=65) + assert item_level_value(a, b) == "60 vs 65 (Vex +5)" + + def test_tied(self) -> None: + a = _page(item_level=70) + b = _page(item_level=70) + assert item_level_value(a, b) == "70 vs 70 (tied)" + + def test_missing_side_shows_dash(self) -> None: + a = _page(item_level=None) + b = _page(item_level=65) + assert item_level_value(a, b) == "— vs 65" + + +class TestCharacterFieldValue: + def test_combines_description_and_pvp(self) -> None: + value = character_field_value(_page()) + assert "Level 60 Gnome Mage · Frost" in value + assert "10 honorable kills · PvP rank 3" in value + + +class TestGearBySlot: + def test_no_sheet_returns_empty(self) -> None: + assert gear_by_slot(_page(sheet=None)) == {} + + def test_sheet_gear_maps_slot_to_item_level(self) -> None: + page = _page(sheet=CharacterSheet(gear=[_gear(slot_name="Head", item_level=65)])) + assert gear_by_slot(page) == {"Head": 65} + + +class TestGearDiffText: + def test_positive_diff(self) -> None: + assert gear_diff_text(70, 65) == "+5" + + def test_negative_diff(self) -> None: + assert gear_diff_text(60, 65) == "-5" + + def test_zero_diff(self) -> None: + assert gear_diff_text(65, 65) == "0" + + def test_missing_side_shows_dash(self) -> None: + assert gear_diff_text(None, 65) == "—" + assert gear_diff_text(65, None) == "—" + + +class TestBuildGearTable: + def test_no_gear_shows_placeholder(self) -> None: + table = build_gear_table(_page(sheet=None), _page(sheet=None)) + assert table == "No gear data for either character yet." + + def test_includes_every_slot_from_both_sides(self) -> None: + a = _page(sheet=CharacterSheet(gear=[_gear(slot_name="Head", item_level=65)])) + b = _page(sheet=CharacterSheet(gear=[_gear(slot_name="Chest", item_level=60)])) + table = build_gear_table(a, b) + assert "Head" in table + assert "Chest" in table + + def test_missing_side_shows_dash_for_that_slot(self) -> None: + a = _page(sheet=CharacterSheet(gear=[_gear(slot_name="Head", item_level=65)])) + b = _page(sheet=CharacterSheet(gear=[])) + table = build_gear_table(a, b) + head_line = next(line for line in table.splitlines() if line.startswith("Head")) + assert "—" in head_line + + +class TestBuildCompareEmbed: + def test_title_and_fields(self) -> None: + a = _page(name="Nox", surname="Zul") + b = _page(name="Vex", surname="Shade") + embed = build_compare_embed(a, b) + assert embed.title == "Nox Zul vs Vex Shade" + field_names = [field.name for field in embed.fields] + assert "Nox Zul" in field_names + assert "Vex Shade" in field_names + assert "Item level" in field_names + assert "Gear by slot" in field_names + + def test_gear_field_is_a_code_block(self) -> None: + embed = build_compare_embed(_page(), _page()) + gear_field = next(field for field in embed.fields if field.name == "Gear by slot") + assert gear_field.value is not None + assert gear_field.value.startswith("```") + assert gear_field.value.endswith("```") + + +class TestCompareCommand: + async def test_invalid_first_character_sends_hint(self) -> None: + cog = _make_cog() + interaction = _make_interaction() + + await CompareCog.compare_command.callback(cog, interaction, "NoxZul", "Vex Shade") + + interaction.response.send_message.assert_awaited_once_with(NAME_HINT, ephemeral=True) + + async def test_invalid_second_character_sends_hint(self) -> None: + cog = _make_cog() + interaction = _make_interaction() + + await CompareCog.compare_command.callback(cog, interaction, "Nox Zul", "VexShade") + + interaction.response.send_message.assert_awaited_once_with(NAME_HINT, ephemeral=True) + + async def test_success_sends_embed_with_both_characters(self) -> None: + api = AsyncMock() + api.get_character.side_effect = lambda slug: _page( + name="Nox" if slug == "nox-zul" else "Vex", surname="Zul" if slug == "nox-zul" else "Shade", slug=slug + ) + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await CompareCog.compare_command.callback(cog, interaction, "Nox Zul", "Vex Shade") + + assert {call.args[0] for call in api.get_character.await_args_list} == {"nox-zul", "vex-shade"} + kwargs = interaction.followup.send.await_args.kwargs + assert kwargs["embed"].title == "Nox Zul vs Vex Shade" + + async def test_first_not_found_reports_api_detail(self) -> None: + api = AsyncMock() + + async def side_effect(slug: str) -> CharacterPage: + if slug == "nox-zul": + raise NotFoundError(404, "Battle.net has no character nox-zul.") + return _page(slug=slug) + + api.get_character.side_effect = side_effect + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await CompareCog.compare_command.callback(cog, interaction, "Nox Zul", "Vex Shade") + + interaction.followup.send.assert_awaited_once_with("Battle.net has no character nox-zul.", ephemeral=True) + + async def test_second_unavailable_reports_clear_message(self) -> None: + api = AsyncMock() + + async def side_effect(slug: str) -> CharacterPage: + if slug == "vex-shade": + raise APIError(503, "Battle.net unavailable") + return _page(slug=slug) + + api.get_character.side_effect = side_effect + cog = _make_cog(api=api) + interaction = _make_interaction(api=api) + + await CompareCog.compare_command.callback(cog, interaction, "Nox Zul", "Vex Shade") + + interaction.followup.send.assert_awaited_once_with(UNAVAILABLE_MESSAGE, ephemeral=True)