lumibot 4.1.3__py3-none-any.whl → 4.2.1__py3-none-any.whl

tests/backtest/test_polars_lru_eviction.py

@@ -0,0 +1,470 @@
+"""
+Test LRU eviction functionality for Polars data sources.
+
+This test verifies that:
+1. Memory limits are enforced via LRU eviction
+2. Two-tier eviction works (aggregated cache first, then data store)
+3. LRU order is maintained (oldest unused items evicted first)
+4. Memory calculation is accurate
+5. Multiple symbols are handled correctly under memory pressure
+"""
+
+import pytest
+from datetime import datetime, timedelta
+import polars as pl
+
+from lumibot.entities import Asset
+from lumibot.entities.data_polars import DataPolars
+from lumibot.data_sources.polars_data import PolarsData
+
+
+class TestLRUEviction:
+    """Test suite for LRU eviction functionality"""
+
+    def test_memory_limit_configuration(self):
+        """Test that memory limit is configured correctly"""
+        start_date = datetime(2024, 1, 1)
+        end_date = datetime(2024, 1, 31)
+
+        polars_data = PolarsData(
+            datetime_start=start_date,
+            datetime_end=end_date,
+            pandas_data=None
+        )
+
+        # Default should be 1GB
+        assert polars_data.MAX_STORAGE_BYTES == 1_000_000_000
+
+    def test_eviction_from_aggregated_cache_first(self):
+        """Test that eviction happens from aggregated cache first.
+
+        This test verifies the two-tier eviction priority:
+        1. Aggregated cache is evicted first (less critical)
+        2. Data store is evicted only if aggregated cache eviction isn't enough
+        """
+        start_date = datetime(2024, 1, 1)
+        end_date = datetime(2024, 1, 31)
+
+        polars_data = PolarsData(
+            datetime_start=start_date,
+            datetime_end=end_date,
+            pandas_data=None
+        )
+
+        # Set memory limit high enough that evicting aggregated cache is sufficient
+        # Each asset: ~48KB data + ~10KB aggregated = ~58KB total
+        # 5 assets = ~290KB total
+        # Set limit to 250KB so aggregated cache eviction (50KB) is enough
+        polars_data.MAX_STORAGE_BYTES = 250_000  # 250KB
+
+        # Create 1-minute test data for 5 assets
+        assets = [Asset(f"TEST{i}", "stock") for i in range(5)]
+        quote = Asset("USD", "forex")
+
+        for asset in assets:
+            dates = pl.datetime_range(
+                start_date,
+                start_date + timedelta(minutes=1000),
+                interval="1m",
+                eager=True
+            )
+            df = pl.DataFrame({
+                "datetime": dates,
+                "open": [100.0] * len(dates),
+                "high": [101.0] * len(dates),
+                "low": [99.0] * len(dates),
+                "close": [100.5] * len(dates),
+                "volume": [1000.0] * len(dates),
+            })
+            data = DataPolars(asset, df=df, timestep="minute", quote=None)
+            polars_data._data_store[(asset, quote)] = data
+
+        # Aggregate all 5 assets to create aggregated cache entries
+        for asset in assets:
+            polars_data._get_or_aggregate_bars(asset, quote, 100, "minute", "5 minutes")
+
+        assert len(polars_data._aggregated_cache) == 5
+        original_data_store_size = len(polars_data._data_store)
+
+        # CRITICAL: Set _trim_iteration_count = 0 to actually trigger enforcement
+        # (Production code only enforces when _trim_iteration_count == 0)
+        polars_data._trim_iteration_count = 0
+
+        # Force memory limit enforcement
+        polars_data._enforce_memory_limits()
+
+        # Aggregated cache should be partially/fully evicted
+        # Data store should still have all 5 assets (evicting agg cache was enough)
+        assert len(polars_data._aggregated_cache) < 5, "Aggregated cache should have been evicted"
+        assert len(polars_data._data_store) == original_data_store_size, \
+            f"Data store should be untouched (expected {original_data_store_size}, got {len(polars_data._data_store)})"
+
+    def test_eviction_from_data_store_when_aggregated_empty(self):
+        """Test that eviction happens from data_store when aggregated cache is empty"""
+        start_date = datetime(2024, 1, 1)
+        end_date = datetime(2024, 1, 31)
+
+        polars_data = PolarsData(
+            datetime_start=start_date,
+            datetime_end=end_date,
+            pandas_data=None
+        )
+
+        # Set a very low memory limit
+        polars_data.MAX_STORAGE_BYTES = 50_000  # 50KB
+
+        # Create 1-minute test data for 10 assets (no aggregated cache)
+        assets = [Asset(f"TEST{i}", "stock") for i in range(10)]
+        quote = Asset("USD", "forex")
+
+        for asset in assets:
+            dates = pl.datetime_range(
+                start_date,
+                start_date + timedelta(minutes=1000),
+                interval="1m",
+                eager=True
+            )
+            df = pl.DataFrame({
+                "datetime": dates,
+                "open": [100.0] * len(dates),
+                "high": [101.0] * len(dates),
+                "low": [99.0] * len(dates),
+                "close": [100.5] * len(dates),
+                "volume": [1000.0] * len(dates),
+            })
+            data = DataPolars(asset, df=df, timestep="minute", quote=None)
+            polars_data._data_store[(asset, quote)] = data
+
+        # No aggregated cache entries
+        assert len(polars_data._aggregated_cache) == 0
+
+        # Set _trim_iteration_count = 0 to trigger enforcement
+        polars_data._trim_iteration_count = 0
+
+        # Force memory limit enforcement
+        polars_data._enforce_memory_limits()
+
+        # Data store should have been evicted
+        assert len(polars_data._data_store) < 10
+
+    def test_lru_order_maintained(self):
+        """Test that LRU order is maintained - oldest unused items evicted first"""
+        start_date = datetime(2024, 1, 1)
+        end_date = datetime(2024, 1, 31)
+
+        polars_data = PolarsData(
+            datetime_start=start_date,
+            datetime_end=end_date,
+            pandas_data=None
+        )
+
+        # Create 5 assets
+        assets = [Asset(f"TEST{i}", "stock") for i in range(5)]
+        quote = Asset("USD", "forex")
+
+        for asset in assets:
+            dates = pl.datetime_range(
+                start_date,
+                start_date + timedelta(minutes=1000),
+                interval="1m",
+                eager=True
+            )
+            df = pl.DataFrame({
+                "datetime": dates,
+                "open": [100.0] * len(dates),
+                "high": [101.0] * len(dates),
+                "low": [99.0] * len(dates),
+                "close": [100.5] * len(dates),
+                "volume": [1000.0] * len(dates),
+            })
+            data = DataPolars(asset, df=df, timestep="minute", quote=None)
+            polars_data._data_store[(asset, quote)] = data
+
+        # Aggregate all 5 to create cache entries in order
+        for asset in assets:
+            polars_data._get_or_aggregate_bars(asset, quote, 100, "minute", "5 minutes")
+
+        # Access TEST0, TEST1, TEST2 again (should move to end)
+        polars_data._get_or_aggregate_bars(assets[0], quote, 100, "minute", "5 minutes")
+        polars_data._get_or_aggregate_bars(assets[1], quote, 100, "minute", "5 minutes")
+        polars_data._get_or_aggregate_bars(assets[2], quote, 100, "minute", "5 minutes")
+
+        # Order should now be: TEST3, TEST4, TEST0, TEST1, TEST2 (least to most recent)
+        keys = list(polars_data._aggregated_cache.keys())
+        assert keys[0][0] == assets[3]  # TEST3 is oldest
+        assert keys[1][0] == assets[4]  # TEST4 is second oldest
+        assert keys[-3][0] == assets[0]  # TEST0 is third newest
+        assert keys[-2][0] == assets[1]  # TEST1 is second newest
+        assert keys[-1][0] == assets[2]  # TEST2 is newest
+
+    def test_memory_calculation_accuracy(self):
+        """Test that memory calculation is accurate using polars estimated_size()"""
+        start_date = datetime(2024, 1, 1)
+        end_date = datetime(2024, 1, 31)
+
+        polars_data = PolarsData(
+            datetime_start=start_date,
+            datetime_end=end_date,
+            pandas_data=None
+        )
+
+        # Create test data
+        asset = Asset("TEST", "stock")
+        quote = Asset("USD", "forex")
+        dates = pl.datetime_range(
+            start_date,
+            start_date + timedelta(minutes=1000),
+            interval="1m",
+            eager=True
+        )
+        df = pl.DataFrame({
+            "datetime": dates,
+            "open": [100.0] * len(dates),
+            "high": [101.0] * len(dates),
+            "low": [99.0] * len(dates),
+            "close": [100.5] * len(dates),
+            "volume": [1000.0] * len(dates),
+        })
+
+        data = DataPolars(asset, df=df, timestep="minute", quote=None)
+        polars_data._data_store[(asset, quote)] = data
+
+        # Calculate memory manually
+        expected_size = df.estimated_size()
+
+        # Should be non-zero
+        assert expected_size > 0
+
+        # Create aggregated cache entry
+        polars_data._get_or_aggregate_bars(asset, quote, 100, "minute", "5 minutes")
+
+        # Calculate total memory
+        total_memory = 0
+        for data in polars_data._data_store.values():
+            if hasattr(data, 'polars_df'):
+                total_memory += data.polars_df.estimated_size()
+
+        for agg_df in polars_data._aggregated_cache.values():
+            if agg_df is not None:
+                total_memory += agg_df.estimated_size()
+
+        # Should be larger than original df
+        assert total_memory > expected_size
+
+    def test_two_tier_eviction(self):
+        """Test that two-tier eviction works: aggregated first, then data store"""
+        start_date = datetime(2024, 1, 1)
+        end_date = datetime(2024, 1, 31)
+
+        polars_data = PolarsData(
+            datetime_start=start_date,
+            datetime_end=end_date,
+            pandas_data=None
+        )
+
+        # Set memory limit to force eviction
+        polars_data.MAX_STORAGE_BYTES = 80_000  # 80KB
+
+        # Create 5 assets
+        assets = [Asset(f"TEST{i}", "stock") for i in range(5)]
+        quote = Asset("USD", "forex")
+
+        for asset in assets:
+            dates = pl.datetime_range(
+                start_date,
+                start_date + timedelta(minutes=1000),
+                interval="1m",
+                eager=True
+            )
+            df = pl.DataFrame({
+                "datetime": dates,
+                "open": [100.0] * len(dates),
+                "high": [101.0] * len(dates),
+                "low": [99.0] * len(dates),
+                "close": [100.5] * len(dates),
+                "volume": [1000.0] * len(dates),
+            })
+            data = DataPolars(asset, df=df, timestep="minute", quote=None)
+            polars_data._data_store[(asset, quote)] = data
+
+        # Create aggregated cache entries for all 5
+        for asset in assets:
+            polars_data._get_or_aggregate_bars(asset, quote, 100, "minute", "5 minutes")
+
+        initial_data_store_size = len(polars_data._data_store)
+        initial_agg_cache_size = len(polars_data._aggregated_cache)
+
+        assert initial_data_store_size == 5
+        assert initial_agg_cache_size == 5
+
+        # Set _trim_iteration_count = 0 to trigger enforcement
+        polars_data._trim_iteration_count = 0
+
+        # Force eviction
+        polars_data._enforce_memory_limits()
+
+        # Aggregated cache should be evicted first
+        after_eviction_agg_size = len(polars_data._aggregated_cache)
+        after_eviction_data_size = len(polars_data._data_store)
+
+        # Either aggregated cache was reduced, or if that wasn't enough, data store was reduced
+        assert after_eviction_agg_size < initial_agg_cache_size or \
+               after_eviction_data_size < initial_data_store_size
+
+    def test_multiple_symbols_under_pressure(self):
+        """Test handling of multiple symbols under memory pressure"""
+        start_date = datetime(2024, 1, 1)
+        end_date = datetime(2024, 1, 31)
+
+        polars_data = PolarsData(
+            datetime_start=start_date,
+            datetime_end=end_date,
+            pandas_data=None
+        )
+
+        # Very low memory limit
+        polars_data.MAX_STORAGE_BYTES = 30_000  # 30KB
+
+        # Create 20 assets (more than can fit in memory)
+        assets = [Asset(f"TEST{i}", "stock") for i in range(20)]
+        quote = Asset("USD", "forex")
+
+        for asset in assets:
+            dates = pl.datetime_range(
+                start_date,
+                start_date + timedelta(minutes=500),  # Smaller dataset
+                interval="1m",
+                eager=True
+            )
+            df = pl.DataFrame({
+                "datetime": dates,
+                "open": [100.0] * len(dates),
+                "high": [101.0] * len(dates),
+                "low": [99.0] * len(dates),
+                "close": [100.5] * len(dates),
+                "volume": [1000.0] * len(dates),
+            })
+            data = DataPolars(asset, df=df, timestep="minute", quote=None)
+            polars_data._data_store[(asset, quote)] = data
+
+            # Set _trim_iteration_count = 0 to trigger enforcement
+            polars_data._trim_iteration_count = 0
+
+            # Enforce limits after each addition
+            polars_data._enforce_memory_limits()
+
+        # Should have evicted some items
+        final_size = len(polars_data._data_store)
+        assert final_size < 20
+        assert final_size > 0  # Should keep at least some data
+
+    def test_no_eviction_under_limit(self):
+        """Test that no eviction happens when under memory limit"""
+        start_date = datetime(2024, 1, 1)
+        end_date = datetime(2024, 1, 31)
+
+        polars_data = PolarsData(
+            datetime_start=start_date,
+            datetime_end=end_date,
+            pandas_data=None
+        )
+
+        # Very high memory limit (default 1GB should be fine)
+        # Create just 2 small assets
+        assets = [Asset(f"TEST{i}", "stock") for i in range(2)]
+        quote = Asset("USD", "forex")
+
+        for asset in assets:
+            dates = pl.datetime_range(
+                start_date,
+                start_date + timedelta(minutes=100),
+                interval="1m",
+                eager=True
+            )
+            df = pl.DataFrame({
+                "datetime": dates,
+                "open": [100.0] * len(dates),
+                "high": [101.0] * len(dates),
+                "low": [99.0] * len(dates),
+                "close": [100.5] * len(dates),
+                "volume": [1000.0] * len(dates),
+            })
+            data = DataPolars(asset, df=df, timestep="minute", quote=None)
+            polars_data._data_store[(asset, quote)] = data
+
+        # Aggregate both
+        for asset in assets:
+            polars_data._get_or_aggregate_bars(asset, quote, 50, "minute", "5 minutes")
+
+        # Record sizes
+        data_store_size = len(polars_data._data_store)
+        agg_cache_size = len(polars_data._aggregated_cache)
+
+        # Set _trim_iteration_count = 0 to trigger enforcement
+        polars_data._trim_iteration_count = 0
+
+        # Force enforcement
+        polars_data._enforce_memory_limits()
+
+        # Nothing should be evicted
+        assert len(polars_data._data_store) == data_store_size
+        assert len(polars_data._aggregated_cache) == agg_cache_size
+
+    def test_eviction_updates_lru_order(self):
+        """Test that eviction correctly updates LRU order"""
+        start_date = datetime(2024, 1, 1)
+        end_date = datetime(2024, 1, 31)
+
+        polars_data = PolarsData(
+            datetime_start=start_date,
+            datetime_end=end_date,
+            pandas_data=None
+        )
+
+        # Set memory limit
+        polars_data.MAX_STORAGE_BYTES = 60_000  # 60KB
+
+        # Create 5 assets
+        assets = [Asset(f"TEST{i}", "stock") for i in range(5)]
+        quote = Asset("USD", "forex")
+
+        for asset in assets:
+            dates = pl.datetime_range(
+                start_date,
+                start_date + timedelta(minutes=1000),
+                interval="1m",
+                eager=True
+            )
+            df = pl.DataFrame({
+                "datetime": dates,
+                "open": [100.0] * len(dates),
+                "high": [101.0] * len(dates),
+                "low": [99.0] * len(dates),
+                "close": [100.5] * len(dates),
+                "volume": [1000.0] * len(dates),
+            })
+            data = DataPolars(asset, df=df, timestep="minute", quote=None)
+            polars_data._data_store[(asset, quote)] = data
+
+        # Aggregate all 5 in order: 0, 1, 2, 3, 4
+        for asset in assets:
+            polars_data._get_or_aggregate_bars(asset, quote, 100, "minute", "5 minutes")
+
+        # Access 4 again (should move to end)
+        polars_data._get_or_aggregate_bars(assets[4], quote, 100, "minute", "5 minutes")
+
+        # Set _trim_iteration_count = 0 to trigger enforcement
+        polars_data._trim_iteration_count = 0
+
+        # Force eviction
+        polars_data._enforce_memory_limits()
+
+        # After eviction, if TEST4 is still in cache, it should be at the end
+        if (assets[4], quote, "5 minutes") in polars_data._aggregated_cache:
+            keys = list(polars_data._aggregated_cache.keys())
+            # TEST4 should be last (most recent)
+            assert keys[-1][0] == assets[4]
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v", "-s"])

