~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""Tests for web/utils/vite_helper.py."""
import hashlib
import io
import json
import os
import threading
from pathlib import Path
from unittest.mock import Mock, patch
import pytest
class TestViteHelperInit:
"""Tests for ViteHelper initialization."""
def test_init_without_app(self):
"""Test initialization without Flask app."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
assert helper.app is None
assert helper.manifest is None
assert helper.is_dev is False
def test_init_with_app_calls_init_app(self):
"""Test that initialization with app calls init_app."""
from local_deep_research.web.utils.vite_helper import ViteHelper
mock_app = Mock()
mock_app.debug = False
mock_app.config = {}
mock_app.jinja_env = Mock()
mock_app.jinja_env.globals = {}
with patch.object(ViteHelper, "_load_manifest"):
helper = ViteHelper(app=mock_app)
assert helper.app is mock_app
class TestViteHelperInitApp:
"""Tests for ViteHelper.init_app method."""
def test_init_app_sets_app_attribute(self):
"""Test that init_app sets the app attribute."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
mock_app = Mock()
mock_app.debug = False
mock_app.config = {}
mock_app.jinja_env = Mock()
mock_app.jinja_env.globals = {}
with patch.object(helper, "_load_manifest"):
helper.init_app(mock_app)
assert helper.app is mock_app
def test_init_app_sets_dev_mode_from_debug(self):
"""Test that is_dev is set from app.debug."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
mock_app = Mock()
mock_app.debug = True
mock_app.config = {}
mock_app.jinja_env = Mock()
mock_app.jinja_env.globals = {}
helper.init_app(mock_app)
assert helper.is_dev is True
def test_init_app_sets_dev_mode_from_config(self):
"""Test that is_dev can be set from VITE_DEV_MODE config."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
mock_app = Mock()
mock_app.debug = False
mock_app.config = {"VITE_DEV_MODE": True}
mock_app.jinja_env = Mock()
mock_app.jinja_env.globals = {}
helper.init_app(mock_app)
assert helper.is_dev is True
def test_init_app_registers_vite_asset_global(self):
"""Test that vite_asset is registered as Jinja global."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
mock_app = Mock()
mock_app.debug = True
mock_app.config = {}
mock_app.jinja_env = Mock()
mock_app.jinja_env.globals = {}
helper.init_app(mock_app)
assert "vite_asset" in mock_app.jinja_env.globals
assert mock_app.jinja_env.globals["vite_asset"] == helper.vite_asset
def test_init_app_registers_vite_hmr_global(self):
"""Test that vite_hmr is registered as Jinja global."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
mock_app = Mock()
mock_app.debug = True
mock_app.config = {}
mock_app.jinja_env = Mock()
mock_app.jinja_env.globals = {}
helper.init_app(mock_app)
assert "vite_hmr" in mock_app.jinja_env.globals
assert mock_app.jinja_env.globals["vite_hmr"] == helper.vite_hmr
def test_init_app_loads_manifest_in_production(self):
"""Test that manifest is loaded in production mode."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
mock_app = Mock()
mock_app.debug = False
mock_app.config = {}
mock_app.jinja_env = Mock()
mock_app.jinja_env.globals = {}
with patch.object(helper, "_load_manifest") as mock_load:
helper.init_app(mock_app)
mock_load.assert_called_once()
def test_init_app_skips_manifest_in_dev(self):
"""Test that manifest loading is skipped in dev mode."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
mock_app = Mock()
mock_app.debug = True
mock_app.config = {}
mock_app.jinja_env = Mock()
mock_app.jinja_env.globals = {}
with patch.object(helper, "_load_manifest") as mock_load:
helper.init_app(mock_app)
mock_load.assert_not_called()
class TestViteHelperLoadManifest:
"""Tests for ViteHelper._load_manifest method."""
def test_load_manifest_reads_json_file(self, tmp_path):
"""Test that manifest JSON is loaded from file."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.app = Mock()
helper.app.config = {"STATIC_DIR": str(tmp_path)}
manifest_data = {"js/app.js": {"file": "assets/app-abc123.js"}}
manifest_path = tmp_path / "dist" / ".vite" / "manifest.json"
manifest_path.parent.mkdir(parents=True)
manifest_path.write_text(json.dumps(manifest_data), encoding="utf-8")
asset_path = tmp_path / "dist" / "assets" / "app-abc123.js"
asset_path.parent.mkdir()
asset_path.write_text("// built", encoding="utf-8")
helper._load_manifest()
assert helper.manifest == manifest_data
def test_load_manifest_uses_default_static_dir(self, monkeypatch, tmp_path):
"""Test that default static directory is used when not configured."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.app = Mock()
helper.app.config = {}
monkeypatch.chdir(tmp_path)
helper._load_manifest()
assert helper.manifest == {}
def test_load_manifest_handles_missing_file(self, tmp_path):
"""Test that missing manifest file results in empty dict."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.app = Mock()
helper.app.config = {"STATIC_DIR": str(tmp_path)}
helper._load_manifest()
assert helper.manifest == {}
class TestViteHelperViteHmr:
"""Tests for ViteHelper.vite_hmr method."""
def test_vite_hmr_returns_script_in_dev_mode(self):
"""Test that HMR script is returned in development mode."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = True
result = helper.vite_hmr()
assert "localhost:5173" in str(result)
assert "@vite/client" in str(result)
assert '<script type="module"' in str(result)
def test_vite_hmr_returns_empty_in_production(self):
"""Test that empty string is returned in production mode."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
result = helper.vite_hmr()
assert result == ""
class TestViteHelperViteAsset:
"""Tests for ViteHelper.vite_asset method.
Every helper here is a bare ``ViteHelper()`` with ``_manifest_path``
left at None and ``manifest`` assigned in memory, which is the
*no-`dist_root`* path: `_refresh_manifest_if_stale()` returns without
touching the filesystem and `_entry_problem()` checks the manifest's
shape only. These are markup/branching tests; they are not coverage of
the on-disk validation, which needs a real `dist/` tree and lives in
`TestRequestedEntryConsistency`.
"""
def test_vite_asset_returns_dev_server_url_in_dev_mode(self):
"""Test that dev server URL is returned in development mode."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = True
result = helper.vite_asset("js/app.js")
assert "localhost:5173" in str(result)
assert "js/app.js" in str(result)
assert '<script type="module"' in str(result)
def test_vite_asset_uses_default_entry_point(self):
"""Test that default entry point is used when not specified."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = True
result = helper.vite_asset()
assert "js/app.js" in str(result)
def test_vite_asset_returns_manifest_path_in_production(self):
"""Test that manifest file path is returned in production."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
helper.manifest = {
"js/app.js": {
"file": "assets/app-abc123.js",
}
}
result = helper.vite_asset("js/app.js")
assert "/static/dist/assets/app-abc123.js" in str(result)
assert '<script type="module"' in str(result)
def test_vite_asset_includes_css_from_manifest(self):
"""Test that CSS files from manifest are included."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
helper.manifest = {
"js/app.js": {
"file": "assets/app-abc123.js",
"css": ["assets/app-abc123.css", "assets/vendor-def456.css"],
}
}
result = helper.vite_asset("js/app.js")
assert "/static/dist/assets/app-abc123.css" in str(result)
assert "/static/dist/assets/vendor-def456.css" in str(result)
assert '<link rel="stylesheet"' in str(result)
def test_vite_asset_returns_fallback_when_no_manifest(self):
"""Test that fallback is returned when manifest is empty."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
helper.manifest = {}
result = helper.vite_asset("js/app.js")
assert "Vite build not found" in str(result)
def test_vite_asset_returns_fallback_for_missing_entry(self):
"""Test that fallback is returned for missing entry point."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
helper.manifest = {"other/file.js": {"file": "assets/other.js"}}
result = helper.vite_asset("js/missing.js")
assert "Vite build not found" in str(result)
@pytest.fixture(autouse=True)
def _reset_warned_causes():
"""Reset the module-level "already warned" guard around every test.
`_warned_causes` is intentionally module-level state (so each distinct
cause is reported once per process, not once per request). That means it
leaks across tests unless we reset it, both before and after, so tests
that check "warns" and tests that check "doesn't warn" don't depend on
execution order.
"""
import local_deep_research.web.utils.vite_helper as vite_helper_module
vite_helper_module._warned_causes.clear()
yield
vite_helper_module._warned_causes.clear()
class TestViteHelperFallbackAssets:
"""Tests for ViteHelper._fallback_assets method."""
def test_fallback_assets_returns_comment(self):
"""Test that fallback returns informative HTML comment."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
result = helper._fallback_assets()
assert "Vite build not found" in str(result)
assert "npm run build" in str(result)
def test_missing_assets_banner_is_visible_and_self_contained(self):
"""The body-level banner names the problem and the fix."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
helper.manifest = {}
result_str = str(helper.missing_assets_banner())
assert 'id="ldr-vite-missing-assets-banner"' in result_str
assert "not been built" in result_str
assert "npm run build" in result_str
# Inline styles are required: the real stylesheet is what's missing.
assert "style=" in result_str
def test_missing_assets_banner_mentions_restart_as_a_fallback(self):
"""A restart is the last resort, not the instruction.
The helper re-reads the manifest on every production render, so a
rebuild is picked up without restarting anything - and the banner
must say so, because telling operators to bounce the server for a
problem a reload already fixes is how a 30-second fix becomes an
outage. It still names a restart, as the fallback for the case where
the banner survives a successful build and reload, which is the same
thing `docs/FRONTEND_BUILD_SYSTEM.md` says.
Merely asserting that the word "restart" appears is satisfied by the
wording this replaced ("run `npm run build`, then restart the
server"), which said the opposite. The sentences that carry the
meaning are pinned instead.
"""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
helper.manifest = {}
result_str = " ".join(str(helper.missing_assets_banner()).split())
assert "picked up" in result_str
assert "without a restart" in result_str
assert "restarting the server is the last resort" in result_str
def test_missing_assets_banner_empty_when_assets_built(self):
"""A healthy production build renders no banner at all."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
helper.manifest = {"js/app.js": {"file": "assets/app-abc123.js"}}
assert str(helper.missing_assets_banner()) == ""
def test_missing_assets_banner_empty_in_dev_mode(self):
"""Dev-server mode has no manifest by design - never banner it."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = True
helper.manifest = None
assert str(helper.missing_assets_banner()) == ""
def test_fallback_assets_logs_warning_once(self):
"""Test that a server-side warning is logged the first time."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
helper._fallback_assets()
mock_logger.warning.assert_called_once()
(message,), _ = mock_logger.warning.call_args
assert "npm run build" in message
def test_fallback_assets_with_entry_logs_entry_not_found(self):
"""When entry_point is passed, the warning names the missing entry.
This locks the differentiated log contract: a missing manifest file
and a missing entry inside an existing manifest are different
operator-facing problems and must not share one vague message.
"""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
helper._fallback_assets(entry_point="js/app.js")
mock_logger.warning.assert_called_once()
(message,), _ = mock_logger.warning.call_args
assert "manifest entry" in message
assert "js/app.js" in message
assert "manifest not found" not in message
def test_fallback_assets_does_not_repeat_warning(self):
"""Test that the warning is only logged once across repeated calls."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
helper._fallback_assets()
helper._fallback_assets()
helper._fallback_assets()
mock_logger.warning.assert_called_once()
def test_fallback_assets_warning_not_repeated_across_instances(self):
"""Test the guard is process/module-wide, not per-instance."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper_a = ViteHelper()
helper_b = ViteHelper()
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
helper_a._fallback_assets()
helper_b._fallback_assets()
mock_logger.warning.assert_called_once()
def _write_manifest(static_dir, manifest):
manifest_path = static_dir / "dist" / ".vite" / "manifest.json"
manifest_path.parent.mkdir(parents=True, exist_ok=True)
manifest_path.write_text(json.dumps(manifest), encoding="utf-8")
return manifest_path
def _write_asset(static_dir, relative_path):
asset_path = static_dir / "dist" / relative_path
asset_path.parent.mkdir(parents=True, exist_ok=True)
asset_path.write_text("// built", encoding="utf-8")
return asset_path
def _production_helper(static_dir):
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
helper.manifest = {}
helper._manifest_path = static_dir / "dist" / ".vite" / "manifest.json"
return helper
def _count_reads_and_parses(monkeypatch):
"""Record every manifest `Path.open` and every `json.loads`."""
import local_deep_research.web.utils.vite_helper as vite_helper_module
real_open = Path.open
real_loads = vite_helper_module.json.loads
opens = []
parses = []
def counting_open(path, *args, **kwargs):
opens.append(path)
return real_open(path, *args, **kwargs)
def counting_loads(*args, **kwargs):
parses.append(args)
return real_loads(*args, **kwargs)
monkeypatch.setattr(Path, "open", counting_open)
monkeypatch.setattr(vite_helper_module.json, "loads", counting_loads)
return opens, parses
def _swap_manifest_after_the_first_read(
monkeypatch, manifest_path, replacement
):
"""Replace the manifest on disk the moment its first read returns.
The reader gets the original bytes (served from memory, so the swap
cannot retroactively change what it saw), and every later read sees the
replacement - exactly the ordering a rebuild lands in during startup.
"""
real_open = Path.open
original = manifest_path.read_bytes()
swapped = False
def open_then_swap(path, *args, **kwargs):
nonlocal swapped
if path != manifest_path or swapped:
return real_open(path, *args, **kwargs)
swapped = True
manifest_path.write_bytes(replacement)
return io.BytesIO(original)
monkeypatch.setattr(Path, "open", open_then_swap)
def _assert_fallback_and_banner(helper, stale_url):
assert helper.assets_are_missing() is True
assert stale_url not in str(helper.vite_asset())
assert "Vite build not found" in str(helper.vite_asset())
assert "ldr-vite-missing-assets-banner" in str(
helper.missing_assets_banner()
)
class TestViteHelperRefreshManifestIfStale:
def test_unchanged_bytes_are_reread_but_not_reparsed(
self, tmp_path, monkeypatch
):
"""Catches a revert that re-parses JSON on every healthy request.
The steady-state cost is one bounded read plus a hash. Deleting the
`fingerprint == self._manifest_fingerprint` short-circuit in
`_adopt_manifest_from_disk` makes `json.loads` run per request and
fails the `parses == []` assertion.
"""
manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
_write_manifest(tmp_path, manifest)
_write_asset(tmp_path, "js/app.OLDHASH.js")
helper = _production_helper(tmp_path)
helper._refresh_manifest_if_stale()
opens, parses = _count_reads_and_parses(monkeypatch)
helper._refresh_manifest_if_stale()
assert opens == [helper._manifest_path]
assert parses == []
def test_a_refused_manifest_is_parsed_once_not_once_per_request(
self, tmp_path, monkeypatch
):
"""Catches removal of the rejected-fingerprint backoff.
Adoption is a pure function of the manifest bytes, so re-parsing
bytes already refused cannot change the verdict. Without the
`fingerprint == self._rejected_fingerprint` short-circuit, a broken
build re-parses on every `vite_asset()` *and* every banner call;
with it, 50 renders cost one parse.
"""
manifest_path = _write_manifest(
tmp_path, {"js/app.js": {"file": "js/app.OLDHASH.js"}}
)
manifest_path.write_text("{broken", encoding="utf-8")
helper = _production_helper(tmp_path)
helper._refresh_manifest_if_stale()
_opens, parses = _count_reads_and_parses(monkeypatch)
for _ in range(50):
helper.vite_asset()
helper.missing_assets_banner()
assert parses == []
def test_the_backoff_still_adopts_a_later_valid_rebuild(self, tmp_path):
"""The backoff must not latch: new bytes are always parsed."""
manifest_path = _write_manifest(
tmp_path, {"js/app.js": {"file": "js/app.OLDHASH.js"}}
)
manifest_path.write_text("{broken", encoding="utf-8")
helper = _production_helper(tmp_path)
for _ in range(20):
helper.vite_asset()
_write_manifest(tmp_path, {"js/app.js": {"file": "js/app.NEW.js"}})
_write_asset(tmp_path, "js/app.NEW.js")
assert "js/app.NEW.js" in str(helper.vite_asset())
def test_a_manifest_larger_than_the_read_cap_is_refused(self, tmp_path):
"""Catches a revert to an unbounded `read_bytes()`.
A capped read means an oversized manifest is refused instead of
materialised; the helper degrades rather than allocating whatever
the file happens to contain.
"""
from local_deep_research.web.utils.vite_helper import (
_MAX_MANIFEST_BYTES,
)
manifest_path = _write_manifest(
tmp_path, {"js/app.js": {"file": "js/app.OK.js"}}
)
_write_asset(tmp_path, "js/app.OK.js")
padding = "A" * (_MAX_MANIFEST_BYTES + 1)
manifest_path.write_text(
json.dumps({"js/app.js": {"file": "js/app.OK.js", "pad": padding}}),
encoding="utf-8",
)
helper = _production_helper(tmp_path)
_assert_fallback_and_banner(helper, "js/app.OK.js")
# The refusal has to remember *which* bytes it refused, like every
# other refusal: without it the state is permanently "unknown", so
# nothing downstream can tell a repeat of the same bad file from a
# fresh one, and the backoff that the other refusal paths rely on
# never engages.
assert (
helper._rejected_fingerprint
== hashlib.sha256(
manifest_path.read_bytes()[: _MAX_MANIFEST_BYTES + 1]
).hexdigest()
)
# Deleting the size check does not make this file *servable*: the
# capped read hands `json.loads` a truncated document, which is
# refused as malformed with the identical fingerprint. So the
# markup, the banner and the fingerprint above are all satisfied by
# a helper that has no size check at all. The recorded cause is the
# only thing that distinguishes them.
cause, _location = helper._manifest_failure
assert "read cap" in cause, cause
assert "not valid JSON" not in cause, cause
def test_a_deeply_nested_manifest_degrades_instead_of_raising(
self, tmp_path
):
"""Catches narrowing the parse guard back to `except ValueError`.
`json.loads` raises RecursionError - not a ValueError - on deeply
nested input, so an unguarded parse escapes into template rendering
and turns every page into a 500 instead of a banner.
"""
manifest_path = _write_manifest(
tmp_path, {"js/app.js": {"file": "js/app.OK.js"}}
)
_write_asset(tmp_path, "js/app.OK.js")
manifest_path.write_text(
"[" * 200_000 + "]" * 200_000, encoding="utf-8"
)
helper = _production_helper(tmp_path)
_assert_fallback_and_banner(helper, "js/app.OK.js")
def test_no_filesystem_access_without_a_manifest_path(self):
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
helper.manifest = {}
with patch.object(Path, "open") as mock_open_path:
helper._refresh_manifest_if_stale()
mock_open_path.assert_not_called()
def test_no_filesystem_access_in_dev_mode(self):
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = True
helper._manifest_path = Path("/fake/static/dist/.vite/manifest.json")
with patch.object(Path, "open") as mock_open_path:
helper._refresh_manifest_if_stale()
mock_open_path.assert_not_called()
def test_initial_missing_manifest_recovers_after_a_valid_rebuild(
self, tmp_path
):
helper = _production_helper(tmp_path)
helper._refresh_manifest_if_stale()
_assert_fallback_and_banner(helper, "OLDHASH")
manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
_write_manifest(tmp_path, manifest)
_write_asset(tmp_path, "js/app.NEWHASH.js")
assert "js/app.NEWHASH.js" in str(helper.vite_asset())
assert str(helper.missing_assets_banner()) == ""
def test_vite_asset_reflects_a_valid_rebuild_on_the_next_request(
self, tmp_path
):
old_manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
new_manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
_write_manifest(tmp_path, old_manifest)
_write_asset(tmp_path, "js/app.OLDHASH.js")
helper = _production_helper(tmp_path)
helper._refresh_manifest_if_stale()
_write_manifest(tmp_path, new_manifest)
_write_asset(tmp_path, "js/app.NEWHASH.js")
assert helper.manifest == old_manifest
assert "js/app.NEWHASH.js" in str(helper.vite_asset())
assert helper.manifest == new_manifest
def test_consistent_manifest_without_app_entry_is_refreshed(self, tmp_path):
old_manifest = {"js/other.js": {"file": "js/other.OLDHASH.js"}}
new_manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
_write_manifest(tmp_path, old_manifest)
_write_asset(tmp_path, "js/other.OLDHASH.js")
helper = _production_helper(tmp_path)
helper._refresh_manifest_if_stale()
assert helper.assets_are_missing() is True
_write_manifest(tmp_path, new_manifest)
_write_asset(tmp_path, "js/app.NEWHASH.js")
assert "js/app.NEWHASH.js" in str(helper.vite_asset())
class TestManifestAssetUrlEncoding:
@pytest.mark.parametrize("field", ["file", "css"])
@pytest.mark.parametrize(
"filename",
["chunk?x.js", "chunk#x.js", "chunk%41.js", "chunk name.js", "文.js"],
)
def test_rendered_url_addresses_the_literal_filename(self, field, filename):
"""URL syntax must not change the filename validated on disk.
This checks tag generation with an in-memory manifest: percent
decoding the emitted path once must recover the exact filename,
with no query or fragment and no duplicated encoding.
"""
import re
from urllib.parse import unquote, urlsplit
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
entry = (
{"file": filename}
if field == "file"
else {"file": "app.js", "css": [filename]}
)
helper.manifest = {"js/app.js": entry}
html = str(helper.vite_asset())
attribute = "src" if field == "file" else "href"
match = re.search(rf'{attribute}="([^"]+)"', html)
assert match is not None, html
url = urlsplit(match.group(1))
assert url.query == ""
assert url.fragment == ""
assert unquote(url.path) == f"/static/dist/{filename}"
class TestManifestSnapshotCoherence:
def test_the_stored_fingerprint_describes_the_bytes_held_in_memory(
self, tmp_path, monkeypatch
):
"""Catches any revert that fingerprints the file, not the bytes read.
The startup read returns manifest A and the file becomes B before the
fingerprint is taken. The invariant asserted here is the one that
makes staleness detection work at all: `_manifest_fingerprint` is
sha256(A) - the bytes actually in `self.manifest` - *not* sha256(B),
the file's current content. Re-deriving the fingerprint from a second
read or a stat (the shape this helper had before) stores B's key
alongside A's data, and the next refresh sees "unchanged" and latches
OLDHASH forever, which the follow-up assertions then catch.
"""
from local_deep_research.web.utils.vite_helper import ViteHelper
old_manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
new_manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
manifest_path = _write_manifest(tmp_path, old_manifest)
_write_asset(tmp_path, "js/app.OLDHASH.js")
_write_asset(tmp_path, "js/app.NEWHASH.js")
original = json.dumps(old_manifest).encode("utf-8")
replacement = json.dumps(new_manifest).encode("utf-8")
assert manifest_path.read_bytes() == original
_swap_manifest_after_the_first_read(
monkeypatch, manifest_path, replacement
)
helper = ViteHelper()
helper.app = Mock(config={"STATIC_DIR": str(tmp_path)})
helper._load_manifest()
# The replacement has already landed on disk, but startup adopted A.
assert manifest_path.read_bytes() == replacement
assert helper.manifest == old_manifest
assert (
helper._manifest_fingerprint == hashlib.sha256(original).hexdigest()
)
helper._refresh_manifest_if_stale()
assert helper.manifest == new_manifest
assert (
helper._manifest_fingerprint
== hashlib.sha256(replacement).hexdigest()
)
assert "js/app.NEWHASH.js" in str(helper.vite_asset())
class TestConcurrentManifestReplacement:
"""A rebuild landing mid-render must not poison the next render."""
def test_a_manifest_swapped_mid_validation_cannot_poison_the_memo(
self, tmp_path, monkeypatch
):
"""Catches splitting the snapshot back into separate attributes.
`vite_asset()` renders from a manifest, asks whether that manifest's
entry is servable, and records the answer. While those three lived
in separate attributes, a refresh landing between the render's
snapshot and the verdict's memo key stored a *positive* verification
of manifest A under manifest B's fingerprint - after which B was
served with validation skipped, durably, until its bytes changed
again. The interleaving is forced through a monkeypatched hook, not
timing, so this is deterministic rather than a stress test.
B is deliberately a manifest that *renders*: its entry is an object
with a perfectly good `file` string, pointing at a chunk that is not
on disk. A B whose entry merely lacked `file` would be caught by the
render path's own `.get("file")` guard even with the memo poisoned,
so it could not tell a coherent snapshot apart from a bad one. With
this B, the only thing standing between the poisoned memo and a
`<script>` tag naming a file that does not exist is verifying B for
itself.
"""
from local_deep_research.web.utils.vite_helper import ViteHelper
manifest_a = {"js/app.js": {"file": "js/app.AAA.js"}}
manifest_b = {"js/app.js": {"file": "js/app.MISSING.js"}}
_write_manifest(tmp_path, manifest_a)
_write_asset(tmp_path, "js/app.AAA.js")
# js/app.MISSING.js is deliberately never written.
helper = _production_helper(tmp_path)
real_entry_problem = ViteHelper._entry_problem
swapped = threading.Event()
def swap_then_validate(self, *args, **kwargs):
# Runs in the render thread once `vite_asset()` has taken the
# snapshot it will render from (A) and before that snapshot is
# verified. A second thread publishes B here, and this returns
# only once it has.
if not swapped.is_set():
swapped.set()
def rewriter():
_write_manifest(tmp_path, manifest_b)
helper._refresh_manifest_if_stale()
rewriter_thread = threading.Thread(
target=rewriter, name="manifest-rewriter"
)
rewriter_thread.start()
rewriter_thread.join()
return real_entry_problem(self, *args, **kwargs)
monkeypatch.setattr(ViteHelper, "_entry_problem", swap_then_validate)
rendered = []
render_thread = threading.Thread(
target=lambda: rendered.append(str(helper.vite_asset("js/app.js"))),
name="render",
)
render_thread.start()
render_thread.join()
# The render that verified A serves A: its tag names a file that the
# manifest it rendered from actually defines.
assert rendered, "the render thread raised before producing markup"
assert "js/app.AAA.js" in rendered[0]
assert helper.manifest == manifest_b
# The next render sees B, and must verify B for itself. A memo
# attributed to the wrong manifest serves B's dangling URL here,
# with no banner and no warning.
html = str(helper.vite_asset("js/app.js"))
assert "Vite build not found" in html
assert "js/app.MISSING.js" not in html
assert "js/app.AAA.js" not in html
assert "<script" not in html
assert helper.assets_are_missing() is True
def test_a_rewritten_manifest_is_reverified_not_served_from_the_old_memo(
self, tmp_path
):
"""Catches hoisting `verified_entries` off the state onto `self`.
The sequential half of the pair above: no threads, no forced
interleaving, just a manifest rewritten between two renders. The
memo lives on the state, so the new state starts with an empty one
and the new manifest is walked for itself. Hoisted onto the helper
it survives the state swap, `js/app.js` is still "verified", and the
second render serves a chunk that was never flushed - the exact
stale URL this PR exists to stop.
"""
_write_manifest(tmp_path, {"js/app.js": {"file": "js/app.AAA.js"}})
_write_asset(tmp_path, "js/app.AAA.js")
helper = _production_helper(tmp_path)
assert "js/app.AAA.js" in str(helper.vite_asset("js/app.js"))
assert helper.assets_are_missing() is False
# New bytes; js/app.BBB.js is deliberately never written.
_write_manifest(tmp_path, {"js/app.js": {"file": "js/app.BBB.js"}})
html = str(helper.vite_asset("js/app.js"))
assert "Vite build not found" in html
assert "js/app.BBB.js" not in html
assert "<script" not in html
assert helper.assets_are_missing() is True
def test_an_asset_deleted_after_verification_is_noticed_in_the_window(
self, tmp_path, monkeypatch
):
"""Catches a memo that outlives the files it verified.
Nothing rewrites `manifest.json` when a chunk is deleted from
`dist/`, so the bytes-changed invalidation never fires and a
verification recorded once would otherwise stand for the life of the
process: `assets_are_missing()` keeps saying False and the page
keeps carrying a `<script>` tag for a file that is gone. Each
positive result is therefore stamped and re-checked once it is older
than `_VERIFICATION_TTL_SECONDS`.
The clock is faked rather than slept on, and the window is pinned at
both ends: a midpoint, a point just under the TTL, and the TTL
boundary itself. The comparison in `_entry_problem()` is a strict
`<` (delta against `_VERIFICATION_TTL_SECONDS`), so a memo taken at
t=0 must still answer at a delta just under the TTL and must be
re-checked at a delta exactly equal to it; a `<` -> `<=` regression
would keep answering from the memo at the exact boundary too, and
only the boundary step below would catch that.
"""
import local_deep_research.web.utils.vite_helper as vite_helper_module
clock = {"now": 1000.0}
monkeypatch.setattr(
vite_helper_module, "_monotonic", lambda: clock["now"]
)
_write_manifest(tmp_path, {"js/app.js": {"file": "js/app.OK.js"}})
asset = _write_asset(tmp_path, "js/app.OK.js")
helper = _production_helper(tmp_path)
verified_at = clock["now"]
assert "js/app.OK.js" in str(helper.vite_asset("js/app.js"))
assert helper.assets_are_missing() is False
# manifest.json is untouched: same bytes, same hash, same state.
asset.unlink()
ttl = vite_helper_module._VERIFICATION_TTL_SECONDS
clock["now"] = verified_at + ttl / 2
assert helper.assets_are_missing() is False
# Just under the TTL: still memoised, deletion not yet surfaced.
clock["now"] = verified_at + ttl - 0.001
assert helper.assets_are_missing() is False
# Exactly at the TTL: the strict `<` must treat the memo as expired.
clock["now"] = verified_at + ttl
_assert_fallback_and_banner(helper, "js/app.OK.js")
def test_a_verified_entry_without_a_file_string_still_falls_back(
self, monkeypatch
):
"""Catches reverting `file_info.get("file")` to `file_info["file"]`.
Validation and rendering are two separate reads of the same dict, so
the render path may not treat the verdict as a guarantee about what
it is about to subscript. With a bare subscript an entry that has no
'file' key raises KeyError out of Jinja - a 500 on every page,
instead of the degraded page the banner exists for.
"""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
helper.manifest = {"js/app.js": {"css": ["css/app.css"]}}
monkeypatch.setattr(
ViteHelper, "_entry_problem", lambda *args, **kwargs: None
)
html = str(helper.vite_asset("js/app.js"))
assert "Vite build not found" in html
assert "<script" not in html
assert "<link" not in html
class TestContentChangeDetection:
def test_equal_size_same_mtime_rewrite_is_adopted(self, tmp_path):
old_manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
new_manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
old_bytes = json.dumps(old_manifest).encode("utf-8")
new_bytes = json.dumps(new_manifest).encode("utf-8")
assert len(old_bytes) == len(new_bytes)
manifest_path = _write_manifest(tmp_path, old_manifest)
_write_asset(tmp_path, "js/app.OLDHASH.js")
helper = _production_helper(tmp_path)
helper._refresh_manifest_if_stale()
original_stat = manifest_path.stat()
_write_asset(tmp_path, "js/app.NEWHASH.js")
manifest_path.write_bytes(new_bytes)
os.utime(
manifest_path,
ns=(original_stat.st_atime_ns, original_stat.st_mtime_ns),
)
rewritten_stat = manifest_path.stat()
assert (
rewritten_stat.st_mtime_ns,
rewritten_stat.st_size,
) == (original_stat.st_mtime_ns, original_stat.st_size)
helper._refresh_manifest_if_stale()
assert helper.manifest == new_manifest
assert "js/app.NEWHASH.js" in str(helper.vite_asset())
class TestFailClosedOnUnusableManifest:
def test_deleted_manifest_drops_old_urls_and_recovers(self, tmp_path):
old_manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
new_manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
manifest_path = _write_manifest(tmp_path, old_manifest)
old_asset = _write_asset(tmp_path, "js/app.OLDHASH.js")
helper = _production_helper(tmp_path)
helper._refresh_manifest_if_stale()
manifest_path.unlink()
old_asset.unlink()
_assert_fallback_and_banner(helper, "OLDHASH")
_write_manifest(tmp_path, new_manifest)
_write_asset(tmp_path, "js/app.NEWHASH.js")
assert "js/app.NEWHASH.js" in str(helper.vite_asset())
def test_malformed_manifest_drops_old_urls_and_recovers(self, tmp_path):
old_manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
new_manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
manifest_path = _write_manifest(tmp_path, old_manifest)
_write_asset(tmp_path, "js/app.OLDHASH.js")
helper = _production_helper(tmp_path)
helper._refresh_manifest_if_stale()
old_fingerprint = helper._manifest_fingerprint
manifest_path.write_text("{broken", encoding="utf-8")
_assert_fallback_and_banner(helper, "OLDHASH")
# The adopted fingerprint is dropped with the manifest it described;
# the refused bytes are remembered separately, which is what stops
# the degraded path re-parsing them on every request.
assert helper._manifest_fingerprint is None
assert helper._rejected_fingerprint not in (None, old_fingerprint)
_write_manifest(tmp_path, new_manifest)
_write_asset(tmp_path, "js/app.NEWHASH.js")
assert "js/app.NEWHASH.js" in str(helper.vite_asset())
def test_incomplete_manifest_drops_old_urls_and_recovers(self, tmp_path):
old_manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
incomplete_manifest = {
"js/app.js": {
"file": "js/app.NEWHASH.js",
"css": ["css/app.NEWHASH.css"],
}
}
_write_manifest(tmp_path, old_manifest)
_write_asset(tmp_path, "js/app.OLDHASH.js")
helper = _production_helper(tmp_path)
helper._refresh_manifest_if_stale()
_write_manifest(tmp_path, incomplete_manifest)
_write_asset(tmp_path, "js/app.NEWHASH.js")
_assert_fallback_and_banner(helper, "OLDHASH")
_write_asset(tmp_path, "css/app.NEWHASH.css")
assert "js/app.NEWHASH.js" in str(helper.vite_asset())
class TestRequestedEntryConsistency:
"""Validation is scoped to the closure of the entry actually asked for."""
def test_an_unrelated_entry_missing_from_disk_still_serves_app_js(
self, tmp_path
):
"""Catches re-widening validation to every manifest entry.
The real manifest carries 67 top-level entries, 65 of them fonts
that no template ever passes to `vite_asset()`. Validating all of
them all-or-nothing turns one missing font - a single 404 on `main`
- into an empty manifest, a blank page and a red banner. Only the
requested entry's own closure may gate it.
"""
manifest = {
"js/app.js": {
"file": "js/app.OKHASH.js",
"css": ["css/app.OKHASH.css"],
"imports": ["_vendor.js"],
},
"_vendor.js": {"file": "js/vendor.OKHASH.js"},
"fonts/fa-solid-900.ttf": {
"file": "fonts/fa-solid-900.MISSING.ttf"
},
}
_write_manifest(tmp_path, manifest)
_write_asset(tmp_path, "js/app.OKHASH.js")
_write_asset(tmp_path, "css/app.OKHASH.css")
_write_asset(tmp_path, "js/vendor.OKHASH.js")
helper = _production_helper(tmp_path)
html = str(helper.vite_asset("js/app.js"))
assert "js/app.OKHASH.js" in html
assert "css/app.OKHASH.css" in html
assert str(helper.missing_assets_banner()) == ""
assert helper.assets_are_missing() is False
def test_the_unrelated_entry_is_still_refused_when_it_is_requested(
self, tmp_path
):
"""Scoping must not become "never check": asking for it still fails."""
manifest = {
"js/app.js": {"file": "js/app.OKHASH.js"},
"fonts/fa-solid-900.ttf": {
"file": "fonts/fa-solid-900.MISSING.ttf"
},
}
_write_manifest(tmp_path, manifest)
_write_asset(tmp_path, "js/app.OKHASH.js")
helper = _production_helper(tmp_path)
html = str(helper.vite_asset("fonts/fa-solid-900.ttf"))
assert "Vite build not found" in html
assert "<script" not in html
assert "<link" not in html
def test_primary_file_missing_degrades_until_the_chunk_is_flushed(
self, tmp_path
):
"""Catches removing the existence check on the entry's own `file`.
Vite writes manifest.json before every hashed chunk is flushed, so an
entry pointing at a file that is not there yet must degrade - and
must recover on the very next call once it lands, which only works
because negative results are not cached.
"""
manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
_write_manifest(tmp_path, manifest)
helper = _production_helper(tmp_path)
_assert_fallback_and_banner(helper, "NEWHASH")
_write_asset(tmp_path, "js/app.NEWHASH.js")
assert "js/app.NEWHASH.js" in str(helper.vite_asset())
def test_missing_css_makes_the_requested_entry_unservable(self, tmp_path):
"""Catches dropping `css` from the per-entry closure walk.
Without it the entry is served with a <link> to a stylesheet that
404s - a styled-looking tag pointing at nothing.
"""
manifest = {
"js/app.js": {
"file": "js/app.OKHASH.js",
"css": ["css/app.MISSING.css"],
}
}
_write_manifest(tmp_path, manifest)
_write_asset(tmp_path, "js/app.OKHASH.js")
helper = _production_helper(tmp_path)
_assert_fallback_and_banner(helper, "app.OKHASH.js")
def test_dangling_import_reference_is_rejected(self, tmp_path):
manifest = {
"js/app.js": {
"file": "js/app.OKHASH.js",
"imports": ["js/missing.js"],
}
}
_write_manifest(tmp_path, manifest)
_write_asset(tmp_path, "js/app.OKHASH.js")
helper = _production_helper(tmp_path)
_assert_fallback_and_banner(helper, "app.OKHASH.js")
def test_an_unflushed_static_import_is_rejected(self, tmp_path):
"""A chunk the entry needs up front still gates the whole entry."""
manifest = {
"js/app.js": {
"file": "js/app.OKHASH.js",
"imports": ["js/vendor.js"],
},
"js/vendor.js": {"file": "js/vendor.MISSING.js"},
}
_write_manifest(tmp_path, manifest)
_write_asset(tmp_path, "js/app.OKHASH.js")
helper = _production_helper(tmp_path)
_assert_fallback_and_banner(helper, "app.OKHASH.js")
def test_an_unflushed_lazy_chunk_warns_but_still_serves_the_page(
self, tmp_path
):
"""Catches putting `dynamicImports` back in the blocking closure.
The shipped `js/app.js` entry lazily imports a canvg chunk that only
the diagram-export path ever pulls in. Gating the entry on it means
one unflushed lazy chunk renders the login form as a red banner -
the app is unreachable over a feature nobody on that page uses. The
chunk is still validated, and the operator is still told once; the
blast radius is the one feature, not the whole UI.
"""
manifest = {
"js/app.js": {
"file": "js/app.OKHASH.js",
"dynamicImports": ["js/lazy.js"],
},
"js/lazy.js": {"file": "js/lazy.MISSING.js"},
}
_write_manifest(tmp_path, manifest)
_write_asset(tmp_path, "js/app.OKHASH.js")
helper = _production_helper(tmp_path)
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
html = str(helper.vite_asset("js/app.js"))
assert "js/app.OKHASH.js" in html
assert "Vite build not found" not in html
assert str(helper.missing_assets_banner()) == ""
assert helper.assets_are_missing() is False
mock_logger.warning.assert_called_once()
(message,), _ = mock_logger.warning.call_args
assert "js/lazy.MISSING.js" in message
assert "on demand" in message
def test_a_dangling_lazy_reference_warns_but_still_serves_the_page(
self, tmp_path
):
"""A `dynamicImports` name the manifest never defines is advisory too."""
manifest = {
"js/app.js": {
"file": "js/app.OKHASH.js",
"dynamicImports": ["js/nowhere.js"],
}
}
_write_manifest(tmp_path, manifest)
_write_asset(tmp_path, "js/app.OKHASH.js")
helper = _production_helper(tmp_path)
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
html = str(helper.vite_asset("js/app.js"))
assert "js/app.OKHASH.js" in html
mock_logger.warning.assert_called_once()
(message,), _ = mock_logger.warning.call_args
assert "js/nowhere.js" in message
def test_cyclic_imports_are_validated_once_and_served(self, tmp_path):
"""Catches dropping the `visited` set: a cycle would hang forever.
"Hang forever" is why the walk runs on a worker thread with a
bounded `join()`: without `visited` this test would not fail, it
would never return, and a hung worker takes the whole suite with it
instead of reporting one red test. The thread is a daemon so the
interpreter can still exit if the assertion below trips.
"""
manifest = {
"js/app.js": {
"file": "js/app.OKHASH.js",
"imports": ["js/vendor.js"],
},
"js/vendor.js": {
"file": "js/vendor.OKHASH.js",
"dynamicImports": ["js/app.js"],
},
}
_write_manifest(tmp_path, manifest)
_write_asset(tmp_path, "js/app.OKHASH.js")
_write_asset(tmp_path, "js/vendor.OKHASH.js")
helper = _production_helper(tmp_path)
helper._refresh_manifest_if_stale()
assert helper.manifest == manifest
verdicts = []
walker = threading.Thread(
target=lambda: verdicts.append(helper.assets_are_missing()),
name="closure-walk",
daemon=True,
)
walker.start()
walker.join(timeout=30)
assert not walker.is_alive(), (
"the closure walk did not terminate on a cycle"
)
assert verdicts == [False]
def test_path_outside_dist_is_rejected(self, tmp_path):
"""Catches dropping the `is_relative_to(dist_root)` containment check.
`..`-escaping and symlinked targets must not become servable URLs
just because the file happens to exist.
"""
manifest = {"js/app.js": {"file": "../escaped.js"}}
_write_manifest(tmp_path, manifest)
escaped = tmp_path / "escaped.js"
escaped.write_text("// outside dist", encoding="utf-8")
helper = _production_helper(tmp_path)
_assert_fallback_and_banner(helper, "escaped.js")
def test_an_absolute_path_into_dist_is_rejected(self, tmp_path):
"""Catches accepting an absolute manifest path that lands in dist/.
`dist_root / "/srv/app/static/dist/js/app.js"` is the absolute path
itself (pathlib lets the absolute operand win), so containment and
`is_file()` both pass - and the value is then pasted into
`src="/static/dist/<path>"`, publishing the server's filesystem
layout to every visitor on a URL that 404s anyway.
"""
served = tmp_path / "dist" / "js" / "app.OKHASH.js"
served.parent.mkdir(parents=True, exist_ok=True)
served.write_text("// built", encoding="utf-8")
_write_manifest(tmp_path, {"js/app.js": {"file": str(served)}})
helper = _production_helper(tmp_path)
html = str(helper.vite_asset("js/app.js"))
assert "Vite build not found" in html
assert str(tmp_path) not in html
assert "<script" not in html
@pytest.mark.parametrize(
"manifest_file_value",
[
"js/app.OKHASH.js/", # trailing separator
"js//app.OKHASH.js", # empty segment
"js/app.OKHASH.js/.", # '.' segment
"./js/app.OKHASH.js", # leading '.' segment
"js/../js/app.OKHASH.js", # '..' segment that stays inside
],
)
def test_an_unnormalised_path_is_rejected(
self, tmp_path, manifest_file_value
):
"""Catches accepting paths pathlib normalises but a URL does not.
Every value here resolves to the same real file inside `dist/`, so
containment and `is_file()` both pass - and then the raw string is
pasted into `src="/static/dist/<path>"`, where it is not the URL of
the file that was just verified. `js/app.OKHASH.js/` renders a
trailing slash, `js//app.OKHASH.js` renders a doubled separator, and
the dot segments render paths a static handler is under no
obligation to fold. All 404 while the check says "verified".
"""
_write_manifest(tmp_path, {"js/app.js": {"file": manifest_file_value}})
_write_asset(tmp_path, "js/app.OKHASH.js")
helper = _production_helper(tmp_path)
_assert_fallback_and_banner(helper, "app.OKHASH.js")
def test_the_normalised_form_of_that_path_is_still_served(self, tmp_path):
"""The rejection above must be about the shape, not the file.
Without this row, rejecting every path unconditionally passes the
parametrised test.
"""
_write_manifest(tmp_path, {"js/app.js": {"file": "js/app.OKHASH.js"}})
_write_asset(tmp_path, "js/app.OKHASH.js")
helper = _production_helper(tmp_path)
assert "js/app.OKHASH.js" in str(helper.vite_asset("js/app.js"))
assert helper.assets_are_missing() is False
class TestRefusedManifestIsReported:
"""A manifest that exists but is refused must not be silent or misdescribed."""
def test_a_refused_manifest_warns_and_names_the_file(self, tmp_path):
"""Catches a silent `_fail_closed()`.
Deleting the warning from `_fail_closed` (or gating the startup
warning on `manifest_path.exists()` again) leaves a present-but-
unusable manifest logging nothing at all, and the render-time
fallback then blames a file that is sitting right there.
"""
manifest_path = _write_manifest(
tmp_path, {"js/app.js": {"file": "js/app.OK.js"}}
)
manifest_path.write_text("{broken", encoding="utf-8")
helper = _production_helper(tmp_path)
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
markup = str(helper.vite_asset("js/app.js"))
mock_logger.warning.assert_called_once()
(message,), _ = mock_logger.warning.call_args
assert str(manifest_path) in message
assert "not valid JSON" in message
assert "manifest not found" not in message
# The rendered comment says the manifest was refused rather than
# blaming a file that is sitting right there - and, unlike the log,
# it carries neither the server's filesystem layout nor any
# manifest-controlled text into every visitor's HTML.
assert "read and refused" in markup
assert str(manifest_path) not in markup
assert str(tmp_path) not in markup
def test_a_repeated_failure_warns_once_per_distinct_cause(self, tmp_path):
"""Catches a revert to the single-boolean "already warned" flag.
With one process-wide boolean the first transient burns the only
warning and every later, different failure is silent forever.
Arrays and empty objects share one rejection cause, so changing
between them must not warn again; removing the file is a distinct
cause and must produce another warning.
"""
manifest_path = _write_manifest(
tmp_path, {"js/app.js": {"file": "js/app.OK.js"}}
)
manifest_path.write_text("{broken", encoding="utf-8")
helper = _production_helper(tmp_path)
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
for _ in range(5):
helper.vite_asset("js/app.js")
assert mock_logger.warning.call_count == 1
manifest_path.write_text("[1, 2, 3]", encoding="utf-8")
helper.vite_asset("js/app.js")
assert mock_logger.warning.call_count == 2
manifest_path.write_text("{}", encoding="utf-8")
helper.vite_asset("js/app.js")
assert mock_logger.warning.call_count == 2
manifest_path.unlink()
helper.vite_asset("js/app.js")
assert mock_logger.warning.call_count == 3
messages = [call.args[0] for call in mock_logger.warning.call_args_list]
assert "not valid JSON" in messages[0]
assert "not a non-empty JSON object" in messages[1]
assert "no readable manifest file" in messages[2]
def test_an_unservable_entry_names_the_file_that_is_missing(self, tmp_path):
"""Catches dropping the reason from the entry-level warning."""
_write_manifest(tmp_path, {"js/app.js": {"file": "js/app.GONE.js"}})
helper = _production_helper(tmp_path)
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
helper.vite_asset("js/app.js")
mock_logger.warning.assert_called_once()
(message,), _ = mock_logger.warning.call_args
assert "manifest entry" in message
assert "js/app.js" in message
assert "js/app.GONE.js" in message
class TestManifestDerivedTextInTheLog:
"""What a manifest says must not decide how much of the log it owns."""
def test_churning_manifest_bytes_warn_once_not_once_per_render(
self, tmp_path
):
"""Catches putting the fingerprint back in the warning's cause key.
A manifest being rewritten with fresh garbage yields new bytes on
every render and the *same* operator problem. Keying "warn once" on
the bytes turns one warning into one per render, which buries every
other line in the log; the fingerprint belongs in the message, where
it identifies the snapshot without multiplying the records.
"""
manifest_path = tmp_path / "dist" / ".vite" / "manifest.json"
manifest_path.parent.mkdir(parents=True, exist_ok=True)
helper = _production_helper(tmp_path)
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
for index in range(300):
manifest_path.write_text(
"{broken " + "x" * index, encoding="utf-8"
)
helper.vite_asset("js/app.js")
mock_logger.warning.assert_called_once()
(message,), _ = mock_logger.warning.call_args
assert "not valid JSON" in message
assert "sha256" in message
def test_a_manifest_key_cannot_forge_a_second_log_line(self, tmp_path):
"""Catches interpolating manifest-supplied text into a log record raw.
manifest.json is not written by this process. A key containing a
newline splices a second, fabricated record into the log that no
aggregator can tell apart from a real one - so the text is escaped,
not dropped: the operator still sees what the manifest actually
said.
"""
forged = "js/app.js\nERROR | totally-real-log-line"
_write_manifest(
tmp_path,
{
"js/app.js": {
"file": "js/app.OKHASH.js",
"imports": [forged],
},
forged: {},
},
)
_write_asset(tmp_path, "js/app.OKHASH.js")
helper = _production_helper(tmp_path)
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
helper.vite_asset("js/app.js")
mock_logger.warning.assert_called_once()
(message,), _ = mock_logger.warning.call_args
assert "\n" not in message
assert "\r" not in message
assert "totally-real-log-line" in message
class TestViteAssetWarningIntegration:
"""End-to-end coverage of vite_asset()'s warning/banner behavior.
"End-to-end" here means template-global to markup, not manifest file to
markup: like `TestViteHelperViteAsset` these helpers have no
``_manifest_path``, so they exercise only the no-`dist_root` path and no
file is ever read or checked. The disk-backed equivalents are in
`TestRefusedManifestIsReported` and `TestRequestedEntryConsistency`.
"""
def test_manifest_present_no_banner_no_warning(self):
"""Normal production path: no banner, no warning."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
helper.manifest = {
"js/app.js": {
"file": "assets/app-abc123.js",
"css": ["assets/app-abc123.css"],
}
}
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
result = helper.vite_asset("js/app.js")
result_str = str(result)
assert "assets/app-abc123.js" in result_str
assert "ldr-vite-missing-assets-banner" not in result_str
mock_logger.warning.assert_not_called()
def test_manifest_missing_shows_banner_and_warns(self):
"""No manifest at all: fallback markup returned and warning logged."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
helper.manifest = {}
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
result = helper.vite_asset("js/app.js")
assert "Vite build not found" in str(result)
mock_logger.warning.assert_called_once()
# Manifest file itself is missing - operator must rebuild everything,
# so the message names the manifest, not a specific entry.
(message,), _ = mock_logger.warning.call_args
assert "manifest not found" in message
assert "manifest entry" not in message
def test_manifest_missing_entry_shows_banner_and_warns(self):
"""Manifest exists but lacks the requested entry: fallback + warning."""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = False
helper.manifest = {"other/file.js": {"file": "assets/other.js"}}
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
result = helper.vite_asset("js/app.js")
assert "Vite build not found" in str(result)
mock_logger.warning.assert_called_once()
# Manifest exists but the requested entry is absent - the message
# must name the specific entry so the operator knows what's missing.
(message,), _ = mock_logger.warning.call_args
assert "manifest entry" in message
assert "js/app.js" in message
assert "manifest not found" not in message
def test_dev_server_mode_never_warns_even_without_manifest(self):
"""Dev-server mode is a legitimate no-manifest state - must stay silent.
In dev mode `vite_asset()` returns the Vite dev-server URL directly
and never consults the manifest, so the "assets not built" warning
(which only makes sense for the production/manifest path) must never
fire here, even though `self.manifest` is None/unset just like the
"never built" case.
"""
from local_deep_research.web.utils.vite_helper import ViteHelper
helper = ViteHelper()
helper.is_dev = True
helper.manifest = None
with patch(
"local_deep_research.web.utils.vite_helper.logger"
) as mock_logger:
result = helper.vite_asset("js/app.js")
result_str = str(result)
assert "localhost:5173" in result_str
assert "ldr-vite-missing-assets-banner" not in result_str
mock_logger.warning.assert_not_called()
class TestViteSingleton:
"""Tests for the singleton vite instance."""
def test_singleton_is_vite_helper_instance(self):
"""Test that singleton is a ViteHelper instance."""
from local_deep_research.web.utils.vite_helper import vite, ViteHelper
assert isinstance(vite, ViteHelper)