"""
Unit tests for standalone rules access and rules version selection (Issue #169).
Tests cover:
- Global RulebookManager initialization
- Rules queries without a campaign loaded (fallback to global manager)
- Fallback chain: campaign manager takes priority over global
- rules_version parameter in create_campaign
- rules_version persistence and loading
- Source attribution in rule query responses
These tests use mocked rulebook sources to avoid network dependencies.
"""
import asyncio
import json
import pytest
from pathlib import Path
from unittest.mock import AsyncMock, MagicMock, patch, PropertyMock
from datetime import datetime
from dm20_protocol.storage import DnDStorage
from dm20_protocol.rulebooks import RulebookManager
from dm20_protocol.rulebooks.sources.base import (
RulebookSourceBase,
RulebookSourceType,
SearchResult,
ContentCounts,
)
from dm20_protocol.rulebooks.models import (
ClassDefinition,
RaceDefinition,
SpellDefinition,
MonsterDefinition,
ArmorClassInfo,
SpellSchool,
Size,
)
def run_async(coro):
"""Helper to run async code in sync tests."""
loop = asyncio.new_event_loop()
try:
return loop.run_until_complete(coro)
finally:
loop.close()
# ---------------------------------------------------------------------------
# Mock Source Fixtures
# ---------------------------------------------------------------------------
class MockRulebookSource(RulebookSourceBase):
"""A mock rulebook source for testing without network dependencies."""
def __init__(self, source_id: str = "mock-source", name: str = "Mock Source"):
super().__init__(
source_id=source_id,
source_type=RulebookSourceType.SRD,
name=name,
)
self._classes = {}
self._races = {}
self._spells = {}
self._monsters = {}
self._loaded = False
self.loaded_at = None
async def load(self) -> None:
self._loaded = True
self.loaded_at = datetime.now()
async def close(self) -> None:
pass
def get_class(self, index: str):
return self._classes.get(index)
def get_race(self, index: str):
return self._races.get(index)
def get_spell(self, index: str):
return self._spells.get(index)
def get_monster(self, index: str):
return self._monsters.get(index)
def get_subclass(self, index: str):
return None
def get_subrace(self, index: str):
return None
def get_feat(self, index: str):
return None
def get_background(self, index: str):
return None
def get_item(self, index: str):
return None
def search(self, query: str, categories=None, limit: int = 20, class_filter=None):
results = []
for idx, cls in self._classes.items():
if query.lower() in cls.name.lower():
results.append(SearchResult(
name=cls.name, index=idx, category="class", source=self.name
))
for idx, spell in self._spells.items():
if query.lower() in spell.name.lower():
results.append(SearchResult(
name=spell.name, index=idx, category="spell", source=self.name
))
for idx, monster in self._monsters.items():
if query.lower() in monster.name.lower():
results.append(SearchResult(
name=monster.name, index=idx, category="monster", source=self.name
))
return results[:limit]
def content_counts(self):
return ContentCounts(
classes=len(self._classes),
races=len(self._races),
spells=len(self._spells),
monsters=len(self._monsters),
)
def _make_mock_class(name: str = "Fighter", source: str = "Mock Source") -> ClassDefinition:
"""Create a minimal ClassDefinition for testing."""
return ClassDefinition(
index=name.lower(),
name=name,
hit_die=10,
proficiency_choices={},
proficiencies=[],
saving_throws=["str", "con"],
source=source,
)
def _make_mock_spell(name: str = "Fireball", source: str = "Mock Source") -> SpellDefinition:
"""Create a minimal SpellDefinition for testing."""
return SpellDefinition(
index=name.lower().replace(" ", "-"),
name=name,
level=3,
school=SpellSchool.EVOCATION,
casting_time="1 action",
range="150 feet",
components=["V", "S", "M"],
duration="Instantaneous",
desc=["A bright streak flashes from your pointing finger."],
source=source,
)
def _make_mock_race(name: str = "Elf", source: str = "Mock Source") -> RaceDefinition:
"""Create a minimal RaceDefinition for testing."""
return RaceDefinition(
index=name.lower(),
name=name,
speed=30,
size=Size.MEDIUM,
source=source,
)
def _make_mock_monster(name: str = "Goblin", source: str = "Mock Source") -> MonsterDefinition:
"""Create a minimal MonsterDefinition for testing."""
return MonsterDefinition(
index=name.lower().replace(" ", "-"),
name=name,
size=Size.SMALL,
type="humanoid",
alignment="neutral evil",
armor_class=[ArmorClassInfo(type="natural", value=15)],
hit_points=7,
hit_dice="2d6",
speed={"walk": "30 ft."},
strength=8,
dexterity=14,
constitution=10,
intelligence=10,
wisdom=8,
charisma=8,
challenge_rating=0.25,
xp=50,
source=source,
)
@pytest.fixture
def temp_storage_dir(tmp_path: Path) -> Path:
"""Create a temporary storage directory for tests."""
storage_dir = tmp_path / "test_storage"
storage_dir.mkdir()
return storage_dir
@pytest.fixture
def mock_source() -> MockRulebookSource:
"""Create a mock rulebook source with sample data."""
source = MockRulebookSource(source_id="mock-5etools", name="5etools")
source._classes["fighter"] = _make_mock_class("Fighter", "5etools")
source._classes["wizard"] = _make_mock_class("Wizard", "5etools")
source._spells["fireball"] = _make_mock_spell("Fireball", "5etools")
source._races["elf"] = _make_mock_race("Elf", "5etools")
source._monsters["goblin"] = _make_mock_monster("Goblin", "5etools")
run_async(source.load())
return source
@pytest.fixture
def campaign_mock_source() -> MockRulebookSource:
"""Create a mock campaign-specific source with different data."""
source = MockRulebookSource(source_id="campaign-srd", name="Campaign SRD")
source._classes["fighter"] = _make_mock_class("Fighter", "Campaign SRD")
source._spells["magic-missile"] = _make_mock_spell("Magic Missile", "Campaign SRD")
source._races["dwarf"] = _make_mock_race("Dwarf", "Campaign SRD")
source._monsters["dragon"] = _make_mock_monster("Dragon", "Campaign SRD")
run_async(source.load())
return source
@pytest.fixture
def global_manager(mock_source: MockRulebookSource) -> RulebookManager:
"""Create a global RulebookManager with mock 5etools data."""
manager = RulebookManager() # No campaign_dir
run_async(manager.load_source(mock_source))
return manager
@pytest.fixture
def campaign_manager(campaign_mock_source: MockRulebookSource, tmp_path: Path) -> RulebookManager:
"""Create a campaign-specific RulebookManager with different data."""
campaign_dir = tmp_path / "campaign"
campaign_dir.mkdir()
(campaign_dir / "rulebooks").mkdir()
manager = RulebookManager(campaign_dir)
run_async(manager.load_source(campaign_mock_source))
return manager
# ===========================================================================
# Test: Global RulebookManager Initialization
# ===========================================================================
class TestGlobalManagerInit:
"""Tests for global RulebookManager initialization at server startup."""
def test_global_manager_created_without_campaign_dir(self, global_manager):
"""Global manager should be created without a campaign directory."""
assert global_manager is not None
assert global_manager.campaign_dir is None
def test_global_manager_has_sources(self, global_manager):
"""Global manager should have loaded sources."""
assert len(global_manager.sources) > 0
assert "mock-5etools" in global_manager.source_ids
def test_global_manager_can_query_classes(self, global_manager):
"""Global manager should be able to query class definitions."""
fighter = global_manager.get_class("fighter")
assert fighter is not None
assert fighter.name == "Fighter"
def test_global_manager_can_query_spells(self, global_manager):
"""Global manager should be able to query spell definitions."""
spell = global_manager.get_spell("fireball")
assert spell is not None
assert spell.name == "Fireball"
def test_global_manager_can_query_races(self, global_manager):
"""Global manager should be able to query race definitions."""
race = global_manager.get_race("elf")
assert race is not None
assert race.name == "Elf"
def test_global_manager_can_query_monsters(self, global_manager):
"""Global manager should be able to query monster definitions."""
monster = global_manager.get_monster("goblin")
assert monster is not None
assert monster.name == "Goblin"
def test_global_manager_can_search(self, global_manager):
"""Global manager should support search across content."""
results = global_manager.search("fire")
assert len(results) > 0
assert any(r.name == "Fireball" for r in results)
def test_global_manager_no_manifest_persistence(self, global_manager, tmp_path):
"""Global manager should not persist manifests (no campaign_dir)."""
# No manifest file should be created since campaign_dir is None
assert global_manager.campaign_dir is None
# Verify no manifest dir was set
assert global_manager._manifest_dir is None
# ===========================================================================
# Test: Rules Queries Without Campaign
# ===========================================================================
class TestRulesWithoutCampaign:
"""Tests for rules tools working without a campaign loaded."""
def test_fallback_to_global_when_no_campaign(self, global_manager):
"""When no campaign manager exists, should use global manager."""
# Simulate: storage.rulebook_manager is None
campaign_manager = None
active_manager = campaign_manager or global_manager
assert active_manager is global_manager
def test_search_rules_without_campaign(self, global_manager):
"""search_rules should work without a campaign by using global manager."""
results = global_manager.search("fighter")
assert len(results) > 0
assert results[0].name == "Fighter"
def test_get_class_without_campaign(self, global_manager):
"""get_class_info should work without a campaign."""
class_def = global_manager.get_class("wizard")
assert class_def is not None
assert class_def.name == "Wizard"
def test_get_spell_without_campaign(self, global_manager):
"""get_spell_info should work without a campaign."""
spell = global_manager.get_spell("fireball")
assert spell is not None
assert spell.name == "Fireball"
def test_get_race_without_campaign(self, global_manager):
"""get_race_info should work without a campaign."""
race = global_manager.get_race("elf")
assert race is not None
assert race.name == "Elf"
def test_get_monster_without_campaign(self, global_manager):
"""get_monster_info should work without a campaign."""
monster = global_manager.get_monster("goblin")
assert monster is not None
assert monster.name == "Goblin"
# ===========================================================================
# Test: Fallback Chain (Campaign Manager Takes Priority)
# ===========================================================================
class TestFallbackChain:
"""Tests for campaign manager taking priority over global manager."""
def test_campaign_manager_takes_priority(self, global_manager, campaign_manager):
"""Campaign manager should take priority when both exist."""
# Simulate the fallback chain
storage_manager = campaign_manager # Campaign has a manager
active_manager = storage_manager or global_manager
assert active_manager is campaign_manager
def test_campaign_fighter_overrides_global(self, global_manager, campaign_manager):
"""Campaign-specific Fighter should override global Fighter."""
# Global has Fighter from "5etools"
global_fighter = global_manager.get_class("fighter")
assert global_fighter.source == "5etools"
# Campaign has Fighter from "Campaign SRD"
campaign_fighter = campaign_manager.get_class("fighter")
assert campaign_fighter.source == "Campaign SRD"
# Fallback chain: campaign wins
active = campaign_manager or global_manager
fighter = active.get_class("fighter")
assert fighter.source == "Campaign SRD"
def test_global_used_when_campaign_manager_is_none(self, global_manager):
"""Global manager should be used when campaign manager is None."""
storage_manager = None
active_manager = storage_manager or global_manager
assert active_manager is global_manager
fighter = active_manager.get_class("fighter")
assert fighter is not None
assert fighter.source == "5etools"
def test_neither_manager_available(self):
"""When both managers are None, result should be None."""
storage_manager = None
global_mgr = None
active_manager = storage_manager or global_mgr
assert active_manager is None
def test_campaign_exclusive_content_available(self, campaign_manager):
"""Content only in campaign manager should be accessible."""
spell = campaign_manager.get_spell("magic-missile")
assert spell is not None
assert spell.name == "Magic Missile"
def test_global_exclusive_content_not_in_campaign(self, global_manager, campaign_manager):
"""Content only in global manager should not be in campaign manager."""
# Fireball is only in global, not in campaign
assert campaign_manager.get_spell("fireball") is None
assert global_manager.get_spell("fireball") is not None
# ===========================================================================
# Test: Source Attribution
# ===========================================================================
class TestSourceAttribution:
"""Tests for source attribution in rule query responses."""
def test_class_has_source_field(self, global_manager):
"""ClassDefinition should include source information."""
fighter = global_manager.get_class("fighter")
assert fighter is not None
assert fighter.source == "5etools"
def test_spell_has_source_field(self, global_manager):
"""SpellDefinition should include source information."""
spell = global_manager.get_spell("fireball")
assert spell is not None
assert spell.source == "5etools"
def test_race_has_source_field(self, global_manager):
"""RaceDefinition should include source information."""
race = global_manager.get_race("elf")
assert race is not None
assert race.source == "5etools"
def test_monster_has_source_field(self, global_manager):
"""MonsterDefinition should include source information."""
monster = global_manager.get_monster("goblin")
assert monster is not None
assert monster.source == "5etools"
def test_search_results_have_source(self, global_manager):
"""Search results should include source attribution."""
results = global_manager.search("fire")
assert len(results) > 0
for r in results:
assert r.source is not None
assert r.source == "5etools"
# ===========================================================================
# Test: rules_version in Campaign Creation
# ===========================================================================
class TestRulesVersionCampaign:
"""Tests for rules_version parameter in campaign creation and loading."""
def test_create_campaign_default_version(self, temp_storage_dir):
"""create_campaign should default to rules_version='2024'."""
storage = DnDStorage(data_dir=temp_storage_dir)
storage.create_campaign(
name="Default Version Campaign",
description="Testing default rules version",
)
assert storage.rules_version == "2024"
def test_create_campaign_with_2014_version(self, temp_storage_dir):
"""create_campaign should accept rules_version='2014'."""
storage = DnDStorage(data_dir=temp_storage_dir)
storage.create_campaign(
name="2014 Campaign",
description="Testing 2014 rules version",
rules_version="2014",
)
assert storage.rules_version == "2014"
def test_create_campaign_with_2024_version(self, temp_storage_dir):
"""create_campaign should accept rules_version='2024'."""
storage = DnDStorage(data_dir=temp_storage_dir)
storage.create_campaign(
name="2024 Campaign",
description="Testing 2024 rules version",
rules_version="2024",
)
assert storage.rules_version == "2024"
def test_rules_version_persisted_in_metadata(self, temp_storage_dir):
"""rules_version should be persisted in campaign.json."""
storage = DnDStorage(data_dir=temp_storage_dir)
storage.create_campaign(
name="Versioned Campaign",
description="Testing persistence",
rules_version="2014",
)
# Read campaign.json directly to verify persistence
campaign_dir = temp_storage_dir / "campaigns" / "Versioned Campaign"
campaign_json = campaign_dir / "campaign.json"
assert campaign_json.exists()
with open(campaign_json, 'r') as f:
metadata = json.load(f)
assert "rules_version" in metadata
assert metadata["rules_version"] == "2014"
def test_rules_version_loaded_on_reload(self, temp_storage_dir):
"""rules_version should be loaded when reloading a campaign."""
# Create campaign with specific version
storage = DnDStorage(data_dir=temp_storage_dir)
storage.create_campaign(
name="Reload Test",
description="Testing reload",
rules_version="2014",
)
assert storage.rules_version == "2014"
# Create fresh storage and load the campaign
storage2 = DnDStorage(data_dir=temp_storage_dir)
storage2.load_campaign("Reload Test")
assert storage2.rules_version == "2014"
def test_rules_version_defaults_on_legacy_campaign(self, temp_storage_dir):
"""Legacy campaigns without rules_version should default to '2024'."""
# Create a campaign, then remove rules_version from metadata
storage = DnDStorage(data_dir=temp_storage_dir)
storage.create_campaign(
name="Legacy Campaign",
description="Testing legacy compatibility",
)
# Remove rules_version from campaign.json
campaign_dir = temp_storage_dir / "campaigns" / "Legacy Campaign"
campaign_json = campaign_dir / "campaign.json"
with open(campaign_json, 'r') as f:
metadata = json.load(f)
if "rules_version" in metadata:
del metadata["rules_version"]
with open(campaign_json, 'w') as f:
json.dump(metadata, f)
# Reload and verify default
storage2 = DnDStorage(data_dir=temp_storage_dir)
storage2.load_campaign("Legacy Campaign")
assert storage2.rules_version == "2024"
def test_rules_version_cleared_on_campaign_delete(self, temp_storage_dir):
"""rules_version should reset to default when campaign is deleted."""
storage = DnDStorage(data_dir=temp_storage_dir)
storage.create_campaign(
name="Delete Me",
description="Testing delete",
rules_version="2014",
)
assert storage.rules_version == "2014"
storage.delete_campaign("Delete Me")
assert storage.rules_version == "2024"
def test_different_campaigns_different_versions(self, temp_storage_dir):
"""Different campaigns can have different rules versions."""
storage = DnDStorage(data_dir=temp_storage_dir)
storage.create_campaign(
name="Modern Campaign",
description="2024 rules",
rules_version="2024",
)
assert storage.rules_version == "2024"
storage.create_campaign(
name="Classic Campaign",
description="2014 rules",
rules_version="2014",
)
assert storage.rules_version == "2014"
# Load the 2024 campaign
storage.load_campaign("Modern Campaign")
assert storage.rules_version == "2024"
# Load the 2014 campaign
storage.load_campaign("Classic Campaign")
assert storage.rules_version == "2014"
# ===========================================================================
# Test: _get_rulebook_manager helper function
# ===========================================================================
class TestGetRulebookManager:
"""Tests for the _get_rulebook_manager fallback chain helper."""
def test_returns_campaign_manager_when_available(self, campaign_manager, global_manager):
"""Should return campaign manager when it exists."""
# Simulate the function logic
storage_manager = campaign_manager
result = storage_manager or global_manager
assert result is campaign_manager
def test_returns_global_when_no_campaign(self, global_manager):
"""Should return global manager when no campaign manager."""
storage_manager = None
result = storage_manager or global_manager
assert result is global_manager
def test_returns_none_when_nothing_available(self):
"""Should return None when neither manager is available."""
storage_manager = None
global_mgr = None
result = storage_manager or global_mgr
assert result is None
def test_campaign_manager_preferred_even_if_empty(self, global_manager, tmp_path):
"""Campaign manager should be preferred even if it has fewer sources."""
# Create an empty campaign manager (no sources loaded)
campaign_dir = tmp_path / "empty_campaign"
campaign_dir.mkdir()
(campaign_dir / "rulebooks").mkdir()
empty_campaign_manager = RulebookManager(campaign_dir)
# The fallback chain uses 'or' which means empty manager (truthy) is still preferred
result = empty_campaign_manager or global_manager
assert result is empty_campaign_manager
# ===========================================================================
# Test: Init function for global manager
# ===========================================================================
class TestInitGlobalManager:
"""Tests for the _init_global_rulebook_manager function."""
def test_init_returns_none_on_failure(self):
"""_init_global_rulebook_manager should return None on failure."""
with patch("dm20_protocol.main.RulebookManager") as MockManager:
MockManager.side_effect = Exception("Init failed")
from dm20_protocol.main import _init_global_rulebook_manager
result = _init_global_rulebook_manager()
assert result is None
def test_init_creates_manager_with_no_campaign_dir(self):
"""_init_global_rulebook_manager should create manager without campaign_dir."""
with patch("dm20_protocol.main.RulebookManager") as MockManager:
mock_instance = MagicMock()
MockManager.return_value = mock_instance
with patch("dm20_protocol.main.FiveToolsSource", create=True):
# Mock the async load_source
mock_instance.load_source = AsyncMock()
from dm20_protocol.main import _init_global_rulebook_manager
# The function will be called but may fail due to import context
# This mainly validates the function exists and is callable
assert callable(_init_global_rulebook_manager)