tests/backtest/test_yahoo.py

@@ -1,4 +1,6 @@
 import datetime
+import pandas as pd
+import pytz
 import pytest
 
 from lumibot.backtesting import BacktestingBroker, YahooDataBacktesting
@@ -28,6 +30,45 @@ class YahooPriceTest(Strategy):
 
 class TestYahooBacktestFull:
 
+    def test_yahoo_no_future_bars_before_open(self, monkeypatch):
+        tz = pytz.timezone('America/New_York')
+        asset = 'SPY'
+        index = pd.DatetimeIndex([
+            tz.localize(datetime.datetime(2023, 10, 31, 16, 0)),
+            tz.localize(datetime.datetime(2023, 11, 1, 16, 0)),
+        ])
+
+        frame = pd.DataFrame(
+            {
+                'Open': [416.18, 419.20],
+                'High': [416.50, 420.10],
+                'Low': [415.80, 418.90],
+                'Close': [418.53, 419.54],
+                'Volume': [1_000_000, 1_100_000],
+                'Dividends': [0.0, 0.0],
+                'Stock Splits': [0.0, 0.0],
+            },
+            index=index,
+        )
+
+        monkeypatch.setattr(
+            'lumibot.tools.YahooHelper.get_symbol_data',
+            lambda *args, **kwargs: frame,
+        )
+
+        data_source = YahooDataBacktesting(
+            datetime_start=datetime.datetime(2023, 10, 30),
+            datetime_end=datetime.datetime(2023, 11, 2),
+        )
+        data_source._datetime = tz.localize(datetime.datetime(2023, 11, 1, 8, 45))
+
+        price = data_source.get_last_price(asset, timestep='day')
+        assert round(price, 2) == 416.18
+
+        bars = data_source.get_historical_prices(asset, 1, timestep='day')
+        # The bar timestamp must be strictly before the current backtest clock to avoid lookahead.
+        assert bars.df.index[-1] < data_source._datetime
+
     def test_yahoo_last_price(self):
         """
         Test the YahooDataBacktesting class by running a backtest and checking that the strategy object is returned
@@ -62,3 +103,4 @@ class TestYahooBacktestFull:
         last_price = round(last_price, 2)
 
         assert last_price == 416.18  # This is the correct price for 2023-11-01 (the open price)
+

tests/test_asset.py

@@ -124,12 +124,12 @@ def test_resolve_continuous_futures_contract_year_digits():
     assert four_digit == "MNQZ2025"
 
 
-def test_resolve_continuous_futures_contract_rolls_mid_month():
-    """Verify contracts roll to next quarter after mid-month in expiry month."""
+def test_resolve_continuous_futures_contract_rolls_on_rule_date():
+    """Verify contracts roll eight business days before the third Friday."""
     asset = Asset(symbol="MNQ", asset_type=Asset.AssetType.CONT_FUTURE)
 
-    before_roll = datetime.datetime(2025, 9, 10)
-    after_roll = datetime.datetime(2025, 9, 20)
+    before_roll = datetime.datetime(2025, 9, 8)
+    after_roll = datetime.datetime(2025, 9, 10)
 
     contract_before = asset.resolve_continuous_futures_contract(reference_date=before_roll)
     contract_after = asset.resolve_continuous_futures_contract(reference_date=after_roll)

tests/test_backtest_cache_manager.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, Tuple
+
+import pytest
+
+from lumibot.tools import backtest_cache
+from lumibot.tools.backtest_cache import (
+    BacktestCacheManager,
+    BacktestCacheSettings,
+    CacheMode,
+    reset_backtest_cache_manager,
+)
+
+
+@pytest.fixture(autouse=True)
+def reset_manager():
+    reset_backtest_cache_manager(for_testing=True)
+    yield
+    reset_backtest_cache_manager(for_testing=True)
+
+
+def test_settings_from_env_disabled_when_backend_not_s3():
+    config = {
+        "backend": "local",
+        "mode": "disabled",
+    }
+    assert BacktestCacheSettings.from_env(config) is None
+
+
+def test_settings_from_env_requires_bucket():
+    config = {
+        "backend": "s3",
+        "mode": "readwrite",
+    }
+    with pytest.raises(ValueError):
+        BacktestCacheSettings.from_env(config)
+
+
+class StubS3Client:
+    def __init__(self, objects: Dict[Tuple[str, str], bytes] | None = None):
+        self.objects = objects or {}
+        self.uploads: Dict[Tuple[str, str], bytes] = {}
+
+    def download_file(self, bucket: str, key: str, destination: str) -> None:
+        lookup = (bucket, key)
+        if lookup not in self.objects:
+            raise FileNotFoundError(f"{bucket}/{key} missing")
+        Path(destination).write_bytes(self.objects[lookup])
+
+    def upload_file(self, source: str, bucket: str, key: str) -> None:
+        self.uploads[(bucket, key)] = Path(source).read_bytes()
+
+
+def _build_settings(prefix: str = "prod/cache") -> BacktestCacheSettings:
+    return BacktestCacheSettings(
+        backend="s3",
+        mode=CacheMode.S3_READWRITE,
+        bucket="test-bucket",
+        prefix=prefix,
+        region="us-east-1",
+        version="v3",
+    )
+
+
+def test_remote_key_uses_relative_cache_path(tmp_path, monkeypatch):
+    cache_root = tmp_path / "cache"
+    cache_root.mkdir()
+    local_file = cache_root / "thetadata" / "bars" / "spy.parquet"
+    local_file.parent.mkdir(parents=True, exist_ok=True)
+
+    monkeypatch.setattr(backtest_cache, "LUMIBOT_CACHE_FOLDER", cache_root)
+
+    settings = _build_settings(prefix="stage/cache")
+    manager = BacktestCacheManager(settings, client_factory=lambda settings: StubS3Client())
+
+    remote_key = manager.remote_key_for(local_file)
+    assert remote_key == "stage/cache/v3/thetadata/bars/spy.parquet"
+
+
+def test_ensure_local_file_downloads_from_s3(tmp_path, monkeypatch):
+    cache_root = tmp_path / "cache"
+    cache_root.mkdir()
+    local_file = cache_root / "thetadata" / "bars" / "spy.parquet"
+
+    monkeypatch.setattr(backtest_cache, "LUMIBOT_CACHE_FOLDER", cache_root)
+
+    remote_key = "stage/cache/v3/thetadata/bars/spy.parquet"
+    objects = {("test-bucket", remote_key): b"cached-data"}
+
+    stub = StubS3Client(objects)
+    manager = BacktestCacheManager(_build_settings(prefix="stage/cache"), client_factory=lambda s: stub)
+
+    fetched = manager.ensure_local_file(local_file)
+    assert fetched is True
+    assert local_file.exists()
+    assert local_file.read_bytes() == b"cached-data"
+
+
+def test_ensure_local_file_handles_missing_remote(tmp_path, monkeypatch):
+    cache_root = tmp_path / "cache"
+    cache_root.mkdir()
+    local_file = cache_root / "thetadata" / "bars" / "spy.parquet"
+
+    monkeypatch.setattr(backtest_cache, "LUMIBOT_CACHE_FOLDER", cache_root)
+
+    stub = StubS3Client()
+    manager = BacktestCacheManager(_build_settings(prefix="stage/cache"), client_factory=lambda s: stub)
+
+    fetched = manager.ensure_local_file(local_file)
+    assert fetched is False
+    assert not local_file.exists()
+
+
+def test_on_local_update_uploads_file(tmp_path, monkeypatch):
+    cache_root = tmp_path / "cache"
+    cache_root.mkdir()
+    local_file = cache_root / "thetadata" / "bars" / "spy.parquet"
+    local_file.parent.mkdir(parents=True, exist_ok=True)
+    local_file.write_bytes(b"new-data")
+
+    monkeypatch.setattr(backtest_cache, "LUMIBOT_CACHE_FOLDER", cache_root)
+
+    remote_key = "stage/cache/v3/thetadata/bars/spy.parquet"
+    stub = StubS3Client({("test-bucket", remote_key): b"old"})
+    manager = BacktestCacheManager(_build_settings(prefix="stage/cache"), client_factory=lambda s: stub)
+
+    uploaded = manager.on_local_update(local_file)
+    assert uploaded is True
+    assert stub.uploads[( "test-bucket", remote_key)] == b"new-data"
+
+
+def test_manager_disabled_skip_upload(tmp_path, monkeypatch):
+    cache_root = tmp_path / "cache"
+    cache_root.mkdir()
+    local_file = cache_root / "foo.parquet"
+    local_file.write_bytes(b"noop")
+
+    monkeypatch.setattr(backtest_cache, "LUMIBOT_CACHE_FOLDER", cache_root)
+
+    disabled_settings = BacktestCacheSettings(
+        backend="local",
+        mode=CacheMode.DISABLED,
+    )
+    manager = BacktestCacheManager(disabled_settings)
+
+    assert manager.ensure_local_file(local_file) is False
+    assert manager.on_local_update(local_file) is False